Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fellowgeek--mcp-memory/badge.svg)](/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

i

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)

  1. # MCP-Memory: OKF-Backed Agent Memory Server
  2. **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.
  3. 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.
  4. > **Fast Track:** [Jump directly to Quick Start](#quick-start)
  5. ---
  6. ## Key Features
  7. * **Persistent State Across Sessions:** Enables AI agents to read, store, search, and delete stateful memory snippets that persist across chat turns and sessions.
  8. * **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).
  9. * **Dual-Layer Architecture:**
  10. - **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.
  11. - **High-Performance SQLite Indexing**: SQLite FTS5 (Full-Text Search) and automatic triggers for sub-20ms key lookups and instant keyword searches.
  12. * **Namespace Isolation:** Supports contextual separation (e.g. `user/preferences`, `project/architecture`, `default`).
  13. * **Zero Boilerplate Setup:** Quick setup wizard (`python3 setup.py`) auto-configures installed MCP tools (Antigravity, Claude, Cursor, Windsurf, Codex).
  14. ---
  15. ## MCP Tools
  16. The server exposes six MCP tools to interacting agents:
  17. ### 1. `memory_store`
  18. Stores or updates a memory record in OKF v0.2 format.
  19. * **Parameters:**
  20. - `key` *(string, required)*: Unique identifier or path for the memory (e.g. `user/preferences/coding_style` or `project/architecture`).
  21. - `content` *(string or object, required)*: Core information to store.
  22. - `project_root` *(string, required)*: Absolute path to the active project root directory (e.g. `/Users/user/Projects/my-app`).
  23. - `tags` *(array of strings, optional)*: Classification tags for filtering.
  24. - `namespace` *(string, optional, default: `"default"`)*: Scope/namespace.
  25. - `concept_type` *(string, optional, default: `"Agent Memory"`)*: OKF concept type (e.g. `Metric`, `Playbook`, `Attested Computation`).
  26. - `title` *(string, optional)*: Display name.
  27. - `description` *(string, optional)*: One-line summary.
  28. - `resource` *(string, optional)*: Canonical URI of underlying asset.
  29. - `status` *(string, optional, default: `"stable"`)*: Lifecycle state (`draft` | `stable` | `deprecated`).
  30. - `stale_after` *(string, optional)*: ISO date (`YYYY-MM-DD`).
  31. - `sources` *(array of objects, optional)*: Provenance sources `[{resource, id, title, author, usage_count, last_modified}]`.
  32. - `verified` *(array of objects or object, optional)*: Verification events `[{by, at}]`.
  33. - `generated_by` *(string, optional)*: Actor identifier following actor convention (`<producer>/<version>`, `human:<id>`, `process:<id>`).
  34. ### 2. `memory_retrieve`
  35. Retrieves a specific memory by its key and namespace.
  36. * **Parameters:**
  37. - `key` *(string, required)*: The memory key to look up.
  38. - `project_root` *(string, required)*: Absolute path to the active project root directory.
  39. - `namespace` *(string, optional, default: `"default"`)*: Scope/namespace.
  40. ### 3. `memory_search`
  41. Finds memories matching keywords, tags, or namespace filters.
  42. * **Parameters:**
  43. - `project_root` *(string, required)*: Absolute path to the active project root directory.
  44. - `query` *(string, optional)*: Keyword search query across keys, frontmatter, and content.
  45. - `tags` *(array of strings, optional)*: Filter by specific tags.
  46. - `namespace` *(string, optional)*: Scope search to a namespace.
  47. - `limit` *(integer, optional, default: 10)*: Maximum number of results.
  48. ### 4. `memory_delete`
  49. Removes a specific memory record by its key and namespace, from both the SQLite index and the `memory/` bundle on disk.
  50. * **Parameters:**
  51. - `key` *(string, required)*: The key of the memory to remove.
  52. - `project_root` *(string, required)*: Absolute path to the active project root directory.
  53. - `namespace` *(string, optional, default: `"default"`)*: Scope/namespace.
  54. ### 5. `memory_get_last`
  55. **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.
  56. * **Parameters:**
  57. - `project_root` *(string, required)*: Absolute path to active project root directory.
  58. - `namespace` *(string, optional, default: `"default"`)*: Scope/namespace.
  59. ### 6. `memory_update_last`
  60. **AGENT DIRECTIVE (Milestones & Progress):** Updates the canonical session checkpoint (`system/last_memory`) whenever completing a milestone, making key changes, or pausing work.
  61. * **Parameters:**
  62. - `content` *(string or object, required)*: Brief note or structured dictionary summarizing progress and referencing key memory files.
  63. - `project_root` *(string, required)*: Absolute path to active project root directory.
  64. - `namespace` *(string, optional, default: `"default"`)*: Scope/namespace.
  65. - `summary` *(string, optional)*: One-sentence description of the milestone achieved.
  66. ---
  67. ## OKF (Open Knowledge Format) Structure
  68. Every stored memory strictly adheres to the OKF v0.2 specification ([`SPEC.md`](SPEC.md) & [`OKF_RULES.md`](OKF_RULES.md)):
  69. ```markdown
  70. ---
  71. type: Agent Memory
  72. title: Coding Style
  73. key: user/preferences/coding_style
  74. namespace: default
  75. tags:
  76. - preferences
  77. - style
  78. status: stable
  79. generated:
  80. by: mcp-memory/0.2.0
  81. at: '2026-08-12T19:23:35Z'
  82. created_at: '2026-08-12T19:23:35Z'
  83. updated_at: '2026-08-12T19:23:35Z'
  84. ---
  85. User prefers functional programming style with explicit type annotations.
  86. ```
  87. ---
  88. ## Quick Start
  89. ### 1. Clone the Repository
  90. ```bash
  91. git clone https://github.com/fellowgeek/mcp-memory
  92. cd mcp-memory
  93. ```
  94. ### 2. Interactive Setup Wizard
  95. Run `setup.py` to auto-detect and register `mcp-memory` with your AI tools:
  96. ```bash
  97. python3 setup.py
  98. ```
  99. > **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.
  100. ### 3. Run Manually via CLI (Optional / Debugging)
  101. If you want to manually verify startup, inspect stdio output, or pre-initialize the virtual environment (`.venv`), you can run `run.sh` directly:
  102. ```bash
  103. ./run.sh
  104. ```
  105. ---
  106. ## Manual Client Configuration
  107. If you prefer to configure your MCP client manually, add the `"memory"` server entry pointing to `run.sh`:
  108. ### JSON Configuration (Antigravity, Claude Desktop, Cursor, Windsurf)
  109. Add to your client's `mcp_config.json` or `claude_desktop_config.json`:
  110. ```json
  111. {
  112. "mcpServers": {
  113. "memory": {
  114. "command": "/ABSOLUTE/PATH/TO/run.sh"
  115. }
  116. }
  117. }
  118. ```
  119. ### TOML Configuration (Codex Desktop)
  120. Add to `~/.codex/config.toml`:
  121. ```toml
  122. [mcp_servers.memory]
  123. command = "/ABSOLUTE/PATH/TO/run.sh"
  124. ```
  125. ### CLI Configuration
  126. - **Claude Code CLI:**
  127. ```bash
  128. claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
  129. ```
  130. - **Codex CLI:**
  131. ```bash
  132. codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh
  133. ```
  134. ---
  135. ## Testing
  136. Run the automated test suite to verify OKF serialization, SQLite database operations, and FastMCP tool execution:
  137. ```bash
  138. python3 test_memory.py
  139. ```
  140. ## Storage & Environment Variables
  141. By default, `mcp-memory` creates project-isolated memory stores inside each project's root directory:
  142. - **OKF Markdown Files (Human-readable)**: `memory/` folder in project root.
  143. - **SQLite Database (Hidden index)**: `.mcp_memory/memories.db` in project root.
  144. You can customize this behavior using environment variables:
  145. - `MCP_MEMORY_PROJECT_ROOT`: Project root directory (default: process current working directory `cwd`).
  146. - `MCP_MEMORY_DB_PATH`: SQLite database file path (default: `.mcp_memory/memories.db` relative to project root).
  147. - `MCP_MEMORY_DIR`: Directory for Open Knowledge Format (OKF) `.md` files (default: `memory` relative to project root).
  148. > **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 in

Free to use. If it’s helped, pass it on.