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
Что это такое?MCP-сервер, который даёт ИИ-агентам долговременную память — заметки с состоянием, которые сохраняются между сессиями. Хранятся они в формате Open Knowledge Format и индексируются в локальной базе SQLite для быстрого поиска.
Это отдельное приложение, которое нужно запускать, или оно встраивается в инструменты, которыми я уже пользуюсь?Оно подключается к MCP-совместимым клиентам: достаточно зарегистрировать его один раз, и ваш ИИ-клиент будет сам запускать его в фоне, когда нужно, — вручную запускать или держать процесс сервера не требуется.
Как его настроить?Склонируйте репозиторий и запустите мастер настройки: python3 setup.py. Он сам найдёт установленные MCP-инструменты и зарегистрирует сервер в них; также в документации описана ручная настройка через JSON, TOML и командную строку.
С какими ИИ-клиентами он работает?Claude Desktop, Cursor, Antigravity, Windsurf и Codex (Desktop и CLI), а ещё Claude Code CLI. Проект написан на Python, так что на компьютере должен быть установлен Python 3.
Память общая для всех проектов или у каждого проекта своя?По умолчанию у каждого проекта своё изолированное хранилище: папка memory/ с файлами Markdown плюс скрытый индекс .mcpmemory/memories.db в корне проекта. Через переменные окружения оба пути можно перенаправить на одно общее глобальное хранилище.
Эти данные памяти куда-то отправляются с моего компьютера?Нет — память хранится в виде обычных .md-файлов и локальной базы SQLite на вашем own диске. В README не упоминается ни облачный сервис, ни аккаунт, ни телеметрия.
Что мой агент реально может делать с этой памятью?Шесть MCP-инструментов: сохранять или обновлять записи, получать запись по ключу, искать по ключевому слову, тегу или пространству имён с ограничением числа результатов, а также удалять — плюс пара инструментов-чекпоинтов (memorygetlast / memoryupdatelast), которые запоминают и восстанавливают, на чём остановилась прошлая сессия.
Что такое Open Knowledge Format (OKF)?Спецификация, которой следует каждая запись: документ Markdown с YAML-заголовком (frontmatter), где хранятся метаданные — type, key, namespace, tags, status, staleafter, sources и события проверки; согласно OKF v0.2 (файлы SPEC.md и OKFRULES.md).
Зачем хранить файлы Markdown, если всё и так лежит в SQLite?Это намеренная двухслойная схема: папка memory/ хранит .md-копии, которые можно читать глазами, с файлами index.md и журналом log.md, а триггеры SQLite FTS5 обеспечивают поиск по ключу быстрее 20 мс и мгновенный поиск по ключевым словам.
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