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 to-SPEC.mdand-OKF_RULES.md. - Dual-Layer Architecture:- Human-Browseable OKF Directory: Automatically dumps and syncs every memory to disk as a raw-
.mdfile inside the-memory/bundle directory with hierarchical-index.mdprogressive disclosure files (root-index.mdversioned with-okf_version: "0.2") and-log.mdupdate 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 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_styleor-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:: Scope/namespace.-"default")concept_type- (string, optional, default:: OKF concept type (e.g.-"Agent Memory")-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:: Lifecycle state (-"stable")-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>).
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:: Scope/namespace.-"default")
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:: Scope/namespace.-"default")
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:: Scope/namespace.-"default")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
``
Runsetup.pyto auto-detect and registermcp-memory` with your AI tools:
python3 setup.py
Note:Oncesetup.pyfinishes configuring your tools, your AI client will launchmcp-memoryautomatically 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.shIf 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.pyBy 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.dbin 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.dbrelative to project root).MCP_MEMORY_DIR: Directory for Open Knowledge Format (OKF)-.mdfiles (default:-memoryrelative to project root).
Tip:If you prefer a single global memory store shared across all projects, setMCP_MEMORY_DB_PATH=~/.mcp_memory/memories.dbandMCP_MEMORY_DIR=~/.mcp_memory/memoryin your client's MCP configuration.