marm-memory

Приветствуются вклады! Просматривайте открытые вопросы для участия или присоединяйтесь к MARM Discord, чтобы делиться рабочими процессами, получать помощь по настройке и общаться с другими разработчиками.

Содержание

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

• Почему MARM Memory

• Производительность и тесты масштабирования

• Настройка MCP-клиента

• Команды CLI времени выполнения

• Полный набор инструментов MCP (14 инструментов)

• Использование MARM: Говорите, а не вызывайте инструменты

• Понимание MARM Memory

• Графы знаний: код и концепции

• Архитектура и внутреннее устройство

• Устранение неполадок

• Участие

• Документация проекта

Related MCP server: Memory Crystal MCP Server

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

1. Установите и выполните инициализацию с вашими предпочтительными профилями агентов:

pip install marm-mcp-server
marm-memory init --g-claude --g-codex --g-gemini

Также доступно: --g-qwen и --g-kiro. Запустите без флагов, чтобы установить в текущую папку проекта вместо домашней.

1. Передайте управление вашему AI-компаньону. Скажите своему агенту:

"Используй навык marm-init для настройки MARM."

1. Взаимодействуйте: Ваш агент выполнит всю настройку (Python/Docker, HTTP/STDIO, ключи и конфигурации клиента) интерактивно прямо в вашем чате.

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

Предпочитаете настроить всё самостоятельно:

Замените "agent" на команду CLI вашего клиента (например, claude, gemini, или qwen). Для Codex используйте codex mcp add marm-memory --url http://localhost:8001/mcp.

• ⚡ Быстрый запуск HTTP: Выполните marm-memory fast-start-http, чтобы запустить локальную среду выполнения, запустить консоль и сразу открыть её в браузере.

• 🖥️ Веб-консоль: Выполните marm-memory console, чтобы мгновенно открыть локальное UI-приложение (не требуется Node.js).

• ⚙️ Управление жизненным циклом: Управляйте фоновым демоном с помощью команд status, logs --follow, restart и stop.

• 💡 Быстрые флаги: Используйте --no-console или --no-browser, чтобы ограничить запуск. Выполните marm-memory --help для полного списка команд.

Почему MARM Memory

Ваш AI забывает всё. MARM Memory — нет.

marm-memory предоставляет вашим агентам частную, общую память для контекста, который обычно теряется между чатами: решений, исследований, исправлений, заметок и истории проекта. Переключайтесь с Claude Code на Codex или Gemini, не теряя уже собранный контекст.

Он объединяет три вещи:

• 🧠 Основная память (7 инструментов) хранит разговоры, заметки, записи блокнота и сводки, чтобы они оставались доступными для поиска.

• 💻 Граф кода (5 инструментов) отображает ваш репозиторий, чтобы агенты могли находить символы, следовать по путям кода и понимать проект без повторного чтения. Укажите его на репозиторий один раз, и он будет поддерживать себя в актуальном состоянии по мере вашей работы.

• 🧩 Граф концепций (2 инструмента) связывает людей, решения, ошибки и идеи из ваших сохранённых воспоминаний, со ссылками на соответствующий код, если он доступен. Он строится сам по мере сохранения воспоминаний.

Все 14 инструментов работают через HTTP и STDIO. Ваши агенты используют одну и ту же локальную память в разных сессиях, вместо того чтобы начинать с нуля каждый раз. Встроенная консоль позволяет просматривать и управлять сохранёнными данными.

Как это работает

См. Производительность и тесты масштабирования для данных о задержке извлечения, параллелизме и стоимости записи, а также Архитектура и внутреннее устройство для механизмов каждого слоя.

Команды CLI времени выполнения

marm-memory — это локальный менеджер времени выполнения, устанавливаемый вместе с пакетом Python. Это обычные операционные команды; используйте marm-memory <command> --help для справки по флагам и примерам.

Ежедневная работа времени выполнения

marm-memory fast-start-http                # start HTTP, Console, and open the browser
marm-memory start                          # start or reuse the managed HTTP runtime
marm-memory start --profile swarm          # shared multi-agent preset
marm-memory stop                           # stop the managed runtime safely
marm-memory restart                        # restart the managed runtime
marm-memory status                         # inspect runtime, database, queue, and graph status
marm-memory logs --follow                  # follow bounded runtime logs
marm-memory console                        # start or reuse the bundled local Console

Транспорты и настройка

marm-memory http                           # run HTTP in the foreground
marm-memory stdio                          # run the strict local MCP STDIO transport
marm-memory init                           # install the MARM skill into detected agents (project scan)
marm-memory init --g-claude                # install the skill into the home-folder claude directory
marm-memory doctor                         # diagnose the local install
marm-memory key init                       # create or reuse ~/.marm/.env without displaying the key
marm-memory key path                       # print the managed key-file path
marm-memory key reveal                     # explicitly display the managed key
marm-memory console --import-key           # open an authenticated local Console session
marm-memory upgrade --check                # compare the installed package with PyPI
marm-memory uninstall                      # preview package removal; always preserves ~/.marm

Знания, проекты и обслуживание

marm-memory knowledge status               # Indexers, models, and how far behind automatic indexing is
marm-memory knowledge build --all          # Rebuild the whole concept graph (new memories index themselves)
marm-memory knowledge auto off             # Stop indexing memories automatically (on, off, status)
marm-memory projects list                  # List all tracked workspaces
marm-memory projects index <path>          # Add a repo to the code graph (kept current after that)
marm-memory projects status                # Inspect target repo graph readiness
marm-memory projects auto off              # Stop re-indexing repos automatically (on, off, status)
marm-memory maintenance status             # Check internal database optimization state
marm-memory maintenance embeddings migrate # Upgrade old 384-dim vectors to 512-dim
marm-memory maintenance chunks rechunk     # Recalibrate long memory text splits

Команды Docker документируются отдельно ниже, поскольку они требуют явного монтирования данных, открытия сети и выбора обработки ключей.

Производительность и тесты масштабирования

MARM оптимизирован в первую очередь для быстрого поиска, даже при росте памяти и разбиении длинных воспоминаний на части в фоновом режиме.

Эти измерения используют кодировщик jinaai/jina-embeddings-v2-small-en на базе fastembed и временную локальную базу данных SQLite. Каждый замеренный путь вызывает поставляемый код MARMMemory, а не локальную реализацию бенчмарка. Разделы 1-4 — это временные замеры из одного запуска scripts/benchmarking/performance/bench_hotpath.py на локальном оборудовании; абсолютные миллисекунды различаются в зависимости от машины, поэтому рассматривайте форму масштабирования как сигнал. Раздел 5 — это отдельный бенчмарк точности (run_eval.py) и сообщает два запуска по указанной причине.

1. Масштабирование задержки извлечения

Сквозная задержка recall_similar (включает кодирование запроса).

Разброс от запуска к запуску при малом $N$ больше, чем разрыв между соседними размерами, поэтому N = 250 читается медленнее, чем N = 500. Рассматривайте тренд от N = 1,000 и выше как реальный сигнал.

2. Кодировщик + параллелизм

• Холодная загрузка модели: 893 мс

• Тёплое кодирование: медиана 3.8 мс, p95 4.3 мс

• Параллельный поиск: 10 собранных поисков завершены за 151.5 мс против 176.0 мс последовательно (gather/serial = 0.86). Не интерпретируйте это как параллелизм: повторные запуски этого же бенчмарка дают значения от 0.63 до 0.86, поэтому соотношение недостаточно стабильно, чтобы утверждать ускорение. Путь по замыслу сериализован вокруг общего кодировщика и работы SQLite, и любое кажущееся ускорение — это шум измерений.

3. Стоимость обработки при записи

• Консолидация выключена: медиана 6.5 мс, p95 7.6 мс

