Entertainment
Show HN: MCP Memory – Fast Agent Memory Using Google's OKF and SQLite FTS5
Key Points
MCP-Memory is a Model Context Protocol (MCP) server that equips AI agents (such as Claude Desktop, Cursor, Antigravity, Windsurf, or Codex) with persistent, long-term memory capabilities. Memory records are formatted using the Open Knowledge Format (OKF v0.2) standard and indexed with a local SQLite instance (supporting FTS5 full-text search) for fast key-value lookups, tag filtering, and content search. Fast Track: Jump directly to Quick Start - Persistent State Across Sessions:
MCP-Memory is a Model Context Protocol (MCP) server that equips AI agents (such as Claude Desktop, Cursor, Antigravity, Windsurf, or Codex) with persistent, long-term memory capabilities.
Memory records are formatted using the Open Knowledge Format (OKF v0.2) standard and indexed with a local SQLite instance (supporting FTS5 full-text search) for fast key-value lookups, tag filtering, and content search.
Fast Track: Jump directly to Quick Start
- Persistent State Across Sessions: Enables AI agents to read, store, search, and delete stateful memory snippets that persist across chat turns and sessions.
- OKF Standard Compliance: Stores every memory item formatted as an OKF v0.2 Markdown document with YAML frontmatter (
type
,key
,namespace
,tags
,generated
,sources
,verified
,status
,stale_after
), adhering strictly toSPEC.md
andOKF_RULES.md
. - Dual-Layer Architecture:
- Human-Browseable OKF Directory: Automatically dumps and syncs every memory to disk as a raw
.md
file inside thememory/
bundle directory with hierarchicalindex.md
progressive disclosure files (rootindex.md
versioned withokf_version: "0.2"
) andlog.md
update history tracking. - High-Performance SQLite Indexing: SQLite FTS5 (Full-Text Search) and automatic triggers for sub-20ms key lookups and instant keyword searches.
- Human-Browseable OKF Directory: Automatically dumps and syncs every memory to disk as a raw
- Namespace Isolation: Supports contextual separation (e.g.
user/preferences
,project/architecture
,default
). - Zero Boilerplate Setup: Quick setup wizard (
python3 setup.py
) auto-configures installed MCP tools (Antigravity, Claude, Cursor, Windsurf, Codex).
The server exposes four primary MCP tools to interacting agents:
Stores or updates a memory record in OKF v0.2 format.
- Parameters:
key
(string, required): Unique identifier or path for the memory (e.g.user/preferences/coding_style
orproject/architecture
).content
(string or object, required): Core information to store.project_root
(string, required): Absolute path to the active project root directory (e.g./Users/user/Projects/my-app
).tags
(array of strings, optional): Classification tags for filtering.namespace
(string, optional, default:"default"
): Scope/namespace.concept_type
(string, optional, default:"Agent Memory"
): OKF concept type (e.g.Metric
,Playbook
,Attested Computation
).title
(string, optional): Display name.description
(string, optional): One-line summary.resource
(string, optional): Canonical URI of underlying asset.status
(string, optional, default:"stable"
): Lifecycle state (draft
|stable
|deprecated
).stale_after
(string, optional): ISO date (YYYY-MM-DD
).sources
(array of objects, optional): Provenance sources[{resource, id, title, author, usage_count, last_modified}]
.verified
(array of objects or object, optional): Verification events[{by, at}]
.generated_by
(string, optional): Actor identifier following actor convention (/
,human:
,process:
).
Retrieves a specific memory by its key and namespace.
- Parameters:
key
(string, required): The memory key to look up.project_root
(string, required): Absolute path to the active project root directory.namespace
(string, optional, default:"default"
): Scope/namespace.
Finds memories matching keywords, tags, or namespace filters.
- Parameters:
project_root
(string, required): Absolute path to the active project root directory.query
(string, optional): Keyword search query across keys, frontmatter, and content.tags
(array of strings, optional): Filter by specific tags.namespace
(string, optional): Scope search to a namespace.limit
(integer, optional, default: 10): Maximum number of results.
AGENT DIRECTIVE (Session Start): Retrieves the last recorded session checkpoint (system/last_memory
) so the AI agent immediately knows where work was left off when opening a project or starting a session.
- Parameters:
project_root
(string, required): Absolute path to active project root directory.namespace
(string, optional, default:"default"
): Scope/namespace.
AGENT DIRECTIVE (Milestones & Progress): Updates the canonical session checkpoint (system/last_memory
) whenever completing a milestone, making key changes, or pausing work.
- Parameters:
content
(string or object, required): Brief note or structured dictionary summarizing progress and referencing key memory files.project_root
(string, required): Absolute path to active project root directory.namespace
(string, optional, default:"default"
): Scope/namespace.summary
(string, optional): One-sentence description of the milestone achieved.
Every stored memory strictly adheres to the OKF v0.2 specification (SPEC.md
& OKF_RULES.md
):
---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
- preferences
- style
status: stable
generated:
by: mcp-memory/0.2.0
at: '2026-08-12T19:23:35Z'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.
git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory
Run setup.py
to auto-detect and register mcp-memory
with your AI tools:
python3 setup.py
Note: Once
setup.py
finishes configuring your tools, your AI client will launchmcp-memory
automatically in the background whenever needed. You do not need to manually start or keep a server process running in your terminal.
If you want to manually verify startup, inspect stdio output, or pre-initialize the virtual environment (.venv
), you can run run.sh
directly:
./run.sh
If you prefer to configure your MCP client manually, add the "memory"
server entry pointing to run.sh
:
Add to your client's mcp_config.json
or claude_desktop_config.json
:
{
"mcpServers": {
"memory": {
"command": "/ABSOLUTE/PATH/TO/run.sh"
}
}
}
Add to ~/.codex/config.toml
:
[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"
- Claude Code CLI:
claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
- Codex CLI:
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh
Run the automated test suite to verify OKF serialization, SQLite database operations, and FastMCP tool execution:
python3 test_memory.py
By default, mcp-memory
creates project-isolated memory stores inside each project's root directory:
- OKF Markdown Files (Human-readable):
memory/
folder in project root. - SQLite Database (Hidden index):
.mcp_memory/memories.db
in project root.
You can customize this behavior using environment variables:
MCP_MEMORY_PROJECT_ROOT
: Project root directory (default: process current working directorycwd
).MCP_MEMORY_DB_PATH
: SQLite database file path (default:.mcp_memory/memories.db
relative to project root).MCP_MEMORY_DIR
: Directory for Open Knowledge Format (OKF).md
files (default:memory
relative to project root).
Tip: If you prefer a single global memory store shared across all projects, set
MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db
andMCP_MEMORY_DIR=~/.mcp_memory/memory
in your client's MCP configuration.