mcp-memory README

The project's README from github.com/fellowgeek/mcp-memory. As one markdown file: README.md.

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

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.

2. memory_retrieve

Retrieves a specific memory by its key and namespace.

3. memory_search

Finds memories matching keywords, tags, or namespace filters.

4. memory_delete

Removes a specific memory record by its key and namespace, from both the SQLite index and the memory/ bundle on disk.

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.

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.

OKF (Open Knowledge Format) Structure

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:

You can customize this behavior using environment variables:

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-memory (fellowgeek/mcp-memory)

Searching Database…

218 ·GitHub
Mcp-memory
What is this?An MCP server that gives AI agents persistent long-term memory — stateful notes that survive across sessions, stored in the Open Knowledge Format and indexed in a local SQLite database for fast search.
Is this a separate app I need to run, or something that plugs into tools I already use?It plugs into MCP-capable clients: register it once and your AI client launches it automatically in the background whenever needed — you never start or keep a server process yourself.
How do I set it up?Clone the repository and run the setup wizard: python3 setup.py. It auto-detects your installed MCP tools and registers the server with them; manual JSON, TOML, and CLI configuration are also documented.
Which AI clients does it work with?Claude Desktop, Cursor, Antigravity, Windsurf, and Codex (Desktop and CLI), plus Claude Code CLI. It's a Python project, so Python 3 must be available on your machine.
Does the memory carry over between projects, or does each project keep its own?Each project gets its own isolated store by default: a memory/ folder of Markdown files plus a hidden .mcpmemory/memories.db index in the project root. Environment variables can point both at one shared global store instead.
Does any of this memory data leave my machine?No — memories live as plain .md files and a local SQLite database on your own disk. The README mentions no cloud service, account, or telemetry.
What can my agent actually do with the memory?Six MCP tools: store or update records, retrieve by key, search by keyword, tag, or namespace with a result limit, and delete — plus a checkpoint pair (memorygetlast / memoryupdatelast) that records and recalls where the last session left off.
What is the Open Knowledge Format (OKF)?The spec every record follows: a Markdown document with YAML frontmatter carrying metadata like type, key, namespace, tags, status, staleafter, sources, and verification events, per OKF v0.2 (SPEC.md and OKFRULES.md).
Why keep Markdown files when everything is in SQLite?It's a deliberate dual-layer design: the memory/ folder holds human-browsable .md copies with index.md files and a log.md history, while SQLite FTS5 triggers give sub-20ms key lookups and instant keyword search.
What are similar projects?ai-memory, EverOS, context-mode, agent-memory, engram, okf-agent-memory, LongMemory, MemOS
Which topics is it in?persistence, mcp-tools, long-term-memory, full-text-search, coding-agents, agent-memory, memory, knowledge-base, sqlite, local-first, mcp-server, database
Creator
fellowgeek
Size
0.1 MB
Stars
218
Updated
CommitAug 30Releasev1.0Aug 30
Age
2mo
Commits · 90 Days