• Консолидация включена: медиана 58.1 мс, p95 106.5 мс

• Компромисс: дедупликация/кластеризация при записи добавляет в 9.0x медианную стоимость, чтобы поиск оставался быстрым, а хранилище — чище со временем. Консолидация выключена по умолчанию.

4. Масштабирование поиска: полное сканирование против гибридного режима производства

Почему recall остается стабильным при росте памяти: вместо сканирования каждого вектора production-recall использует FTS-ключевой префильтр для сужения пула кандидатов, а затем повторно ранжирует с помощью смешанной семантической + BM25 + временной оценки. Оба бенчмарковых столбца представляют собой аутентичные асинхронные пути кода, синхронизированные по времени с предварительно вычисленными векторами, чтобы изолировать скорость извлечения от накладных расходов на кодирование. Тесты чередуют выполнение для обеспечения полностью беспристрастных условий кэша.

Полное сканирование растет примерно линейно с $N$, в то время как гибридный recall растет гораздо медленнее, поэтому преимущество все еще увеличивается с размером сессии. При очень маленьком $N$ префильтр не оправдывает своих накладных расходов, и гибридная система работает медленнее.

5. Точность извлечения LoCoMo

Все 10 диалогов LoCoMo загружаются через marm_log_entry (5 882 воспоминания), затем результаты top-5 marm_smart_recall оцениваются по 1 977 вопросам с аннотированными доказательствами. Модель генерации ответов или LLM-судья не используются.

Прирост производительности изолирован в гибридном конвейере извлечения и локализованном векторном пространстве, что обеспечивает высокую точность извлечения с несколькими переходами без использования облачных LLM-судей. Воспроизведите полный бенчмарк с помощью scripts/benchmarking/accuracy/locomo/run_eval.py.

6. Сравнение с конкурентами: Архитектура

MARM нацелен на определенную нишу: локальная память для MCP-подключенных кодирующих агентов, а не общая персонализированная память или полноценная среда выполнения агента. Вот чем он архитектурно отличается от известных имен в области памяти ИИ-агентов:

Отказ от ответственности и точность: Ландшафт конкурентов быстро меняется. Приведенная выше матрица отражает основные архитектурные особенности по состоянию на Q3 2026, основанные на общедоступной документации и README, а не на внутреннем тестировании каждой системы. Если какой-либо пункт данных относительно альтернативного фреймворка изменился или был искажен, пожалуйста, откройте issue или отправьте Pull Request для обновления таблицы. Мы активно приветствуем исправления от коллег-мейнтейнеров.

Настройка MCP-клиента для HTTP и STDIO

Ручная установка через pip

pip install marm-mcp-server

Используйте это краткое правило для выбора настройки

• Локальный HTTP/STDIO = самая быстрая однокомпьютерная настройка.

• Docker HTTP = общий/постоянно работающий сервер (требуется ключ).

• Docker STDIO = частное контейнеризированное локальное использование (без HTTP-ключа).

Примечание для роя/многоагентных систем: Очередь записи включена по умолчанию для сериализации записи в память через один рабочий процесс. Для общих HTTP-развертываний используйте marm-memory start --profile swarm (200 RPM) или --profile swarm-max (600 RPM). --profile trusted отключает ограничение скорости для частных развертываний. STDIO по-прежнему лучше всего подходит для частного однопользовательского/локального использования. Смотрите полную таблицу в разделе Пресеты для роя и многоагентных систем.

"agent" относится к claude, gemini, grok, qwen или любому MCP-клиенту. Codex использует --url вместо --transport для добавления MCP-инструментов.

pip install marm-mcp-server
marm-memory start
# Stuck on client setup? Open a Q&A thread: https://github.com/Lyellr88/marm-memory/discussions
# most agents use this --transport command
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp
codex mcp add marm-memory --url http://localhost:8001/mcp

Запуск по умолчанию через pip/locally не требует настройки: MARM привязывается к localhost и не требует ключа, если вы не откроете доступ с помощью SERVER_HOST=0.0.0.0.

pip install marm-mcp-server
python -m marm_mcp_server.server_stdio
# most agents use this --transport command
"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio
codex mcp add marm-memory-stdio -- marm-mcp-stdio

Замените marm-mcp-stdio на python -m marm_mcp_server.server_stdio, если используете виртуальное окружение или настройку на основе путей. Работает с Claude Code, Cursor, VS Code, Qwen и Gemini CLI. STDIO остается единственным локальным процессом без порта и API-ключа и предоставляет те же 14 инструментов, что и HTTP.

Используйте HTTP, когда нескольким агентам нужно использовать один работающий MARM-сервер. STDIO по-прежнему лучше всего подходит для частного однопользовательского использования, потому что каждый клиент владеет своим собственным локальным процессом.

# HTTP shared server, normal multi-agent use
marm-memory start --profile swarm

# HTTP shared server, heavier private swarm
marm-memory start --profile swarm-max

# HTTP trusted private lab/server, rate limiting disabled
marm-memory start --profile trusted

# STDIO remains keyless/private and does not use swarm flags
marm-mcp-stdio

Docker HTTP требует API-ключа, потому что он открывает MARM как сетевой сервер; STDIO остается локальным для клиентского процесса и не требует его.

Если вы установили MARM через pip, интерфейс командной строки продукта может безопасно предварительно просмотреть или запустить ту же самую настройку. По умолчанию он использует порт обратной связи (loopback), сохраняет ~/.marm, хранит сгенерированный ключ в ~/.marm/.env, а не в истории оболочки, и отказывается заменять существующий контейнер.

marm-memory docker command                 # preview the exact HTTP command
marm-memory docker run                     # create the managed HTTP container
marm-memory docker stdio-command           # print a Docker STDIO client command
marm-memory docker status
marm-memory docker logs --follow
marm-memory docker stop

# Optional: mount repositories read-only for code indexing.
marm-memory docker run --repo /absolute/path/to/repository

# Optional: preview or explicitly write a Compose configuration.
marm-memory docker compose
marm-memory docker compose --yes

Команды HTTP run, command и compose принимают те же операционные флаги:

Например:

# Shared local server with a custom data path and two repositories for indexing.
marm-memory docker command \
  --profile swarm \
  --data-dir /srv/marm-data \
  --repo /srv/projects/api \
  --repo /srv/projects/web

# Execute the reviewed command, pulling the image first.
marm-memory docker run --profile swarm --data-dir /srv/marm-data --pull

Docker STDIO отделен от Docker HTTP: marm-memory docker stdio-command использует docker run -i --rm, не имеет порта и bearer-ключа, но по-прежнему монтирует каталог данных, чтобы SQLite-память сохранялась после завершения кратковременного контейнера. Используйте --data-dir и --tag с этой командой при необходимости. Отдельных команд docker key или docker mount нет; --env-file и --data-dir делают эти выборы явными в сгенерированной HTTP-команде.

marm-memory docker pull только загружает образ. marm-memory docker maintenance embeddings migrate выполняется с тем же монтированием данных и отказывается работать, пока управляемый HTTP-контейнер запущен. Помощник доступен только с командой marm-memory, установленной через pip; пользователи, использующие только Docker, могут использовать сырые команды ниже.

# Step 1: generate key (do not add < > around the key)
docker run --rm lyellr88/marm-mcp-server:latest --generate-key

# Step 2: run server
docker pull lyellr88/marm-mcp-server:latest
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest

# Step 3: connect client
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

# PowerShell: set this before starting/restarting Codex
$env:MARM_API_KEY="your-generated-key"
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

# Quick auth smoke test
curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0.1:8001/mcp

