by fellowgeek (community) · Claude Desktop, Claude Code, OpenCode, Cursor, Antigravity, Windsurf, Codex, macOS, Linux, SQLite

показать оригинал переведено ИИ

MCP-Memory: Сервер памяти агентов на базе OKF

MCP-Memory — это сервер протокола Model Context Protocol (MCP), который наделяет ИИ-агентов (таких как Claude Desktop, Cursor, Antigravity, Windsurf или Codex) возможностями постоянной долговременной памяти.

Записи памяти форматируются с использованием стандарта Open Knowledge Format (OKF v0.2) и индексируются локальным экземпляром SQLite (с поддержкой полнотекстового поиска FTS5) для быстрого поиска по ключам, фильтрации по тегам и поиска по содержимому.

Быстрый старт: Перейти сразу к разделу "Быстрый старт"

Ключевые возможности

Постоянное состояние между сессиями: Позволяет ИИ-агентам читать, сохранять, искать и удалять фрагменты памяти с состоянием, которые сохраняются между диалогами и сессиями.
Соблюдение стандарта OKF: Каждый элемент памяти хранится в формате документа OKF v0.2 Markdown с YAML-метаданными (type, key, namespace, tags, generated, sources, verified, status, stale_after), строго следуя SPEC.md и OKF_RULES.md.
Двухуровневая архитектура:
- Каталог OKF для просмотра человеком: Автоматически сохраняет и синхронизирует каждую запись памяти на диск в виде исходного файла .md внутри каталога memory/, с иерархическими файлами прогрессивного раскрытия index.md (корневой index.md версиируется с okf_version: "0.2") и историей обновлений log.md.
- Высокопроизводительная индексация SQLite: SQLite FTS5 (полнотекстовый поиск) и автоматические триггеры для поиска по ключам за менее чем 20 мс и мгновенного поиска по ключевым словам.
Изоляция пространств имён: Поддерживает контекстное разделение (например, user/preferences, project/architecture, default).
Установка без шаблонного кода: Мастер быстрой настройки (python3 setup.py) автоматически конфигурирует установленные инструменты MCP (Antigravity, Claude, Cursor, Windsurf, Codex).

Инструменты MCP

Сервер предоставляет агентам шесть инструментов MCP:

1. `memory_store`

Сохраняет или обновляет запись памяти в формате OKF v0.2. * Параметры: - key (строка, обязательно): Уникальный идентификатор или путь для памяти (например, user/preferences/coding_style или project/architecture). - content (строка или объект, обязательно): Основная информация для хранения. - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта (например, /Users/user/Projects/my-app). - tags (массив строк, опционально): Теги для классификации и фильтрации. - namespace (строка, опционально, по умолчанию: "default"): Пространство имён/область видимости. - concept_type (строка, опционально, по умолчанию: "Agent Memory"): Тип концепции OKF (например, Metric, Playbook, Attested Computation). - title (строка, опционально): Отображаемое имя. - description (строка, опционально): Краткое описание в одну строку. - resource (строка, опционально): Канонический URI базового ресурса. - status (строка, опционально, по умолчанию: "stable"): Состояние жизненного цикла (draft | stable | deprecated). - stale_after (строка, опционально): Дата в формате ISO (YYYY-MM-DD). - sources (массив объектов, опционально): Источники происхождения [{resource, id, title, author, usage_count, last_modified}]. - verified (массив объектов или объект, опционально): События верификации [{by, at}]. - generated_by (строка, опционально): Идентификатор актора по соглашению об акторах (<producer>/<version>, human:<id>, process:<id>).

2. `memory_retrieve`

Извлекает конкретную запись памяти по её ключу и пространству имён. * Параметры: - key (строка, обязательно): Ключ памяти для поиска. - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта. - namespace (строка, опционально, по умолчанию: "default"): Пространство имён/область видимости.

3. `memory_search`

Находит записи памяти, соответствующие ключевым словам, тегам или фильтрам пространств имён. * Параметры: - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта. - query (строка, опционально): Поисковый запрос по ключевым словам в ключах, метаданных и содержимом. - tags (массив строк, опционально): Фильтрация по конкретным тегам. - namespace (строка, опционально): Ограничение поиска пространством имён. - limit (целое число, опционально, по умолчанию: 10): Максимальное количество результатов.

