MCP-Memory: Fast Agent Memory with OKF and SQLite FTS5

Quick Take

MCP-Memory provides AI agents with persistent, OKF‑v0.2‑compliant memory that is indexed in a local SQLite FTS5 database, delivering sub‑20 ms key lookups and instant full‑text search while keeping a human‑browseable markdown directory.

What MCP-Memory Is

MCP-Memory is a Model Context Protocol (MCP) server that equips agents such as Claude Desktop, Cursor, Antigravity, Windsurf, or Codex with long‑term, searchable memory. Each memory record is stored as an OKF v0.2 markdown document with a rich YAML front‑matter, and the same data is indexed in SQLite FTS5 for fast retrieval.

Core Design Choices

Dual‑Layer Architecture

Human‑browseable OKF directory – Every memory is dumped to memory/ as a .md file with hierarchical index.md files, providing a versioned, readable knowledge base.
High‑performance SQLite index – An SQLite database with FTS5 triggers enables key‑value lookups in under 20 ms and keyword searches across keys, front‑matter, and content.

Namespace Isolation

Memory can be partitioned by namespace (e.g., user/preferences, project/architecture, default), preventing cross‑project contamination.

Zero‑Boilerplate Setup

Running python3 setup.py auto‑detects supported agents and registers the memory MCP server, so the agent launches the server automatically without a persistent terminal process.

MCP Tools Exposed to Agents

Tool	Purpose	Key Parameters
`memory_store`	Create or update a memory record	`key`, `content`, `project_root`, optional `tags`, `namespace`, `concept_type`, `title`, `description`, `resource`, `status`, `stale_after`, `sources`, `verified`, `generated_by`
`memory_retrieve`	Fetch a single record by key	`key`, `project_root`, optional `namespace`
`memory_search`	Full‑text or tag‑based search	`project_root`, optional `query`, `tags`, `namespace`, `limit`
`memory_get_last`	Retrieve the session checkpoint (`system/last_memory`) at start‑up	`project_root`, optional `namespace`
`memory_update_last`	Update the checkpoint after a milestone	`content`, `project_root`, optional `namespace`, `summary`

OKF v0.2 Specification in Practice

Each memory follows the OKF front‑matter schema, for example:

---
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.

The same file lives in memory/ while its searchable representation is stored in .mcp_memory/memories.db.

Installation & Quick Start

Clone the repo:

git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory

Run the setup wizard to auto‑register the server with supported agents:
```
python3 setup.py
```
After completion the agent will launch mcp-memory on demand.
Optional manual start for debugging:
```
./run.sh
```

Manual Client Configuration

If you prefer explicit configuration, add a memory entry pointing to run.sh:

JSON (Antigravity, Claude Desktop, Cursor, Windsurf)

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

TOML (Codex Desktop)

[mcp_servers.memory]
command = "/ABSOLUTE/PATH/TO/run.sh"

CLI examples

claude mcp add --scope user memory -- /ABSOLUTE/PATH/TO/run.sh
codex mcp add memory -- /ABSOLUTE/PATH/TO/run.sh

Storage Layout & Environment Variables

OKF markdown – memory/ directory inside the project root.
SQLite index – .mcp_memory/memories.db (hidden).
Environment variables allow custom locations:
- MCP_MEMORY_PROJECT_ROOT – defaults to the current working directory.
- MCP_MEMORY_DB_PATH – defaults to .mcp_memory/memories.db.
- MCP_MEMORY_DIR – defaults to memory.
To share a single store across projects, set MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db and MCP_MEMORY_DIR=~/.mcp_memory/memory.

Community Feedback Highlights

@myshapeprotocol – “Using SQLite FTS5 for fast agent memory is such a pragmatic architectural choice. Great Show HN project.”

@bearjaws – “Another week, another agent memory system that is about the same as grep in a memory/ directory.”

@healthycoder – “How is this any different from all the other Memory stuff we have? mem0 etc that do the same thing?”

@jrflo – “Why is this beneficial over just using markdown files and allowing agents to grep? I've found MCP tools can slow agents and waste tokens.”

@FitchApps – “Can you explain for noobs why using Google's OKF format and not plain MD files?”

@rcarmo – “Nice to see more OKF‑based approaches. My entry is https://rcarmo.github.io/projects/memento/.”

These comments surface two recurring themes: the value of structured OKF metadata versus plain markdown, and the performance trade‑off of an SQLite index compared to simple grep.

How MCP-Memory Differs from Existing Solutions

Standardized metadata – OKF v0.2 enforces a uniform schema (type, tags, status, provenance) that plain markdown lacks, enabling richer filtering and automated lifecycle management.
Sub‑20 ms indexed lookups – SQLite FTS5 provides deterministic latency, whereas grep scales linearly with file size and can become a bottleneck in large projects.
Dual persistence – Agents get instant machine‑readable access via the database while developers retain a human‑readable markdown archive for review and version control.
Namespace isolation – Built‑in support for separate knowledge domains prevents accidental cross‑talk between unrelated projects.

When to Use MCP-Memory

Projects that require fast, deterministic retrieval of dozens to thousands of knowledge snippets.
Teams that want auditability: the markdown directory can be version‑controlled while the database powers the agent.
Workflows that benefit from structured provenance (sources, verification, status) for compliance or documentation.

Limitations & Open Questions

No built‑in vector search; memory is retrieved via exact key, tag, or full‑text match only.
Performance gains depend on SQLite’s FTS5 configuration; extremely large corpora may still need sharding.
Some users report that MCP tooling can increase token usage if agents repeatedly query the server; careful prompt design is required.

Conclusion

MCP-Memory bridges the gap between human‑readable knowledge bases and high‑performance agent memory by combining Google’s Open Knowledge Format with SQLite FTS5. Its dual‑layer design, namespace isolation, and zero‑boilerplate setup make it a compelling option for developers seeking structured, fast, and persistent context for AI agents.