--bearer-token-env-var принимает имя переменной окружения, а не сам ключ. Запустите или перезапустите Codex из той же оболочки после установки $env:MARM_API_KEY. Для локальных тестов Docker MARM_API_KEY=test подходит и избегает проблем с экранированием в оболочке; для реальных развертываний используйте сгенерированный ключ. Ответ 406 Not Acceptable от тестового GET /mcp означает, что аутентификация дошла до конечной точки MCP; 401 Unauthorized означает, что ключ отсутствует или не совпадает.

# --swarm: write queue on, 200 RPM - recommended for multi-agent shared servers
docker run -d --name marm-mcp-server \
  -p 127.0.0.1:8001:8001 \
  -e SERVER_HOST=0.0.0.0 \
  -e MARM_API_KEY=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest --swarm

Docker-инструменты для графа выполняются внутри контейнера, поэтому они не видят пути хоста, если вы не смонтируете их при docker run.

$env:MARM_API_KEY="test"

# The second -v line mounts your repo; adjust the host path to your project
docker run -d --name marm-mcp-server `
  -p 127.0.0.1:8001:8001 `
  -e SERVER_HOST=0.0.0.0 `
  -e MARM_API_KEY=$env:MARM_API_KEY `
  -v ~/.marm:/home/marm/.marm `
  -v C:\Users\lyell\Desktop\marm-memory:/workspace/marm-memory `
  lyellr88/marm-mcp-server:latest

Затем индексируйте путь контейнера, а не путь хоста Windows:

marm_graph_index(repo_path="/workspace/marm-memory")

Инструменты для графа должны использовать путь контейнера. Монтирования нельзя добавить к уже работающему контейнеру; остановите и перезапустите контейнер с монтированием репозитория, когда вам понадобится индексация графа Docker.

Docker STDIO включает те же встроенные инструменты marm-graph; дополнительный образ или этап установки не требуется.

docker run --rm -i \
  -v ~/.marm:/home/marm/.marm \
  --entrypoint python \
  lyellr88/marm-mcp-server:latest \
  -m marm_mcp_server.server_stdio

• Docker HTTP требует ключа; Docker STDIO — нет.

• Если вы получаете 401, проверьте совпадение ключа и перезапуск клиента после изменений переменных окружения.

• Полная настройка ключа, ротация и устранение неполадок: INSTALL-DOCKER.md

Подключите свой клиент

Запустите сервер (python -m marm_mcp_server), затем настройте ваш клиент ниже. Каждый блок предполагает установку по умолчанию (без ключа). Для Docker или открытых серверов добавьте заголовок Authorization: Bearer, как показано в сворачиваемом блоке каждого клиента.

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Claude Code поддерживает HTTP, SSE и STDIO через claude mcp add; используйте HTTP для MARM. Для STDIO: claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio.

Добавьте в .vscode/mcp.json в вашей рабочей области. Используйте marm-memory-local для прямых установок Python; marm-memory-docker для Docker или режима с ключом.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "password": true
    }
  ],
  "servers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${input:marm-api-key}"
      }
    }
  }
}

Откройте .vscode/mcp.json, нажмите Start над нужным сервером, затем используйте Copilot Agent или любое расширение, которое использует встроенный реестр MCP VS Code.

Добавьте в .cursor/mcp.json в вашей рабочей области. Cursor использует mcpServers, а не корневой servers VS Code.

{
  "mcpServers": {
    "marm-memory-local": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    },
    "marm-memory-docker": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MARM_API_KEY}"
      }
    }
  }
}

Для режима Docker/ключ запустите Cursor с установленным MARM_API_KEY в окружении.

Codex использует codex mcp add или TOML-конфигурацию в ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml на Windows).

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required (set MARM_API_KEY in your shell first)
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

# Direct Python install - no key needed
gemini mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
gemini mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Эквивалентный ~/.gemini/settings.json (область пользователя) или проект .gemini/settings.json:

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

Эквивалентный .qwen/settings.json (проект) или ~/.qwen/settings.json (пользователь):

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

xAI подключается из своей собственной инфраструктуры, поэтому localhost не будет работать. Откройте MARM за HTTPS и установите MARM_API_KEY.

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

Полные пошаговые руководства по платформам, настройке ключа и примечания по ОС: Windows · macOS · Linux · Docker/режим ключа · Другие платформы

Используете клиент, которого нет в списке? Откройте issue и сообщите нам; адаптеры клиентов — это запросы функций первого класса.

Требования

• Python: 3.10 или выше

• SQLite3: Входит в состав Python (отдельная установка не требуется)

• Хранилище: ~100 МБ минимум для начальной установки, масштабируется в зависимости от размера базы памяти

• ОЗУ: 512 МБ минимум (зависит от количества одновременных клиентов и размера базы)

• ОС: Windows, macOS, Linux

Расположение данных

• Расположение: ~/.marm/ (Linux/macOS) или %USERPROFILE%\.marm\ (Windows)

• Содержимое: База данных SQLite со всеми воспоминаниями, сессиями и блокнотами; граф концепций находится в своей собственной базе ~/.marm/index/

• Резервное копирование: Скопируйте весь каталог ~/.marm/, чтобы сохранить все данные

• Конфиденциальность: Все остается на вашей машине, никакой облачной синхронизации или внешнего хранилища

Проверка установки

Используйте конечную точку здоровья MCP-сервера для самой быстрой проверки в реальном времени:

curl http://localhost:8001/health

Ожидаемый вывод включает версию сервера, доступность функций (статус семантического поиска), статус подключения к базе данных и статус работоспособности сервиса.

Полный набор инструментов MCP (14 инструментов)

💡 Совет профессионала: Вам не нужно вызывать эти инструменты вручную! Просто скажите вашему AI-агенту, что вы хотите, на естественном языке:

• "Claude, запиши эту сессию как 'Project Alpha' и добавь этот разговор как 'обсуждение дизайна базы данных'"

• "Запомни этот фрагмент кода в своем блокноте для последующего использования"

• "Найди, что мы обсуждали об аутентификации вчера"

AI-агент автоматически использует соответствующие инструменты. Ручной доступ к инструментам доступен для продвинутых пользователей, которым нужен прямой контроль.

🧠 Основная память (7 инструментов)

🕸️ Граф кода (5 инструментов)

🧩 Граф концепций (2 инструмента)

Все 14 инструментов доступны как по HTTP, так и по STDIO. За поверхностью инструментов сервер автоматически обрабатывает настройку жизненного цикла, обновление протокола, индексацию документации, контекст даты, обслуживание кэша резюме, обработку очереди записи, индексацию концепций, переиндексацию кода при изменении репозиториев, атрибуцию проекта/платформы и проверки здоровья; ни одно из этих действий не потребляет внимания или токенов агента. Два движка графа запускаются лениво при первом использовании и никогда не блокируют 7 основных инструментов памяти, если они не могут запуститься. См. Архитектура и внутренности для механизмов.

Использование MARM: Говорите, а не вызывайте инструменты

MARM внутренне обрабатывает работу жизненного цикла. Документация и состояние сессии инициализируются при первом реальном вызове инструмента, а встроенная документация индексируется в пространство имен памяти marm_system с отслеживанием хэша исходного файла, так что ваш агент может отвечать на вопросы об использовании MARM из самой памяти.

Пример рабочего процесса: Исследовательский проект с несколькими AI

Реалистичный рабочий процесс, показывающий MARM в действии. Сценарий: вы исследуете шаблоны аутентификации для нового проекта, используя несколько AI-клиентов.

Фаза 1: Маршрутная сессия (Claude)

You: "Claude, create a MARM session called 'auth-research-2025-01'"
Claude calls: marm_log_entry(entry="Session: auth-research")
Result: Session routed to auth-research-[today]. MARM lifecycle/docs initialize automatically.

Фаза 2: Сбор исследований (Claude)

