mcp-memory
An OKF-backed Model Context Protocol (MCP) server delivering persistent long-term memory and SQLite FTS5 search for AI agents.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/fellowgeek--mcp-memory)HTML
<a href="/listings/fellowgeek--mcp-memory"><img src="/api/listings/fellowgeek--mcp-memory/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 194 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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)**](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) 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](#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`](SPEC.md) and [`OKF_RULES.md`](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).
- ---
- ## MCP Tools
- 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.
- ---
- ## OKF (Open Knowledge Format) Structure
- Every stored memory strictly adheres to the OKF v0.2 specification ([`SPEC.md`](SPEC.md) & [`OKF_RULES.md`](OKF_RULES.md)):
- ```markdown
- ---
- 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
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- ./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`:
- ```json
- {
- "mcpServers": {
- "memory": {
- "command": "/ABSOLUTE/PATH/TO/run.sh"
- }
- }
- }
- ```
- ### TOML Configuration (Codex Desktop)
- Add to `~/.codex/config.toml`:
- ```toml
- [mcp_servers.memory]
- command = "/ABSOLUTE/PATH/TO/run.sh"
- ```
- ### CLI Configuration
- - **Claude Code CLI:**
- ```bash
- claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
- ```
- - **Codex CLI:**
- ```bash
- 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:
- ```bash
- 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.