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
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.
- 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 six 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 (<producer>/<version>, human:<id>, process:<id>).
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.
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.
4. memory_delete
Removes a specific memory record by its key and namespace, from both the SQLite index and the memory/ bundle on disk.
- Parameters:
key (string, required): The key of the memory to remove.project_root (string, required): Absolute path to the active project root directory.namespace (string, optional, default: "default"): Scope/namespace.
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.
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.
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.
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
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.
一个 MCP 服务器，为 AI 代理提供持久的长期记忆——跨会话依然保留的有状态笔记，以 Open Knowledge Format 格式存储，并建立在本地 SQLite 数据库中，方便快速检索。