You: "Summarize OAuth2 vs JWT for API authentication and save it"
Claude calls: marm_log_entry(entry="Research: OAuth2 is token-based with refresh cycles, better for delegated access. JWT is stateless, good for microservices...", session_name="auth-research-2025-01")
Result: Research captured in the active session log and marked for summary-cache refresh

Фаза 3: Добавить повторно используемую ссылку (Claude)

You: "Save a JWT validation code snippet to my notebooks as 'jwt-validation-pattern'"
Claude calls: marm_notebook(action="add", name="jwt-validation-pattern", data="def verify_jwt(token):\n  # validation logic...")
Result: Reusable snippet stored for future projects

Фаза 4: Вспомнить контекст (Gemini)

You: "Gemini, what authentication approaches did we research? Activate the JWT pattern."
Gemini calls: marm_smart_recall("authentication patterns", search_all=True)
Gemini calls: marm_notebook(action="use", names="jwt-validation-pattern")
Result: Gemini sees previous research + has JWT code available as context

Фаза 5: Синтез и сводка (Qwen)

You: "Qwen, pull everything from the auth research and create a summary"
Qwen calls: marm_smart_recall("authentication", session_name="auth-research-2025-01", limit=20)
Qwen calls: marm_summary(session_name="auth-research-2025-01")
Result: Qwen generates an implementation guide from all captured research

Фаза 6: Завершить сессию (Claude)

You: "Log final decision - we're using JWT for APIs, and OAuth2 for user auth"
Claude calls: marm_log_entry(entry="DECISION: JWT for API auth, OAuth2 for user flows. Rationale: stateless APIs + delegated user access", session_name="auth-research-2025-01")
Result: Decision logged and searchable by all future AI clients

Результат: Три разных AI-клиента совместно исследовали тему, обменивались идеями и документировали решения. И все это без повторного объяснения проекта каждому новому AI.

Продвинутые шаблоны

Project Structure:
├── project-name-planning/          # Initial design and requirements
├── project-name-development/       # Implementation details
├── project-name-testing/           # QA and debugging notes
├── project-name-deployment/        # Production deployment
└── project-name-retrospective/     # Lessons learned

Цикл базы знаний:

1. Захват: Используйте marm_log_entry для структурированных обучающих сессий

2. Организация: Создавайте тематические сессии для областей знаний

3. Синтез: Регулярно используйте marm_summary для консолидации знаний

4. Применение: Преобразуйте сводки в записи marm_notebook(action="add", ...)

Совместная работа нескольких AI: каждый AI работает в выделенных сессиях по своим сильным сторонам, использует marm_smart_recall для развития работы других, а затем совместная сессия объединяет полученные знания.

• Именование сессий: Включайте имя LLM для перекрестных ссылок

• Стратегическое логирование: Сосредоточьтесь на ключевых решениях, решениях проблем, открытиях, конфигурациях

• Глобальный поиск: Используйте search_all=True для поиска по всем сессиям

• Поиск на естественном языке: "проблемы аутентификации с JWT токенами" лучше, чем "ошибка аутентификации"

• Многоуровневая глубина извлечения: detail=1 возвращает краткое представление (~200 символов), detail=2 — более широкий контекст (~500 символов), detail=3 — полное содержимое памяти

• Стекирование записной книжки: Объединяйте несколько записей для сложных рабочих процессов

• Компактизация: Позвольте MARM выявлять кандидатов на компактизацию, затем используйте marm_compaction для подготовки, просмотра, применения или отклонения сводок

• Жизненный цикл сессии: Начало → Работа → Ссылка → Просмотр подготовленной компактизации, когда MARM запрашивает

Понимание памяти MARM

Два поиска, две очень разные проблемы, один инструмент:

User: "I discussed machine learning algorithms yesterday"
MARM Search: Finds related memories about "ML models", "neural networks", "AI training"

User: "What was the COMPACTION_TRIGGER_COUNT setting?"
MARM Search: Finds the exact config memory even if the rest of the text differs

Первый запрос касается смысла, поэтому MARM переранжирует кандидатов с помощью локальных векторных эмбеддингов — семантический поиск в стиле RAG без размещенной векторной базы данных. Второй имеет синтаксическую форму (ключ конфигурации), поэтому MARM автоматически обнаруживает это и направляет его через детерминированное точное сопоставление. Этот канал точного извлечения — разница между системой памяти, которая работает в демонстрациях, и той, которая отвечает на вопросы, которые разработчики действительно задают: ключи конфигурации, флаги CLI, пути к файлам, имена API, строки ошибок. Чисто семантические системы памяти терпят неудачу именно на таких запросах.

MARM использует гибридное извлечение фильтр→переранжирование плюс канал точного извлечения:

1. Точный канал (exact_mode="auto", по умолчанию): ключи конфигурации, флаги CLI, пути к файлам, имена API/инструментов, точечные пространства имен, HTTP-маршруты, URL и строки команд в кавычках обнаруживаются и направляются через детерминированный FTS5 BM25 с запасным вариантом LIKE. Эмбеддинги не используются, поэтому результаты стабильны и буквальны.

2. Канал фильтр→переранжирование: запросы на естественном языке сначала извлекают ограниченный набор кандидатов из индекса FTS (FTS_CANDIDATE_LIMIT, по умолчанию 200), затем семантические эмбеддинги переранжируют этих кандидатов по смыслу. Консервативное временное взвешивание дает более свежим воспоминаниям небольшое преимущество, когда совпадения в остальном близки.

3. Ограниченный семантический запасной вариант: когда покрытие FTS слабое или непригодно, MARM переключается на ограниченное семантическое сканирование (RECALL_SCAN_LIMIT). Если ответ включает recall_scan_truncated=true, запасной вариант достиг своего предела; сузьте сессию/запрос или увеличьте переменную окружения для больших хранилищ.

4. Оценка с учетом чанков: длинные воспоминания (примерно 180+ слов) внутренне разбиваются на перекрывающиеся строки чанков, и при извлечении оценки чанков сворачиваются обратно в одно родительское воспоминание с использованием наилучшего совпадающего чанка. Как канал переранжирования, так и запасной канал учитывают чанки.

Вот почему задержка извлечения остается почти постоянной по мере роста хранилища (см. бенчмарки): семантическое переранжирование всегда оценивает ограниченный набор вместо сканирования каждого эмбеддинга.

Управление точным извлечением: exact_mode="auto" обычно правильный. Используйте exact_mode="exact", когда запрос должен соответствовать буквальному тексту, например RECALL_SCAN_LIMIT, --generate-key или settings.py. Используйте exact_mode="semantic", когда запрос, похожий на синтаксический, все равно должен обрабатываться как извлечение на основе смысла.

Типы памяти и классификация

1. Context Logs - Автоматически классифицированные воспоминания разговоров

2. Manual Entries - Явно сохраненная важная информация

3. Notebook Entries - Повторно используемые инструкции и знания

4. Session Summaries - Сжатая история разговоров

MARM автоматически категоризирует содержимое при записи: Код (фрагменты кода и технические обсуждения), Проект (рабочие разговоры и планирование), Книга (литература, учебные материалы, исследования) и Общее (все остальное).

Атрибуция проекта и платформы

MARM хранит допускающие NULL столбцы project и platform в воспоминаниях, записях журнала и записях записной книжки. Проект определяется из рабочего каталога, а платформа — из подключающегося клиента (Claude Code, VS Code, Cursor, ...); MARM_PROJECT и MARM_PLATFORM переопределяют обнаружение. marm_smart_recall(project=..., platform=...) ограничивает извлечение, не изменяя поведение по умолчанию без фильтрации, поэтому один общий сервер может содержать несколько проектов без перекрестного загрязнения.

Графы знаний: Код и концепции

