Show HN: MCP Memory – Fast Agent Memory Using Google's OKF and SQLite FTS5

MCP-Memory: OKF-Backed Agent Memory Server 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 Fast Track: Jump directly to Quick Start Key Features 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 to SPEC.md and OKF_RULES.md. Dual-Layer Architecture: Human-Browseable OKF Directory: Automatically dumps and syncs every memory to disk as a raw .md file inside the memory/ bundle directory with hierarchical index.md progressive disclosure files (root index.md versioned with okf_version: "0.2") and log.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 .md file inside the memory/ bundle directory with hierarchical index.md progressive disclosure files (root index.md versioned with okf_version: "0.2") and log.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. 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). MCP Tools The server exposes four primary MCP tools to interacting agents: 1. memory_store 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 or project/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: ). key (string, required): Unique identifier or path for the memory (e.g. user/preferences/coding_style or project/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: ). 2. memory_retrieve 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. 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. 3. memory_search 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. 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. 5. memory_get_last 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. project_root (string, required): Absolute path to active project root directory. namespace (string, optional, default: "default"): Scope/namespace. 6. memory_update_last 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. 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. OKF (Open Knowledge Format) Structure 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. Quick Start 1. Clone the Repository git clone https://github.com/fellowgeek/mcp-memory cd mcp-memory 2. Interactive Setup Wizard 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 launch mcp-memory automatically in the background whenever needed. You do not need to manually start or keep a server process running in your terminal. Note: Once setup.py finishes configuring your tools, your AI client will launch mcp-memory automatically in the background whenever needed. You do not need to manually start or keep a server process running in your terminal. 3. Run Manually via CLI (Optional / Debugging) 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 Manual Client Configuration If you prefer to configure your MCP client manually, add the "memory" server entry pointing to run.sh: JSON Configuration (Antigravity, Claude Desktop, Cursor, Windsurf) Add to your client's mcp_config.json or claude_desktop_config.json: { "mcpServers": { "memory": { "command": "/ABSOLUTE/PATH/TO/run.sh" } } } TOML Configuration (Codex Desktop) Add to ~/.codex/config.toml: [mcp_servers.memory] command = "/ABSOLUTE/PATH/TO/run.sh" CLI Configuration Claude Code CLI: claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh Codex CLI: codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh Testing Run the automated test suite to verify OKF serialization, SQLite database operations, and FastMCP tool execution: python3 test_memory.py Storage & Environment Variables 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 directory cwd). 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 and MCP_MEMORY_DIR=~/.mcp_memory/memory in your client's MCP configuration. Tip: If you prefer a single global memory store shared across all projects, set MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db and MCP_MEMORY_DIR=~/.mcp_memory/memory in your client's MCP configuration.