4. `memory_delete`

Удаляет конкретную запись памяти по её ключу и пространству имён как из индекса SQLite, так и из каталога memory/ на диске. * Параметры:

- key (строка, обязательно): Ключ памяти, которую необходимо удалить. - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта. - namespace (строка, необязательно, по умолчанию: "default"): Область/пространство имён.

5. `memory_get_last`

ДИРЕКТИВА АГЕНТА (Начало сеанса): Извлекает последний сохранённый чекпоинт сеанса (system/last_memory), чтобы ИИ-агент сразу знал, на чём была остановлена работа при открытии проекта или начале сеанса. * Параметры: - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта. - namespace (строка, необязательно, по умолчанию: "default"): Область/пространство имён.

6. `memory_update_last`

ДИРЕКТИВА АГЕНТА (Вехи и прогресс): Обновляет канонический чекпоинт сеанса (system/last_memory) при завершении вехи, внесении ключевых изменений или приостановке работы. * Параметры: - content (строка или объект, обязательно): Краткая заметка или структурированный словарь с описанием прогресса и ссылками на ключевые файлы памяти. - project_root (строка, обязательно): Абсолютный путь к корневому каталогу активного проекта. - namespace (строка, необязательно, по умолчанию: "default"): Область/пространство имён. - summary (строка, необязательно): Однострочное описание достигнутой вехи.

Структура OKF (Open Knowledge Format)

Каждая сохранённая память строго соответствует спецификации OKF v0.2 (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.

Быстрый старт

1. Клонируйте репозиторий

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

2. Интерактивный мастер настройки

Запустите setup.py, чтобы автоматически обнаружить и зарегистрировать mcp-memory в ваших ИИ-инструментах:

python3 setup.py

Примечание: После завершения настройки setup.py ваш ИИ-клиент будет автоматически запускать mcp-memory в фоновом режиме при необходимости. Вам не нужно вручную запускать или держать работающим серверный процесс в терминале.

3. Запуск вручную через CLI (опционально / отладка)

Если вы хотите вручную проверить запуск, просмотреть вывод stdio или предварительно инициализировать виртуальное окружение (.venv), вы можете напрямую запустить run.sh:

./run.sh

Ручная настройка клиента

Если вы предпочитаете настроить MCP-клиент вручную, добавьте запись сервера "memory", указывающую на run.sh:

Конфигурация JSON (Antigravity, Claude Desktop, Cursor, Windsurf)

Добавьте в mcp_config.json или claude_desktop_config.json вашего клиента:

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

Конфигурация TOML (Codex Desktop)

Добавьте в ~/.codex/config.toml:

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

Конфигурация CLI

Claude Code CLI: bash claude mcp add --scope user memory -- /АБСОЛЮТНЫЙ/ПУТЬ/К/run.sh
Codex CLI: bash codex mcp add memory -- /АБСОЛЮТНЫЙ/ПУТЬ/К/run.sh

Тестирование

Запустите автоматизированный набор тестов для проверки сериализации OKF, операций с базой данных SQLite и выполнения инструментов FastMCP:

python3 test_memory.py

Хранилище и переменные окружения

По умолчанию mcp-memory создаёт изолированные хранилища памяти для каждого проекта в корневом каталоге проекта: - Файлы OKF Markdown (читаемые человеком): папка memory/ в корне проекта. - База данных SQLite (скрытый индекс): .mcp_memory/memories.db в корне проекта.

Вы можете настроить это поведение с помощью переменных окружения:

MCP_MEMORY_PROJECT_ROOT: Корневой каталог проекта (по умолчанию: текущий рабочий каталог процесса cwd).
MCP_MEMORY_DB_PATH: Путь к файлу базы данных SQLite (по умолчанию: .mcp_memory/memories.db относительно корня проекта).
MCP_MEMORY_DIR: Каталог для файлов Open Knowledge Format (OKF) .md (по умолчанию: memory относительно корня проекта).

Совет: Если вы предпочитаете единое глобальное хранилище памяти для всех проектов, установите MCP_MEMORY_DB_PATH=~/.mcp_memory/memories.db и MCP_MEMORY_DIR=~/.mcp_memory/memory в конфигурации MCP вашего клиента.

mcp-memory