MARM поставляется с двумя системами графов, которые дополняют хранилище памяти: граф кода, который понимает структуру вашего репозитория, и граф концепций, который понимает, о чем ваши сохраненные воспоминания. Когда оба индексированы для одного проекта, сущности концепций перекрестно ссылаются на символы кода.

Граф кода: индексация репозитория и поиск кода

marm-graph встроен в оба транспорта. Он индексирует репозиторий один раз, а затем позволяет агентам задавать вопросы о структуре кода без повторного сканирования файлов:

Use marm_graph_index to index this repository.
Then use marm_code_lookup when you need symbols, files, or source snippets.
Use marm_graph_trace for call paths, marm_graph_architecture for an overview, and marm_graph_impact for change-risk checks.

Рекомендуемый рабочий процесс агента: индексировать один раз, затем marm_code_lookup перед широким чтением файлов, marm_graph_trace, когда важен контекст вызывающих/вызываемых или поток данных, marm_graph_architecture для ориентации и marm_graph_impact перед рискованными рефакторингами. Один запрос к графу заменяет десятки циклов grep/чтения, откуда и берется экономия токенов.

После индексации репозитория MARM поддерживает его актуальность самостоятельно. Фоновый опросчик замечает, когда репозиторий изменился, и переиндексирует его, поэтому нет необходимости переиндексировать вручную после коммита. Пока у вас есть незакоммиченная работа, он обновляется каждый цикл, поскольку никакая дешевая проверка не может увидеть повторные правки в уже измененном файле. Чтобы индексировать только по запросу:

marm-mcp-server projects auto off

Агент может сделать то же самое с помощью marm_graph_index(action="auto_off"), а action="auto_status" сообщает, что отслеживается и когда каждый проект был последний раз проиндексирован. Переключатель сохраняется между перезапусками и переопределяет переменную окружения GRAPH_AUTO_INDEX.

Под капотом движок — codebase-memory-mcp (MIT), статический бинарник без зависимостей, который анализирует 158 языков через tree-sitter с гибридным разрешением типов LSP для основных, индексирует средний репозиторий за секунды и отвечает на поиск символов и трассировку вызовов значительно быстрее секунды. Измерено на графе из 149 107 узлов через постоянное соединение, которое поддерживает MARM: поиск символов 146 мс, трассировка вызовов 67 мс, а полный обзор архитектуры 1,23 с — это единственный запрос, который не укладывается в секунду. MARM фиксирует конкретный релиз, проверяет его схему инструментов при запуске и направляет набор инструментов вышестоящего уровня через 5 сфокусированных MCP-инструментов, чтобы поверхность модели оставалась небольшой. Графовый бэкенд запускается лениво при первом использовании графового инструмента, поэтому инструменты памяти, журналирования, записной книжки и сводок по-прежнему запускаются быстро. В Docker бинарник движка встроен в образ; локальные pip-установки загружают его при первом использовании графа (~269 МБ, однократно).

Режим пониженной функциональности: если графовый движок не запускается (нет сети для первой загрузки, диск заполнен, расхождение схемы) или установлено GRAPH_ENABLED=false, графовые инструменты возвращают {"status": "error", "message": "graph backend unavailable"}, в то время как остальные 9 инструментов продолжают работать нормально. Сбои графа никогда не могут вывести из строя память.

Граф концепций: о чем ваши воспоминания

MARM извлекает граф знаний из сохраняемых вами воспоминаний, создавая типизированные сущности (концепции, решения, шаблоны, ошибки, инструменты, люди, организации), связанные типизированными отношениями (исправляет, реализует, зависит_от, использует, вызывает, заменяет, расширяет). Это происходит автоматически: сохранение воспоминания ставит его в очередь, и фоновый рабочий процесс добавляет его в граф примерно через 30 секунд. marm_concept_build по-прежнему доступен для полной или ограниченной перестройки. Как только граф существует, marm_smart_recall добавляет ограниченные связанные сущности, отношения и связанный код в качестве дополнительного graph_context, не изменяя основной рейтинг памяти. marm_concept_recall остается доступным для явного исследования графа:

marm_concept_recall(query="write queue")            → the entity, its relationships, linked code symbols
marm_concept_recall(query="related to SQLite", depth=3) → multi-hop traversal of everything connected

Как это использовать:

• Автоматически по умолчанию: новые воспоминания попадают в граф без вызова инструмента. Установите CONCEPT_AUTO_INDEX=false, чтобы вернуться только к ручной сборке — это останавливает воркер, но продолжает записывать строки очереди, так что при повторном включении подхватывается всё, что было записано, пока она была выключена; CONCEPT_INDEX_DEBOUNCE_SECONDS (30) и CONCEPT_INDEX_BATCH_SIZE (20) управляют темпом.

• Безопасно на обоих транспортах одновременно: арендованная блокировка в базе данных памяти предотвращает ситуацию, когда перестройка в одном процессе удаляет таблицы графа, пока другой процесс пишет в них. Сборка, обнаружившая, что граф занят, сообщает об этом вместо коллизии.

• Сбой никогда не достигает ваших воспоминаний: индексация выполняется в надёжной очереди вне пути записи. Проблемы с извлечением повторяются, воспоминание, которое многократно выходит из строя, помещается с ошибкой, а само воспоминание хранится и извлекается как обычно всё это время.

• Очистка отставания стоит некоторой скорости извлечения: извлечение сущностей требует ресурсов ЦП, поэтому, пока воркер обрабатывает очередь, измеренное время извлечения увеличивается с ~8 мс до ~16 мс медианного на реальном корпусе из 768 воспоминаний. Записи не затрагиваются. Это действует только пока отставание устраняется, что для большинства происходит один раз, после перестройки при обновлении. Воспроизведите с помощью scripts/benchmarking/performance/bench_concept_worker.py --from-live.

• Сборка для отставания: marm_concept_build с областью session_name, project или search_all=True индексирует воспоминания, сохранённые до появления автоматической индексации, и перестраивает после обновления, требующего этого.

• На данный момент два обновления: графы, построенные до атрибуции платформы или до того, как источники компактизации заменили сводки в качестве индексируемых строк, требуют marm_concept_build(search_all=True). Полная сборка создаёт резервную копию и сбрасывает только производную базу данных концептов; целевые сборки отказываются угадывать владение платформой.

• Вся область, постранично: сборки читают каждое воспоминание в области. CONCEPT_BUILD_ROW_CAP (по умолчанию 500) — размер страницы, так что его уменьшение заставляет сборку читать больше, меньших страниц, а не пропускать остальное.

• Компактизированные сессии: исходные воспоминания индексируются, а сгенерированная сводка — нет, поэтому концепты остаются привязанными к тому, где они были фактически высказаны.

• Извлечение работает с отказоустойчивостью: отсутствующий, пустой, несовместимый или недоступный граф концептов никогда не блокирует нормальное извлечение воспоминаний. Ответ сообщает статус графа отдельно.

• Перекрёстные ссылки кода: когда граф кода проиндексировал тот же проект, сущности концептов, совпадающие с символами кода, связываются, соединяя «что мы решили» с «где это находится в коде».

• Встроенная среда выполнения извлечения: среда выполнения spaCy и модель извлечения для английского языка поставляются с MARM, но загружаются только при первом извлечении, которое теперь происходит само по себе вскоре после сохранения первого воспоминания, а не при запуске сборки. Если повреждённая или частичная установка делает их недоступными, оба инструмента концептов корректно деградируют, в то время как основная память остаётся доступной; выполните marm-memory knowledge status, затем переустановите MARM, если необходимо.

• Изолированное хранилище: граф концептов находится в собственной базе данных SQLite (~/.marm/index/marm_index.db) с собственным пулом соединений, поэтому записи графа концептов никогда не могут заблокировать или повредить производственную базу данных памяти.

• Консольный атлас: MARM Console отображает полный атлас до 750 сущностей и 6000 сохранённых связей. Для более крупных графов используется детерминированная связная выборка до 600 сущностей и 4000 агрегированных визуальных рёбер, чётко помеченная как выборка.

Это заполняет пробел в структуре между сессиями, который оставляет плоский поиск по памяти: сессии организуют воспоминания, но граф концептов связывает их, так что на вопрос «что зависит от очереди записи?» можно ответить, даже если ответ охватывает пять сессий от трёх разных агентов.

Архитектура и внутреннее устройство

Всё вышеперечисленное работает на небольшом наборе продуманных механизмов. Этот раздел — полная карта, чтобы вам (или вашему агенту) никогда не приходилось гадать, что делает сервер.

Движок хранения

• SQLite в режиме WAL по адресу ~/.marm/marm_memory.db с пулом соединений (5 соединений). WAL предотвращает блокировку читателей во время записи, что важно, когда несколько агентов извлекают, пока один пишет.

• Полнотекстовый индекс FTS5 (memories_fts) поддерживается как таблица внешнего содержимого поверх таблицы воспоминаний и обеспечивает как точный путь (BM25), так и этап фильтрации гибридного извлечения.

• Хранение фрагментов: воспоминания длиной более ~180 слов разбиваются на перекрывающиеся фрагменты по 150 токенов (перекрытие 50 токенов) в таблице memory_chunks, каждый со своим встраиванием. Извлечение оценивает фрагменты и сворачивает в родительское воспоминание.

• Встраивания создаются кодировщиком jinaai/jina-embeddings-v2-small-en на основе fastembed: 33M параметров, 512 измерений, контекстное окно в 8192 токенов и лицензия Apache-2.0. Он не требует отдельных префиксов текста запроса/документа. Кодировщик лениво загружается при первом семантическом использовании и сериализуется под блокировкой, чтобы параллельные кодировки не могли повредить друг друга. Если он недоступен, записи всё равно успешны; воспоминания сохраняются без встраиваний до его загрузки. Семантическая оценка выполняется как один пакет NumPy (матричный косинус), а не как цикл Python.

• Граф концептов имеет собственную базу данных (~/.marm/index/marm_index.db) и собственный пул, используя ту же реализацию пула, но никогда не разделяя соединения с хранилищем памяти. Преднамеренная изоляция: экспериментальная сборка графа не должна иметь возможности заблокировать производственный WAL. Единственное исключение — очередь индексации, которая намеренно находится в базе данных памяти, чтобы воспоминание и его задача индексации фиксировались вместе; сам граф остаётся производным и одноразовым.

Путь записи

• Сериализованная очередь записи (включена по умолчанию): все записи воспоминаний проходят через одного внутреннего асинхронного воркера, устраняя конкуренцию писателей SQLite при многопользовательской нагрузке. Очередь универсальна; операции компактизации проходят через того же воркера, так что есть ровно один писатель независимо от того, какая подсистема пишет. MAX_QUEUE_SIZE ограничивает её.

• Консолидация во время записи (опционально, CONSOLIDATION_ENABLED=1) выполняется в два слоя до того, как воспоминание попадает в хранилище:

  • Слой 1, точная дедупликация: хеш SHA-256 нормализованного содержимого проверяется в рамках сессии; совпадения хешей проверяются на фактическое содержимое перед дедупликацией, так что коллизия хешей сохраняет новую строку вместо бесшумного слияния разного содержимого.

  • Слой 2, семантическое слияние: почти дубликаты с косинусным сходством выше CONSOLIDATION_THRESHOLD сливаются, а не накапливаются. Это никогда не блокирует запись; если кодировщик недоступен, запись продолжается без консолидации.

  • Компромисс измерен и опубликован: примерно 9-кратная медианная стоимость записи (58 мс против 6,5 мс) в обмен на чистое хранилище, поскольку чтения доминируют в рабочих нагрузках памяти. См. раздел 3 бенчмарков выше.

• Индексация концептов — это надёжный исходящий ящик: запись фиксирует задачу индексации в той же транзакции, что и воспоминание, поэтому воспоминание не может существовать без неё. Фоновый воркер обрабатывает эту очередь и записывает граф концептов. Ничто на пути записи не ждёт извлечения, и процесс, прерванный во время извлечения, не теряет работу, поскольку задача является строкой, а не задачей в памяти. Оба транспорта запускают воркер, поэтому они координируются через арендованную блокировку в базе данных памяти, а не через внутрипроцессную блокировку, которая не могла бы охватить их.

• Компактизация (опционально, COMPACTION_ENABLED=1) — это Слой 3: после достаточного количества записей в сессии фоновый проход обнаруживает кластеры связанных воспоминаний с использованием косинусного сходства и объединения-поиска связных компонентов, с порогом минимального размера кластера, минимальным возрастом и периодом ожидания активной сессии, чтобы он никогда не компактизировал выполняемую работу. Затем MARM вставляет ограниченный запрос, предлагая подключённому агенту обобщить каждый кластер: candidates → stage → review → apply или discard. Идентификаторы исходных воспоминаний сохраняются при применении, поэтому компактизированные сводки остаются отслеживаемыми до оригиналов. Поставленные сводки истекают (COMPACTION_STAGING_TTL_HOURS), напоминания ограничены по количеству и охлаждению, а вставка имеет бюджет байтов. Дизайн честен в отношении того, для чего нужны LLM: MARM обнаруживает, агент обобщает, а цикл stage/apply/discard, доступный для проверки человеком, управляет деструктивным шагом.

Путь извлечения

Рассмотрено в разделе Понимание памяти MARM: точный путь (FTS5 BM25 + запасной LIKE), фильтр→переранжирование (ограниченные кандидаты FTS → пакетное семантическое переранжирование → временное смешивание), ограниченный семантический запасной вариант с явным флагом усечения и оценка свёртки фрагментов. Глубина извлечения (detail=1/2/3) контролирует, сколько каждого воспоминания возвращается, и каждый ответ MCP проходит через ограничитель ответа в 1 МБ, который интеллектуально усекает содержимое вместо нарушения протокола.

Протокол подпроцесса графа кода

Встроенный движок графа работает как контролируемый дочерний процесс, а не как импорт:

• Транспорт: JSON-RPC 2.0 с разделителями строк через stdio дочернего процесса, с проверенным рукопожатием (initialize → захват версии сервера → initialized notification).

• Осторожность с конвертами: ответы сканируются на первый элемент содержимого, который можно разобрать как JSON, а не предполагается индекс 0, потому что вышестоящий двоичный файл может добавить уведомление об обновлении. Ошибки инструментов приходят как result.isError, а не как ошибки JSON-RPC, и преобразуются в чистые словари {"status": "error"} с прикреплённой подсказкой по исправлению от вышестоящего.

• Сериализация: одна блокировка защищает каждый цикл записи+чтения на единственном канале stdin; асинхронные вызывающие идут через asyncio.to_thread, чтобы цикл событий никогда не блокировался на вводе-выводе подпроцесса.

• Восстановление после сбоя: stderr обрабатывается в фоновом потоке, обнаруживается EOF/сбой дочернего процесса, и процесс прозрачно перезапускается при следующем вызове. Тайм-ауты намеренно не рассматриваются как сбои; длительный запуск индексации может всё ещё работать, и его прерывание уничтожило бы выполняемую работу.

• Наблюдение: ленивый синглтон-супервизор владеет клиентом на время жизни процесса. Запуск инициируется первым вызовом инструмента графа или опросчиком автоматической индексации, если двоичный файл движка уже загружен, никогда не вызывает исключение в слой MCP и проверяет схему инструментов закреплённого двоичного файла, чтобы дрейф вышестоящего был обнаружен при запуске, а не во время вызова.

• Автоматическая переиндексация опрашивается по сигнатуре git, а не отслеживается файловая система: фоновая задача сравнивает HEAD и грязное состояние каждого проиндексированного репозитория, вычисляемое запуском git вне движка, чтобы проверка бездействия не стоила блокировки движка. Коммит инициирует переиндексацию. Пока дерево грязное, репозиторий переиндексируется каждый цикл, потому что git status сообщает, какие файлы изменились, а не что в них содержится, поэтому повторные правки одного уже изменённого файла дают байт-идентичный вывод, который не может отличить никакая более дешёвая сигнатура. Git запускается с отключённым core.fsmonitor и очищенным окружением, поскольку эта настройка называет программу, которую git в противном случае выполнял бы из отслеживаемого репозитория по таймеру.

• Один шлюз для каждой мутации хранилища: ручные индексы на всех трёх поверхностях, опросчик и удаление проекта проходят через одну арендованную строку в базе данных памяти. HTTP и STDIO — это отдельные процессы с отдельными дочерними движками, использующими одно общее хранилище движка, поэтому внутрипроцессная блокировка не может охватить их. Аренда освобождается, когда вызов движка фактически возвращается, а не когда его вызывающий прекращает ожидание: отменённый запрос не может передать хранилище другому процессу, пока движок всё ещё пишет в него.

Безопасность и ограничение скорости

• Двухрежимный шлюз аутентификации: без ключа на loopback (127.0.0.1), MARM_API_KEY (Bearer) обязателен, как только сервер становится сетевым (SERVER_HOST=0.0.0.0, Docker). --generate-key создаёт его. Безопасно по умолчанию, нулевое трение настройки локально.

• IP-базированное ограничение скорости с скользящими окнами и временными блокировками, настраивается через пресеты CLI, а не через лабиринт конфигурации (таблица ниже).

• Локально-ориентированное: всё находится в ~/.marm/; нет облачной синхронизации, нет телеметрии, нет внешнего хранилища.

• Корректное завершение: обработчики SIGTERM/SIGINT очищают и закрывают пул соединений, а внутренняя система событий запускает обратные вызовы автоматизации с изоляцией ошибок для каждого обратного вызова и тайм-аутами, чтобы один плохой хук не мог заблокировать сервер.

Пресеты для роя и мультиагентных систем

Очередь записи сериализует записи в память независимо от пресета; флаги роя настраивают поверх этого лимит HTTP-запросов. Очередь управляет порядком записи; консолидация и уплотнение являются отдельными уровнями обслуживания памяти. Этот стек (WAL + пулинг + один сериализованный писатель + пресеты RPM) намеренно ограничен сценарием «SQLite, много агентов, одна машина»; распределенная многопоточная память выходит за рамки текущей архитектуры.

Самоподдерживающаяся документация

Встроенные документы индексируются в пространство памяти marm_system при запуске и обновляются каждые 50 вызовов инструментов, с отслеживанием хэша исходного файла, чтобы неизмененные документы пропускались, а измененные или удаленные строки переиндексировались. Подключенные агенты могут отвечать на вопросы об использовании MARM с помощью marm_smart_recall вместо того, чтобы вы вставляли им документацию.

Справочник по конфигурации

Устранение неполадок

По умолчанию Jina v2 Small использует 512-мерные эмбеддинги; старые данные all-MiniLM-L6-v2 имеют размерность 384 и должны быть переэмбеддированы. Остановите все процессы MARM HTTP и STDIO, затем выполните:

marm-memory maintenance embeddings migrate

Это переэмбеддирует векторы памяти, чанков и существующие векторы графа понятий (записи в блокноте больше не содержат эмбеддинги), сообщает о прогрессе, проверяет обе базы данных и может быть возобновлено после прерывания. Команда отказывается запускаться, если запущен HTTP-сервер; процессы STDIO не могут быть надежно обнаружены, поэтому их необходимо остановить вручную.

Восстановление чанкированных воспоминаний

Воспоминания длиннее 500 слов также хранятся в виде более мелких чанков. Размеры чанков менялись в разных версиях, и описанная выше миграция переэмбеддирует чанки без их повторного разделения, поэтому старые чанки сохраняют устаревшие границы. Остановите все процессы MARM, затем выполните:

marm-memory maintenance chunks rechunk

Эта команда повторно разделяет устаревшие чанки, заполняет те, что были потеряны из-за прерванной записи, и удаляет чанки из воспоминаний, которые теперь не превышают порог. Воспоминания, которые уже корректны, пропускаются без загрузки кодировщика, поэтому повторный запуск ничего не стоит. Та же защита от работающего сервера, что и выше, плюс отказ, если сохраненные векторы не соответствуют настроенной модели эмбеддинга: в этом случае сначала выполните миграцию. Восстановление работает и без этого, просто менее точно для длинных воспоминаний.

Сервер не запускается

• Проверьте версию Python: python --version (должна быть 3.10+)

• Убедитесь, что порт 8001 не занят: lsof -i :8001 (macOS/Linux) или netstat -ano | findstr :8001 (Windows)

• Проверьте ошибки прав доступа в домашней директории (~/.marm/ должна быть доступна для чтения и записи)

• См. устранение неполадок для конкретной платформы: INSTALL-DOCKER.md, INSTALL-WINDOWS.md, INSTALL-MACOS.md, INSTALL-LINUX.md

STDIO-подключение не работает

• Убедитесь, что marm-mcp-stdio находится в вашем PATH после pip install: marm-mcp-stdio --help

• Альтернативно используйте: python -m marm_mcp_server.server_stdio

• Проверьте документацию ИИ-клиента на предмет требований к транспорту STDIO

• Попробуйте прямой запуск для просмотра сообщений об ошибках: python -m marm_mcp_server.server_stdio

ИИ-клиент не может подключиться к MARM

• Убедитесь, что сервер запущен с помощью curl http://localhost:8001/health

• Проверьте, не блокирует ли брандмауэр порт 8001

• Для STDIO: используйте marm-mcp-stdio (консольный скрипт) или python -m marm_mcp_server.server_stdio

• Перезапустите сервер и ИИ-клиент

Инструменты не отображаются в ИИ-клиенте

• Проверьте HTTP-режим с помощью curl http://localhost:8001/health

• Проверьте журналы сервера на наличие ошибок инициализации

• Отключите и снова подключите ИИ-клиент, чтобы обновить список инструментов

• И HTTP, и STDIO предоставляют 14 инструментов: 7 основных инструментов для памяти/логирования/блокнота/компактации, 5 встроенных инструментов для графа кода и 2 инструмента для графа понятий

Инструменты графа возвращают graph backend unavailable

• Убедитесь, что GRAPH_ENABLED не установлен в false (влияет как на HTTP, так и на STDIO; инструменты графа полностью одинаковы для обоих транспортов)

• Первое использование графа может занять больше времени, пока запускается закрепленный движок базы кода или пока он загружается локально

• В Docker бинарный файл движка графа встроен в образ; локальные pip-установки могут загружать его при первом использовании графа

• Основные инструменты памяти продолжают работать, даже если запуск графа завершился неудачей

Инструменты понятий возвращают entities_extracted: 0

• Сначала убедитесь, что сборка понятий с областью видимости действительно включает воспоминания с извлекаемыми сущностями.

• Выполните marm-memory knowledge status; если он сообщает об отсутствии среды выполнения или модели, исправьте установку с помощью python -m pip install -U --force-reinstall marm-mcp-server.

Новые воспоминания не отображаются в графе

• Выполните marm-memory knowledge status. index_queue.pending — сколько воспоминаний ожидает; index_queue.parked — сколько было отложено. auto_index: false означает, что индексация отключена.

• Дайте время на интервал дебаунса (по умолчанию 30 секунд) плюс время извлечения. Пакет записей индексируется за один проход, а не по одному воспоминанию.

• Проверьте, что CONCEPT_AUTO_INDEX не установлен в false, 0, no или off.

• Граф, ожидающий перестроения, не индексируется. Если Консоль или marm-memory knowledge status сообщает rebuild_required, выполните marm_concept_build(search_all=True) один раз; ожидающие воспоминания будут подхвачены после этого.

• Автоматическая индексация охватывает только воспоминания, записанные после обновления. Выполните сборку один раз, чтобы включить все более старые.

• Воспоминание, которое не удалось извлечь три раза, помещается в очередь ожидания, а не повторяется бесконечно. Причина записывается вместе с задачей.

Изменения кода не отображаются в графе кода

• Выполните marm-memory projects auto status. enabled: false означает, что автоматическая переиндексация отключена; source: override означает, что сохраненное переключение отключило ее, а не переменная окружения.

• Репозиторий должен быть проиндексирован один раз, прежде чем за ним будет вестись наблюдение. marm-memory projects list показывает, что зарегистрировано.

• Дайте время на интервал (по умолчанию 30 секунд) плюс время индексации. Коммит подхватывается при следующей проверке.

• Проект, удаленный из Консоли, намеренно остается подавленным, чтобы устаревший список наблюдения не мог его воссоздать. Явная индексация повторно регистрирует его.

• Автоматическая индексация требует движка графа, который остается неактивным до тех пор, пока не будет загружен бинарный файл движка. Любой вызов инструмента графа загружает его один раз.

Индекс возвращает index_in_progress

• Другой процесс MARM удерживает шлюз индексации, обычно это опросчик другого транспорта или задание индексации в Консоли. Удаление проекта также сообщает об этом, поскольку удаление во время индексации было бы отменено. Повторите попытку через мгновение.

Сборка возвращает build_in_progress

• Другой процесс MARM записывает граф, обычно это рабочий процесс индексации другого транспорта. Сборки короткие, если это не полная перестройка; повторите попытку через мгновение.

Сборка возвращает lock_lost

• Сборка была приостановлена достаточно долго, чтобы другой процесс перехватил граф, поэтому она остановилась на полпути, а не записывала параллельно. Обычно это происходит из-за переведенного в спящий режим компьютера или паузы отладчика. Все, что было проиндексировано до остановки, сохраняется, и повторный запуск сборки завершает остальное.

Воспоминания не сохраняются

• Убедитесь, что каталог ~/.marm/ существует и имеет права на запись

• Проверьте доступное дисковое пространство

• Протестируйте с простым воспоминанием: попросите ИИ сохранить одну строку и проверьте с помощью marm_log_show

• Для HTTP-режима проверьте работоспособность сервера с помощью curl http://localhost:8001/health

Поиск не возвращает результатов

• Убедитесь, что воспоминания существуют: используйте marm_log_show для просмотра записей

• Используйте search_all=True для поиска по всем сессиям

• Попробуйте более простые, более общие поисковые запросы

• Подождите несколько секунд; первый семантический поиск загружает ML-модель

Воспоминания появляются, затем исчезают

• Проверьте, не был ли MARM перезапущен или не произошел ли сбой (данные сохраняются в ~/.marm/)

• Убедитесь, что дисковое пространство не заполнилось

• Проверьте системные журналы на наличие ошибок базы данных

Потерянные или поврежденные данные

• Немедленно остановите сервер

• Проверьте каталог ~/.marm/ на наличие резервных копий (если вы их создавали)

• Восстановите из резервной копии: скопируйте резервную копию ~/.marm/ обратно в домашнюю директорию

• Перезапустите сервер

Ошибка блокировки базы данных

• Закройте все подключения ИИ-клиентов

• Остановите сервер: Ctrl+C

• Сделайте резервную копию всего каталога базы данных: cp -r ~/.marm ~/.marm.backup

• Проверьте процессы, удерживающие базу данных: lsof ~/.marm/marm_memory.db (macOS/Linux) или проверьте Диспетчер задач (Windows)

• Если процесс удерживает блокировку, завершите его

• Проверьте целостность базы данных: sqlite3 ~/.marm/marm_memory.db "PRAGMA integrity_check;"

• Если проверка целостности не удалась, восстановите из резервной копии

• Если проверка целостности пройдена, блокировка должна быть снята; перезапустите сервер

Медленные результаты поиска

• Первый поиск медленнее (модель загружается с диска); последующие поиски быстрее

• Большие базы данных (1000+ воспоминаний) могут занимать несколько секунд

• Ограничьте поиск: используйте limit=10 вместо неограниченных результатов

• Используйте marm_summary для сжатия старых сессий

Сервер использует слишком много памяти

• Блокноты с большим количеством записей могут накапливаться; используйте marm_notebook(action="clear") для очистки активных записей

• Закройте неиспользуемые подключения ИИ-клиентов

• Используйте marm_compaction(action="review") для просмотра поэтапных сводок компактации, когда компактация включена

По вопросам поведения памяти, транспортов, поддерживаемых клиентов, компактации и резервного копирования см. FAQ.

История звёзд

Участие в разработке

MARM приветствует участников любого уровня. Код помогает, но также полезны документация, заметки по настройке, тестирование клиентов, отчёты об ошибках, бенчмарки и отзывы о реальных рабочих процессах от людей, ежедневно использующих ИИ-инструменты.

Хорошие места для помощи:

• Тестируйте MARM с большим количеством MCP-клиентов, IDE-агентов и операционных систем

• Улучшайте документацию, скриншоты, примеры и заметки по настройке для конкретных платформ

• Сообщайте об ошибках или запутанных шагах установки с чёткими деталями воспроизведения

• Делитесь рабочими процессами с памятью, привычками агентов и идеями инструментов из реального использования

• Изучайте открытые issues

💡 Хотите увидеть своё имя в этом списке? Ознакомьтесь с нашим руководством CONTRIBUTING.md, чтобы начать!

Присоединяйтесь к сообществу MARM

Помогите построить будущее ИИ-памяти — программирование не требуется!

Связь: MARM Discord | GitHub Discussions

Лицензия и уведомление об использовании

Авторские права © 2026 Райан А. Лайелл. MARM распространяется под лицензией Apache 2.0 (см. NOTICE для заявления об авторских правах). Приветствуются форки, эксперименты и интеграции. MARM также включает сторонние компоненты с открытым исходным кодом, такие как codebase-memory-mcp под лицензией MIT; см. THIRD_PARTY_NOTICES.md для указания авторства. Если вы создаете что-то на его основе, пожалуйста, делайте неофициальные версии легко отличимыми от релизов, опубликованных официальным репозиторием MARM, чтобы пользователи знали, что они устанавливают.

Документация проекта

Руководства по использованию

• README.md - Этот файл: полное руководство по использованию, справочник инструментов, рабочие процессы и архитектура

• PROTOCOL.md - Протокол работы MCP

• FAQ.md - Ответы на часто задаваемые вопросы об использовании MARM

Установка MCP-сервера

• INSTALL-DOCKER.md - Развертывание в Docker (рекомендуется)

• INSTALL-WINDOWS.md - Руководство по установке на Windows

• INSTALL-MACOS.md - Руководство по установке на macOS

• INSTALL-LINUX.md - Руководство по установке на Linux

• INSTALL-PLATFORMS.md - Руководство по установке на платформы

Информация о проекте

• CONTRIBUTING.md - Как внести вклад в MARM

• CHANGELOG.md - История версий и обновления

• ACKNOWLEDGMENTS.md - Участники и благодарности

• ROADMAP.md - Планируемые функции и дорожная карта разработки

• LICENSE - Условия лицензии Apache 2.0