Постоянная память для ИИ-агентов кодирования
Дайте агентам кодирования долговременную память проекта между сеансами, сжатиями и сбросами контекста.
Thoth-Mem — это локальный MCP-сервер на основе SQLite и FTS5. Он сохраняет полезные решения, исправления ошибок, соглашения и непрерывность сеансов, а затем извлекает только те доказательства, которые нужны агенту. Та же установка предоставляет CLI, опциональный HTTP API и нативную интеграцию с жизненным циклом для поддерживаемых сред кодирования.
Глобальная область действия управляет конфигурацией обвязки текущего пользователя; область проекта явная и ограничена выбранным проектом и его деревом квитанций. Engram, thoth-agents или другая интеграция памяти могут пересекаться; рассматривайте это только как предупреждение: thoth-mem не редактирует, не отключает, не удаляет и не записывает во внешние репозитории.
Требуется Node.js 18 или новее. Нативная настройка необязательна: для ручного MCP-подключения нужна только команда mcp.
Запустите последний опубликованный MCP-сервер без установки глобальной команды:
npx -y thoth-mem@latest mcpЭто запускает MCP-сервер и его локальный HTTP-мост. Добавьте --no-http, если нужен только MCP-транспорт. В новых конфигурациях клиента следует использовать явную подкоманду mcp.
Нативные интеграции вызывают постоянную команду thoth-mem после настройки, поэтому установите или обновите эту команду глобально перед настройкой обвязки. Используйте npx для запуска реализации настройки из последнего опубликованного пакета, просмотрите её план без записи, а затем примените его:
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --jsonЗамените codex на opencode или claude для другой поддерживаемой обвязки, затем перезапустите эту обвязку. Сам по себе запуск setup не устанавливает и не обновляет npm-пакет.
Используйте поток репозитория, чтобы протестировать коммиты, которые ещё не были опубликованы:
pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --jsonthoth-mem@latest содержит только последний опубликованный релиз. Пересоберите и повторно выполните pnpm add -g . после получения новых неопубликованных коммитов.
Сначала обновите пакет. Если установлена нативная интеграция, повторно запустите её настройку, чтобы скопированные ресурсы, навыки, хуки и управляемые объявления пришли к новой версии пакета:
pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --jsonЗатем перезапустите обвязку или MCP-процесс. Пользователям ручного MCP не нужен setup; достаточно перезапустить npx -y thoth-mem@latest mcp.
Настройка сохраняет базу данных памяти и конфигурацию, принадлежащую пользователю. При запуске недостающие поля конфигурации могут быть заполнены автоматически, но явные значения, такие как модель LM Studio, остаются выбранными. Формат конфигурации остаётся "version": 1. Для опубликованной установки вручную обновите старый URL $schema до версии этого релиза для актуальной проверки и автодополнения в редакторе. Неопубликованная рабочая копия должна использовать config.schema.json из этого репозитория для соответствующей проверки, поскольку unpkg не может предоставить изменение до релиза. URL схемы не управляет миграцией во время выполнения.
Изменение модели эмбеддингов — это операция конфигурации, а не настройки. При необходимости отредактируйте embedding.provider, model, baseUrl и нативные dimensions; profile: "auto" разрешает поддерживаемые семейства моделей. Перезапустите thoth-mem и позвольте изменённой линии эмбеддингов поставить в очередь идемпотентную пересборку семантического индекса.
Related MCP server: LumenCore
Полезный рабочий процесс агента мал и повторяем:
Сохраните ценный урок. Используйте mem_save для решения, первопричины, соглашения или другого неочевидного факта, который должен пережить текущий контекст.
Выполняйте узкий поиск. Начните с mem_recall(mode="compact"), расширьте сильных кандидатов с помощью mode="context" и получите полную выбранную запись через mem_get.
Возобновляйте с идентичностью. Сохраняйте один и тот же стабильный session_id и project; используйте mem_context для недавней непрерывности и mem_session для событий жизненного цикла, принадлежащих корню.
Пример наблюдения:
{
"kind": "observation",
"title": "Retry SQLite writes in a new transaction",
"type": "bugfix",
"project": "my-project",
"topic_key": "sqlite/busy-retry",
"content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}Удалите содержимое внутри <private>...</private> перед сохранением. Не храните учётные данные, полные стенограммы, сгенерированные подсказки агента как намерение пользователя или необработанные журналы без извлекаемого урока.
Инструмент | Для чего используется |
| Сохранение наблюдения, реального пользовательского запроса, сводки, принадлежащей корню, или пассивное обучение. |
| Выполнение ограниченного объединённого поиска; используйте компактные результаты перед расширением контекста. |
| Чтение недавних сеансов, подсказок, наблюдений и необязательной восстановленной непрерывности. |
| Получение одного наблюдения или подсказки по ID с ограниченной пагинацией или контекстом временной шкалы. |
| Навигация по проектам, темам, представлениям графа и операционному состоянию. |
| Запуск, контрольная точка или сводка сеанса памяти, принадлежащего корню. |
Команды настройки, синхронизации, миграции, пересборки и обслуживания — это администрирование CLI/HTTP, а не дополнительные MCP-инструменты.
Сообщества — это ограниченные сводки, полученные из графа знаний проекта. Оператор создаёт или обновляет зафиксированные сводки через CLI:
thoth-mem rebuild-communities --project my-projectЗатем агент получает их через mem_project:
{
"action": "graph",
"project": "my-project",
"navigation": "community",
"limit": 5,
"max_chars": 2000
}Ответ сообщает состояние сообщества и свежесть, затем записи, такие как community=<id>, покрытие графа, уверенность, состояние деградации, ограниченную сводку и sources=obs:<id>. Просмотр сообщества требует проекта, но не узла фокуса или ID наблюдения. Если зафиксированных сводок нет, об этом сообщается вместо синтезирования глобального ответа.
Чтобы просмотреть доказательства, лежащие в основе сообщества, возьмите obs:<id> из его поля sources и вызовите mem_get(kind="observation", id=<id>). Идентификаторы наблюдений также появляются в результатах поиска. Для ограниченной окрестности графа используйте его как focus_node_id="obs:<id>" с navigation="neighborhood".
Встроенная настройка устанавливает упакованное MCP-объявление, навык памяти и хуки жизненного цикла там, где обвязка их поддерживает. Сначала просмотрите план без записи, затем повторно запустите без --plan, чтобы применить его:
Обвязка | План | Применение |
OpenCode |
|
|
Codex |
|
|
Claude Code |
|
|
Команда настройки OpenCode по умолчанию: thoth-mem setup opencode; добавьте
thoth-mem setup opencode --scope project --project /path/to/project --force
при явном нацеливании на проект или используйте
thoth-mem setup codex --rollback /path/to/receipt.json для отката в рамках квитанции.
Статус настройки и коды выхода процесса стабильны:
Статус | Код выхода |
|
|
|
|
|
|
|
|
Локальная настройка проекта явная:
thoth-mem setup opencode --scope project --project /path/to/project --plan --jsonПроверьте обнаруженные конфликты перед применением. Используйте --force только для конфликтующих расположений, для которых владение thoth-mem уже доказано. Codex 0.144.x, 0.146.x и 0.147.x входят в протестированный набор совместимости и не требуют --force. Для других версий Codex --force может переопределить только шлюз протестированной версии, если выбранная область по-прежнему предоставляет полные, независимо проверяемые возможности диспетчера плагинов; настройка выдаёт предупреждение при использовании этого переопределения. Это не обходит проверку состояния, владения, изоляции, сверки или защиты очистки и не даёт никаких полномочий в отношении несвязанной конфигурации.
Claude Code также поддерживает собственный поток маркетплейса:
claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-memВстроенная интеграция необязательна. Существующие воспоминания и MCP-сервер с шестью инструментами продолжают работать с ручным подключением.
Нативные хуки необязательны. Сохраняйте простое MCP-подключение с шестью инструментами, если вы не хотите управляемой настройки или нативного плагина; существующие воспоминания остаются доступными.
Встроенная настройка выполняется по желанию: просмотрите план без записи, проверьте конфликты, затем примените соответствующую команду обвязки. Для Codex откройте /plugins, установите thoth-mem из EremesNG/thoth-mem и проверьте состояние маркетплейса и плагина. Внешняя регистрация Codex не является атомарно обратимой, поэтому подтвердите внешнее состояние перед повторной попыткой или откатом локальной настройки.
Управляемый контракт настройки: режим плана выполняет ноль записей и только мутацию в управляемых thoth-mem расположениях. Резервные копии создаются перед первой мутацией; OpenCode принимает opencode.json или opencode.jsonc. Каждая попытка мутации записывает защищённую HMAC квитанцию со статусом in_progress перед изменениями:
глобальные квитанции: <thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json
квитанции проекта: <project>/.thoth/setup/receipts/<receipt-id>/receipt.json
Отсутствующие или подделанные квитанции завершаются сбоем. Проверенный откат сохраняет несвязанные настройки, в то время как расхождение или недоступные возможности возвращают requires_user_action. Повторная настройка и повторный завершённый откат не выполняют операций, если проверенное состояние уже совпадает.
Gemini CLI — это путь ручного MCP-клиента, а не управляемая встроенная интеграция thoth-mem. Добавьте эту запись в ~/.gemini/settings.json:
{
"mcpServers": {
"thoth": {
"command": "npx",
"args": ["-y", "thoth-mem@latest", "mcp"]
}
}
}Репозиторий содержит детерминированные команды оценки:
pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --helpeval:retrieval заполняет сигнальные наблюдения плюс отвлекающие факторы и измеряет, ранжируется ли ожидаемая память рядом с верхней частью. Читайте отчёт как набор сигналов:
Полнота и ранг показывают, были ли найдены правильные доказательства и насколько рано.
Шум и смесь случаев показывают устойчивость на прямых, перефразированных и производных от репозитория примерах.
Сжатие показывает, сколько доказательств было удалено перед доставкой контекста; это сигнал эффективности, а не доказательство того, что оставшийся текст корректен.
Дорожка и резервные доказательства показывают лексическое, семантическое необработанное/HyDE и KG-участие, включая ожидающее или деградировавшее семантическое поведение.
Происхождение и источник показывают, остаются ли возвращённые доказательства привязанными к своему источнику.
eval:kg измеряет ожидаемый отзыв субъект-отношение-объект, утечку запрещённых троек, детерминированное поведение извлечения и проверенное необязательное обогащение LLM. Отсутствующие ожидаемые факты указывают на пробелы в покрытии; запрещённые совпадения указывают на небезопасное изобретение графа.
Эти оценки являются детерминированными шлюзами разработки на курируемых и синтетических фикстурах. Они не предсказывают каждый производственный корпус, не заменяют проверку человеком, не доказывают встроенную интеграцию с обвязкой и сами по себе не оправдывают включение необязательных путей чтения сообщества. Сравнивайте отдельные случаи и сообщения об ошибках, а не рассматривайте одно агрегированное число как универсальное качество.
Входные данные семантических эмбеддингов форматируются версионированным профилем модели. auto распознаёт псевдонимы семейств моделей Nomic, EmbeddingGemma и Qwen3-Embedding; неизвестные модели используют raw и не получают предполагаемого асимметричного форматирования. Публичная конфигурация намеренно не имеет глобального поля task: намерение поиска и роль запроса/документа назначаются внутри для каждого входа, включая ответы HyDE в роли документа.
{
"embedding": {
"provider": "lmstudio",
"model": "text-embedding-embeddinggemma-300m",
"baseUrl": "http://127.0.0.1:1234",
"dimensions": 768,
"profile": "auto",
"normalize": true
}
}Поддерживаемые значения профиля: auto, nomic, embeddinggemma, qwen3 и raw. Переменные THOTH_EMBEDDING_PROFILE и THOTH_EMBEDDING_NORMALIZE переопределяют сохранённые значения. Разрешённая версия профиля и флаг нормализации являются частью родословной семантического индекса, поэтому их изменение помечает прежние векторы как устаревшие и использует существующую идемпотентную очередь перестроения.
Локальный вывод Transformers.js может выбирать конкретное устройство выполнения ONNX:
{
"embedding": {
"provider": "transformers_local",
"model": "onnx-community/embeddinggemma-300m-ONNX",
"device": "dml",
"dimensions": 768,
"profile": "auto",
"normalize": true
}
}Поддерживаемые значения устройства: auto, cpu, dml, cuda и coreml; по умолчанию используется cpu. Переменная THOTH_EMBEDDING_DEVICE переопределяет сохранённое значение embedding.device. В предварительно собранной среде выполнения Node ONNX Runtime, используемой Transformers.js, dml нацелен на DirectML в Windows, cuda — на поддерживаемые установки CUDA для Linux x64, а coreml — на macOS. Явно указанное недоступное устройство приводит к сбою инициализации модели, а не к молчаливому переключению на CPU. Значение auto делегирует порядок выбора провайдера и откат для конкретной платформы Transformers.js, поэтому фактический бэкенд может меняться в зависимости от хоста или версий зависимостей.
Выбор устройства влияет только на transformers_local; удалённые запросы Ollama и LM Studio его игнорируют. Бэкенды на GPU могут иметь существенно более медленный холодный старт, поэтому они наиболее полезны для постоянных процессов MCP или более крупных пакетов эмбеддингов. Устройство намеренно исключено из родословной семантического индекса: изменение только embedding.device не помечает существующие векторы как устаревшие и не ставит перестроение в очередь.
Примеры моделей провайдеров:
Профиль | Идентификатор модели LM Studio | Идентификатор модели Transformers.js | Собственная размерность |
Nomic | используйте точный идентификатор из |
| 768 |
EmbeddingGemma |
|
| 768 |
Qwen3-Embedding-0.6B |
|
| 1024 |
Локальное выполнение EmbeddingGemma использует sentence_embedding. Локальное выполнение Qwen применяет инструкцию поиска только к запросам и использует последний attended скрытый токен для пулинга. Все провайдеры отклоняют неполные, неконечные, нулевые или несовместимые по размерности пакеты. Индексы ответов LM Studio проверяются, а допустимые строки, идущие не по порядку, восстанавливаются в порядке ввода; отсутствующие, дублирующиеся или недопустимые индексы отклоняются. Во время поиска эти ошибки явно понижают семантический поиск, в то время как лексический поиск и поиск по графу знаний продолжают работать.
Запустите проверку качества на трёх моделях с явными идентификаторами моделей и постоянным путём вывода:
pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>Проверка требует завершения всех трёх выполнений и как минимум одного кандидата, удовлетворяющего порогам Recall@1/Recall@5/MRR без регресса любого показателя Nomic. Nomic является относительным компаратором, а не кандидатом, подлежащим абсолютным порогам. Если оба кандидата проходят, явная оценка качества и стабильное правило разрешения ничьей выбирают победителя. Отсутствующая модель, недопустимый вектор, отсутствие подходящего кандидата или сбой записи отчёта приводят к ненулевому коду выхода и сохранению текущего значения по умолчанию.
Зафиксированный прогон LM Studio от 2026-08-08 выбрал EmbeddingGemma в качестве поставляемого локального значения по умолчанию. EmbeddingGemma и Qwen3 обе завершились с Recall@1 1.00, Recall@5 1.00 и MRR 1.00, против Nomic 0.50, 1.00 и 0.7167; оба кандидата были допустимы, и EmbeddingGemma выиграла их точную ничью по качеству благодаря стабильному правилу лексического идентификатора профиля. Медианная задержка в зафиксированном решающем прогоне составила 190,5 мс для Nomic, 195 мс для EmbeddingGemma и 320,5 мс для Qwen3.
Размеры файлов Qwen3 зависят от артефакта выполнения:
Артефакт Qwen3 | Квантование | Байт | МиБ |
Оригинальный Transformers | BF16 | 1 191 586 416 | 1 136,39 |
Transformers.js | Q8 | 613 527 631 | 585,11 |
LM Studio | Q8_0 | 639 150 592 | 609,54 |
Модель Qwen3 Q8 на 304 069 133 байта больше, чем EmbeddingGemma Q8 в Transformers.js, и на 305 559 648 байт больше в LM Studio. Она также использует собственные векторы размерностью 1024 вместо 768 измерений EmbeddingGemma. Исполнитель не устанавливает и не обнаруживает модели провайдеров от имени оператора.
Увеличьте шум поиска, когда нужен более сложный локальный прогон:
$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrievalВыполните thoth-mem help для получения полного списка команд и опций CLI.
Откройте локальную панель по адресу http://localhost:7438/ и документацию OpenAPI по адресу http://localhost:7438/docs.
Используйте thoth-mem sync --dir=.thoth-sync и thoth-mem sync-import --dir=.thoth-sync для переносимости, удобной для Git.
repair-sync-journal (--project <name> | --all) --apply предварительно просматривает и внутренне связывает свой пакет исправлений. Необязательный --expected-fingerprint остаётся доступным, когда внешний рабочий процесс уже имеет предварительное связывание.
prune-operation-traces (--project <name> | --all) --apply аналогичным образом внутренне связывает один пакет хранения. Добавьте --until-complete, чтобы обработать изначально ограниченную очередь с одним фиксированным эффективным моментом и свежими более поздними отпечатками. Внешне предоставленное связывание должно включать как --expected-fingerprint, так и --effective-now.
compact-database [--data-dir <path>] выполняет предварительный просмотр только для чтения. Добавляйте --apply только после проверки его оценок освобождаемого пространства и ёмкости. Применение может потребовать удвоенного большего из физического и логического размеров базы данных, может быть заблокировано другими клиентами SQLite и сообщает об успехе только после проверок целостности, внешних ключей, схемы, устойчивого счётчика и WAL. Он использует управляемые SQLite контрольные точки и VACUUM; он не гарантирует откат после завершённой компактации.
Компактация никогда не выполняется автоматически. Запуск её на живых данных требует отдельной авторизации оператора; тесты репозитория используют только одноразовые базы данных.
Ознакомьтесь с config.schema.json для сохранённой конфигурации и настроек на основе переменных окружения.
Данные по умолчанию хранятся в ~/.thoth/thoth.db; переопределите каталог данных с помощью THOTH_DATA_DIR или --data-dir.
Семантическое индексирование не блокирует работу. Если эмбеддинги или sqlite-vec недоступны, поиск остаётся работоспособным через поддерживаемые лексические и графовые свидетельства и сообщает о пониженном канале вместо молчаливого заявления о семантическом успехе.
pnpm install
pnpm run integration:verify
pnpm run build
pnpm testBuild bounded handoff-first continuity. project_key is always required. Supply both root_session_key and harness for session context, or omit both for project context.
| Name | Required | Description | Default |
|---|---|---|---|
| harness | No | Native harness for root_session_key; supply both for session context, or omit both for project context. | |
| project_key | Yes | Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. | |
| budget_chars | No | ||
| correlation_id | No | ||
| finalize_answer | No | ||
| root_session_key | No | Optional verified root session key; supply with harness for session context, or omit both for project context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Build' suggests some construction/side effect, but the description never says whether this reads or writes, what gets persisted, whether auth is required, or how budget_chars bounds output. Only the parameter pairing rule is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose and immediately followed by the required-parameter and mode rules. Efficient, with only the opening jargon phrase costing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations and no output schema, the description covers only the identity params. It says nothing about budget_chars, correlation_id, finalize_answer, or the shape of what comes back, so an agent cannot call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 50% schema coverage, the description must compensate, and it only reinforces project_key (always required) and the root_session_key/harness pairing – both already documented in the schema. budget_chars, correlation_id, and finalize_answer receive no explanation in either place, leaving half the surface opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb+object phrase 'Build bounded handoff-first continuity' conveys a sense of producing continuity context, but 'bounded handoff-first continuity' is jargon that never plainly states what the tool actually returns or does. Nothing distinguishes it from siblings like mem_session, mem_project, or mem_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It does specify a mode rule: supply both root_session_key and harness for session context, or omit both for project context. But this is parameter-shape guidance, not tool-selection guidance – it never says when to reach for mem_context over mem_recall or mem_session, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand one selected memory, summary, observation, or evidence id returned by a prior tool result. Set history:true to include predecessor lineage for memory, summary, or observation records; evidence ids return evidence without lineage.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory, summary, observation, or evidence id returned by a prior tool result. | |
| history | No | Set true to expand predecessor lineage for memory, summary, or observation records; evidence ids have no lineage. | |
| correlation_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the conditional lineage behavior of history:true and the fact that evidence ids have no lineage, but says nothing about read-only safety, permissions, or what 'expand' actually returns (full record vs. fields).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler; the core action and its precondition come first, and the second sentence earns its place by covering the history/evidence edge case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no annotations and no output schema, the description should at minimum say what 'expand' returns and how lineage is presented. It covers the input side adequately but leaves the response shape and correlation_id unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and both id and history are already documented in the schema; the description largely restates those semantics (id from prior result, history for lineage) rather than adding syntax or format detail. The undocumented correlation_id is not covered anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Expand') and a precise resource (one memory/summary/observation/evidence id), and the phrase 'returned by a prior tool result' distinguishes it from search-style siblings like mem_recall or mem_context. It does not name an alternative sibling explicitly, so it falls short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The precondition for use is clear: you must already hold an id produced by a prior tool result, which implicitly routes the agent away from recall/search tools. There are no explicit when-not conditions or named alternatives, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect project views without mutation. action="list": no fields required. action="timeline": project_key required; optionally since, until, cursor, limit, and budget_chars. action="briefing", "summaries", or "observations": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action="history": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Required for action="history"; send a record id returned by a prior tool result. | |
| limit | No | Maximum items (1-100) for action="timeline" or "observations". | |
| since | No | Optional inclusive lower ISO-8601 instant for action="timeline" only; must be <= until. | |
| state | No | Optional state filter for action="observations". | |
| until | No | Optional inclusive upper ISO-8601 instant for action="timeline" only; must be >= since. | |
| action | Yes | Inspect project views without mutation. action="list": no fields required. action="timeline": project_key required; optionally since, until, cursor, limit, and budget_chars. action="briefing", "summaries", or "observations": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action="history": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata. | |
| cursor | No | Unchanged nextCursor from a prior mem_project action="timeline" result; keep project_key, since, and until unchanged. | |
| harness | No | Native harness for the optional root_session_key filter; supply both or omit both. Not accepted for action="timeline". | |
| temporal | No | Filter summaries/observations: current selects current summary versions or observation correction-chain leaves; history includes older summary versions or selects observation predecessors. Not accepted for action="timeline". | |
| project_key | No | Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. Required for action="timeline", "briefing", "summaries", or "observations"; not required for "list" or "history". | |
| budget_chars | No | Optional aggregate character budget for timeline, briefing, summaries, or observations; timeline clamps a positive integer to 1024-20000 characters. | |
| root_session_key | No | Optional session filter for action="briefing", "summaries", or "observations"; supply with harness or omit both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden; it explicitly says 'without mutation' (read-only), documents cursor semantics ('unchanged nextCursor'), and states list returns at most 256 aliases plus aliasCount/aliasesTruncated. It omits permissions, rate limits, and error behavior, so 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the tool purpose and then action clauses; no filler sentences. Dense for six actions but appropriately sized, so 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers action routing and key constraints, but with no output schema it explains return shape only for action='list' and leaves briefing/summaries/observations/history outputs unspecified. Schema 100% coverage offsets parameter gaps, but return transparency remains incomplete, so 3.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the top-level text repeats the action property description rather than adding new parameter meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Inspect project views without mutation' and enumerates six actions (list, timeline, briefing, summaries, observations, history), which conveys the tool's read-only inspection role. It does not distinguish mem_project from siblings like mem_recall or mem_context, so 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives action-by-action requirements (project_key required for timeline/briefing/summaries/observations, id for history, optional session filters) and notes temporal filters apply to summaries/observations, not timeline. It lacks when-not-to-use or explicit alternatives, so 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call at the start of non-trivial repository work before exploring, with task key terms, unprompted. Search promoted project memory with a non-empty query before expanding selected records. temporal="current" (default) searches current guidance; temporal="history" includes historical records. mode="compact" (default) returns bounded snippets; mode="context" adds selected memory content.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | compact (default) returns bounded snippets; context adds selected memory content. | |
| limit | No | ||
| query | Yes | Non-empty search string for promoted project memory. | |
| temporal | No | current (default) searches current guidance; history includes historical records. | |
| project_key | Yes | Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. | |
| budget_chars | No | ||
| correlation_id | No | ||
| finalize_answer | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: default values ('current', 'compact'), what each returns ('bounded snippets' vs 'adds selected memory content'), and the temporal scope difference between current guidance and historical records. It does not address permissions, error behavior, or rate limits, but the mode/temporal semantics are genuinely informative beyond the schema enums.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the call condition and search scope before mode/temporal detail, and there is little wasted text. The phrasing 'unprompted' is slightly awkward and the mode/temporal clauses duplicate schema content, costing a bit of density, but overall it is tight and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description need not explain return values, and it does describe the compact/context output difference. However, for an 8-parameter tool with half the parameters undocumented anywhere, the description leaves limit, budget_chars, correlation_id, and finalize_answer entirely unexplained, which is a notable gap for calling the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description only restates mode and temporal behavior already documented in the schema's own enum descriptions, adding no syntax or format detail for them. The other four parameters (limit, budget_chars, correlation_id, finalize_answer) are undocumented in both the description and the schema, so the description does not compensate for the coverage gap. Baseline 3 fits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search promoted project memory' with a non-empty query. It conveys the recall/search nature of the tool and gestures at its relationship to expansion ('before expanding selected records'), implicitly contrasting with a retrieval sibling like mem_get. It stops short of naming any sibling explicitly, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong when-to-use guidance: 'Call at the start of non-trivial repository work before exploring, with task key terms, unprompted,' and 'before expanding selected records.' This tells the agent both the trigger moment and the follow-up workflow. It does not explicitly name alternative tools or exclusions (e.g., when to prefer mem_context or mem_get), so it falls just shy of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save unprompted as soon as decisions, root causes, failed approaches, or non-obvious conventions are verified. Also save durable discoveries and continuation handoffs. For a direct promoted memory other than a handoff, write memory.content as concise labeled Result, Rationale, Scope, and Caveat / safe action lines. Omit Scope or Caveat / safe action when it does not apply, and never invent details to fill the template. Keep evidence compact and factual. Handoff memories keep the dedicated Objective, Completed, First pending action, Blockers, and Key files/checks format and require a stable workstream topic_key; close a finished handoff by saving its outcome under the same topic_key. Send exactly one branch: evidence (optionally + memory for a direct promoted save; structured evidence with metadata forbids memory and requires event_key plus the session pair), observation (requires event_key; session scope also requires the session pair and coverage), observation_review or observation_promotion (each requires event_key plus the session pair). Supply root_session_key and harness together or omit both.
| Name | Required | Description | Default |
|---|---|---|---|
| memory | No | Promoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion. | |
| harness | No | Native harness for root_session_key; supply both or omit both. Required wherever root_session_key is required. | |
| evidence | No | Direct evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness. | |
| event_key | No | Stable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata. | |
| observation | No | Submit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage. | |
| project_key | Yes | Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. | |
| project_name | Yes | Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output. | |
| root_session_key | No | Verified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent. | |
| observation_review | No | Review one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory. | |
| observation_promotion | No | Promote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: unprompted save timing, branch exclusivity ('Send exactly one branch'), the requirement that structured evidence forbids memory and needs event_key plus the session pair, and the topic_key lifecycle for closing handoffs. It omits what the call returns, error/failure behavior, and any auth/permission context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense and largely earns its place given four operation branches, but it is delivered as one long unbroken block of run-on sentences rather than a structured list, hurting front-loading of the branch rules. It is acceptable in length but weak in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with nested objects and no output schema, the description covers the branch logic and content templates well, but says nothing about what a successful save returns (e.g. an id) or how failures are surfaced. The very rich schema compensates on the input side, keeping this at an adequate level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 is the baseline, but the description adds real semantic value: the required content template (Result, Rationale, Scope, Caveat) and the rule not to invent details, the handoff format, and the topic_key requirement. These are usage semantics not derivable from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb (save) and precise triggers (decisions, root causes, failed approaches, non-obvious conventions), which is well beyond a tautology. It does not explicitly differentiate itself from the read-oriented siblings (mem_context, mem_recall, mem_get), though the write nature is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger ('save unprompted as soon as ... are verified') and then a detailed routing rule for the mutually exclusive branches (evidence, observation, observation_review, observation_promotion), including which branch forbids what. It stops short of naming the sibling recall tools as alternatives, but the intra-tool branch guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record verified root lifecycle events; never use it as an ordinary save. summary is optional and only valid for operation="checkpoint_pre_compact" with kind="checkpoint" or operation="finalize" with kind="final". summary.coverage starts at 1 and its to_sequence must advance the current ending sequence for this session and kind. Each claim's support_ids must be evidence ids from this project_key + root_session_key/harness session inside summary.coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | ||
| harness | Yes | Verified native harness for root_session_key in project_key. | |
| summary | No | Optional only for operation="checkpoint_pre_compact" (kind="checkpoint") or operation="finalize" (kind="final"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units. | |
| event_key | Yes | Stable lifecycle event key; retries for the same operation must resend identical content/summary. | |
| operation | Yes | Lifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final). | |
| project_key | Yes | Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. | |
| project_name | Yes | Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output. | |
| root_session_key | Yes | Stable verified root session key; required with harness for every operation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses important constraints around summary validity, coverage advancement, and support_ids scoping, but omits permissions, side effects, failure behavior, and the meaning of 'verified' lifecycle events.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core purpose before diving into summary constraints. It avoids filler, though some of its content duplicates the already-detailed schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex lifecycle tool with nested objects and no output schema, the description covers core purpose and summary rules. It is incomplete on operation-specific semantics: enroll, recover, capture_root, and guide_post_compact are not explained, leaving invocation guidance thin for a required enum parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 88%, so the schema already documents most parameters thoroughly. The description reinforces a few nested constraints around summary, coverage, and support_ids, but adds little beyond what the schema descriptions already state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: recording verified root lifecycle events. It explicitly distinguishes the tool from an ordinary save, which routes the agent away from the sibling mem_save for normal persistence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear exclusion ('never use it as an ordinary save') and specifies exactly when the optional summary payload is valid. However, it does not explain when to choose each lifecycle operation or name alternatives beyond the implicit ordinary-save sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.6mem_context13 fields changedInput schema / properties / budget_charsAdded value: +{
+ "type": "number"
+}Input schema / properties / correlation_idAdded value: +{
+ "type": "string"
+}Input schema / properties / finalize_answerAdded value: +{
+ "type": "boolean"
+}Input schema / properties / harnessAdded value: +{
+ "description": "Native harness for root_session_key; supply both for session context, or omit both for project context.",
+ "enum": [
+ "opencode",
+ "codex",
+ "claude",
+ "pi",
+ "mcp",
+ "cli",
+ "import"
+ ],
+ "type": "string"
+}Input schema / properties / limitRemoved value: -{
- "description": "Number of observations to retrieve (default: 20)",
- "type": "number"
-}Input schema / properties / max_charsRemoved value: -{
- "description": "Output character budget; 0 disables the context cap",
- "minimum": 0,
- "type": "number"
-}Input schema / properties / projectRemoved value: -{
- "description": "Filter by project name",
- "type": "string"
-}Input schema / properties / project_keyAdded value: +{
+ "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / recall_queryRemoved value: -{
- "description": "Optional query to append fused recall evidence without changing base context sections",
- "type": "string"
-}Input schema / properties / root_session_keyAdded value: +{
+ "description": "Optional verified root session key; supply with harness for session context, or omit both for project context.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / scopeRemoved value: -{
- "description": "Filter by scope",
- "enum": [
- "project",
- "personal"
- ],
- "type": "string"
-}Input schema / properties / session_idRemoved value: -{
- "description": "Filter to a specific session",
- "type": "string"
-}Input schema / requiredAdded value: +[
+ "project_key"
+]mem_get10 fields changedInput schema / properties / afterRemoved value: -{
- "description": "Timeline observations after the focus item (default: 5)",
- "maximum": 20,
- "minimum": 0,
- "type": "number"
-}Input schema / properties / beforeRemoved value: -{
- "description": "Timeline observations before the focus item (default: 5)",
- "maximum": 20,
- "minimum": 0,
- "type": "number"
-}Input schema / properties / correlation_idAdded value: +{
+ "type": "string"
+}Input schema / properties / historyAdded value: +{
+ "description": "Set true to expand predecessor lineage for memory, summary, or observation records; evidence ids have no lineage.",
+ "type": "boolean"
+}Input schema / properties / id / descriptionPrevious value: -"Record ID to retrieve, interpreted according to kind"New value: +"Memory, summary, observation, or evidence id returned by a prior tool result."Input schema / properties / id / typePrevious value: -"number"New value: +"string"Input schema / properties / include_timelineRemoved value: -{
- "description": "Include surrounding observations in the same session",
- "type": "boolean"
-}Input schema / properties / kindRemoved value: -{
- "description": "Memory kind to retrieve (defaults to observation)",
- "enum": [
- "observation",
- "prompt"
- ],
- "type": "string"
-}Input schema / properties / max_lengthRemoved value: -{
- "description": "Max characters to return (default: 50000)",
- "minimum": 100,
- "type": "number"
-}Input schema / properties / offsetRemoved value: -{
- "description": "Character offset for large content (default: 0)",
- "minimum": 0,
- "type": "number"
-}mem_project26 fields changedInput schema / properties / action / descriptionPrevious value: -"Project view to return"New value: +"Inspect project views without mutation. action=\"list\": no fields required. action=\"timeline\": project_key required; optionally since, until, cursor, limit, and budget_chars. action=\"briefing\", \"summaries\", or \"observations\": project_key required; optionally supply both root_session_key and harness to select that session's summaries/observations (briefing still includes project-wide memories). action=\"history\": id required from a prior result. temporal filters summaries/observations, not timeline. list returns at most 256 exact aliases per project plus aliasCount and aliasesTruncated metadata."Input schema / properties / action / enumPrevious value: -[
- "list",
- "summary",
- "graph",
- "topics",
- "topic",
- "health"
-]New value: +[
+ "list",
+ "timeline",
+ "briefing",
+ "history",
+ "summaries",
+ "observations"
+]Input schema / properties / budget_charsAdded value: +{
+ "description": "Optional aggregate character budget for timeline, briefing, summaries, or observations; timeline clamps a positive integer to 1024-20000 characters.",
+ "type": "number"
+}Input schema / properties / continuationRemoved value: -{
- "description": "Opaque continuation token returned by graph navigation views",
- "type": "string"
-}Input schema / properties / cursorAdded value: +{
+ "description": "Unchanged nextCursor from a prior mem_project action=\"timeline\" result; keep project_key, since, and until unchanged.",
+ "maxLength": 4096,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / focus_node_idRemoved value: -{
- "description": "Graph focus node id for navigation=neighborhood, currently obs:<id>",
- "type": "string"
-}Input schema / properties / harnessAdded value: +{
+ "description": "Native harness for the optional root_session_key filter; supply both or omit both. Not accepted for action=\"timeline\".",
+ "enum": [
+ "opencode",
+ "codex",
+ "claude",
+ "pi",
+ "mcp",
+ "cli",
+ "import"
+ ],
+ "type": "string"
+}Input schema / properties / idAdded value: +{
+ "description": "Required for action=\"history\"; send a record id returned by a prior tool result.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / include_supersededRemoved value: -{
- "description": "Explicit history opt-in; honored by navigation=superseded only",
- "type": "boolean"
-}Input schema / properties / limit / descriptionPrevious value: -"Maximum items to return"New value: +"Maximum items (1-100) for action=\"timeline\" or \"observations\"."Input schema / properties / limit / exclusiveMinimumAdded value: +0Input schema / properties / limit / maximumPrevious value: -500New value: +100Input schema / properties / limit / minimumRemoved value: -1Input schema / properties / limit / typePrevious value: -"number"New value: +"integer"Input schema / properties / max_charsRemoved value: -{
- "description": "Response character budget; 0 is supported for action=summary only",
- "maximum": 20000,
- "minimum": 0,
- "type": "integer"
-}Input schema / properties / navigationRemoved value: -{
- "description": "Graph navigation mode for action=graph; defaults to ledger",
- "enum": [
- "ledger",
- "neighborhood",
- "lineage",
- "community",
- "superseded"
- ],
- "type": "string"
-}Input schema / properties / observation_idRemoved value: -{
- "description": "Observation id for lineage or superseded graph navigation",
- "exclusiveMinimum": 0,
- "maximum": 9007199254740991,
- "type": "integer"
-}Input schema / properties / projectRemoved value: -{
- "description": "Project name. Required except action=list and optional for action=topics or health",
- "type": "string"
-}Input schema / properties / project_keyAdded value: +{
+ "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content. Required for action=\"timeline\", \"briefing\", \"summaries\", or \"observations\"; not required for \"list\" or \"history\".",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / relationRemoved value: -{
- "description": "Graph relation filter for action=graph",
- "enum": [
- "HAS_TYPE",
- "IN_PROJECT",
- "HAS_TOPIC_KEY",
- "HAS_WHAT",
- "HAS_WHY",
- "HAS_WHERE",
- "HAS_LEARNED"
- ],
- "type": "string"
-}Input schema / properties / root_session_keyAdded value: +{
+ "description": "Optional session filter for action=\"briefing\", \"summaries\", or \"observations\"; supply with harness or omit both.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / sinceAdded value: +{
+ "description": "Optional inclusive lower ISO-8601 instant for action=\"timeline\" only; must be <= until.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / stateAdded value: +{
+ "description": "Optional state filter for action=\"observations\".",
+ "enum": [
+ "pending",
+ "accepted",
+ "rejected",
+ "promoted"
+ ],
+ "type": "string"
+}Input schema / properties / temporalAdded value: +{
+ "description": "Filter summaries/observations: current selects current summary versions or observation correction-chain leaves; history includes older summary versions or selects observation predecessors. Not accepted for action=\"timeline\".",
+ "enum": [
+ "current",
+ "history"
+ ],
+ "type": "string"
+}Input schema / properties / topic_keyRemoved value: -{
- "description": "Topic key for action=topic or graph filtering",
- "type": "string"
-}Input schema / properties / untilAdded value: +{
+ "description": "Optional inclusive upper ISO-8601 instant for action=\"timeline\" only; must be >= since.",
+ "minLength": 1,
+ "type": "string"
+}mem_recall20 fields changedInput schema / properties / budget_charsAdded value: +{
+ "type": "number"
+}Input schema / properties / correlation_idAdded value: +{
+ "type": "string"
+}Input schema / properties / debugRemoved value: -{
- "description": "Include retrieval defaults and semantic input sources",
- "type": "boolean"
-}Input schema / properties / finalize_answerAdded value: +{
+ "type": "boolean"
+}Input schema / properties / hydeRemoved value: -{
- "description": "Request HyDE query expansion when configured",
- "type": "boolean"
-}Input schema / properties / limit / descriptionRemoved value: -"Maximum evidence items (default: 5)"Input schema / properties / limit / maximumRemoved value: -20Input schema / properties / limit / minimumRemoved value: -1Input schema / properties / mode / descriptionPrevious value: -"compact returns evidence lines; context includes retrieved text"New value: +"compact (default) returns bounded snippets; context adds selected memory content."Input schema / properties / projectRemoved value: -{
- "description": "Optional project filter",
- "type": "string"
-}Input schema / properties / project_keyAdded value: +{
+ "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / query / descriptionPrevious value: -"Recall/search query"New value: +"Non-empty search string for promoted project memory."Input schema / properties / scopeRemoved value: -{
- "description": "Optional scope filter",
- "enum": [
- "project",
- "personal"
- ],
- "type": "string"
-}Input schema / properties / session_idRemoved value: -{
- "description": "Optional session filter",
- "type": "string"
-}Input schema / properties / temporalAdded value: +{
+ "description": "current (default) searches current guidance; history includes historical records.",
+ "enum": [
+ "current",
+ "history"
+ ],
+ "type": "string"
+}Input schema / properties / time_fromRemoved value: -{
- "description": "Optional inclusive created_at lower bound",
- "type": "string"
-}Input schema / properties / time_toRemoved value: -{
- "description": "Optional inclusive created_at upper bound",
- "type": "string"
-}Input schema / properties / topic_keyRemoved value: -{
- "description": "Optional exact topic_key filter",
- "type": "string"
-}Input schema / properties / typeRemoved value: -{
- "description": "Optional observation type filter",
- "enum": [
- "decision",
- "architecture",
- "bugfix",
- "pattern",
- "config",
- "discovery",
- "learning",
- "session_summary",
- "manual"
- ],
- "type": "string"
-}Input schema / requiredPrevious value: -[
- "query"
-]New value: +[
+ "project_key",
+ "query"
+]mem_save19 fields changedInput schema / properties / contentRemoved value: -{
- "description": "Memory content, prompt text, session summary, or text containing a Key Learnings section",
- "type": "string"
-}Input schema / properties / event_keyAdded value: +{
+ "description": "Stable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata.",
+ "type": "string"
+}Input schema / properties / evidenceAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "content": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "root_prompt",
+ "explicit_save",
+ "checkpoint",
+ "handoff",
+ "legacy_prompt",
+ "legacy_observation",
+ "session_summary"
+ ],
+ "type": "string"
+ },
+ "source_ref": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "content"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "content": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "const": "explicit_save",
+ "type": "string"
+ },
+ "metadata": {
+ "additionalProperties": false,
+ "properties": {
+ "observation_validation": {
+ "additionalProperties": false,
+ "properties": {
+ "method": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "observation_id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "result": {
+ "enum": [
+ "passed",
+ "failed"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "observation_id",
+ "result",
+ "method"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "observation_validation"
+ ],
+ "type": "object"
+ },
+ "source_ref": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "content",
+ "metadata"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "content": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "const": "handoff",
+ "type": "string"
+ },
+ "metadata": {
+ "additionalProperties": false,
+ "properties": {
+ "observation_review_attestation": {
+ "additionalProperties": false,
+ "properties": {
+ "method": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "observation_id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "reviewer": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "verdict": {
+ "enum": [
+ "accepted",
+ "rejected"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "observation_id",
+ "verdict",
+ "reviewer",
+ "method"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "observation_review_attestation"
+ ],
+ "type": "object"
+ },
+ "source_ref": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "content",
+ "metadata"
+ ],
+ "type": "object"
+ }
+ ],
+ "description": "Direct evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness."
+}Input schema / properties / harnessAdded value: +{
+ "description": "Native harness for root_session_key; supply both or omit both. Required wherever root_session_key is required.",
+ "enum": [
+ "opencode",
+ "codex",
+ "claude",
+ "pi",
+ "mcp",
+ "cli",
+ "import"
+ ],
+ "type": "string"
+}Input schema / properties / kindRemoved value: -{
- "description": "Write mode. Defaults to observation",
- "enum": [
- "observation",
- "prompt",
- "session_summary",
- "passive_learnings"
- ],
- "type": "string"
-}Input schema / properties / memoryAdded value: +{
+ "additionalProperties": false,
+ "description": "Promoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion.",
+ "properties": {
+ "content": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "decision",
+ "convention",
+ "architecture",
+ "discovery",
+ "failure",
+ "project_structure",
+ "handoff",
+ "preference"
+ ],
+ "type": "string"
+ },
+ "outcome": {
+ "enum": [
+ "unknown",
+ "succeeded",
+ "failed",
+ "mixed"
+ ],
+ "type": "string"
+ },
+ "supersedes_id": {
+ "type": "string"
+ },
+ "title": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "topic_key": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "title",
+ "content"
+ ],
+ "type": "object"
+}Input schema / properties / observationAdded value: +{
+ "additionalProperties": false,
+ "description": "Submit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage.",
+ "properties": {
+ "claim": {
+ "maxLength": 4000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "concepts": {
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 16,
+ "type": "array"
+ },
+ "coverage": {
+ "additionalProperties": false,
+ "properties": {
+ "from_sequence": {
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ },
+ "to_sequence": {
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "from_sequence",
+ "to_sequence"
+ ],
+ "type": "object"
+ },
+ "files": {
+ "items": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 16,
+ "type": "array"
+ },
+ "generator": {
+ "additionalProperties": false,
+ "properties": {
+ "config_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "root_agent",
+ "harness",
+ "model"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "version": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "name"
+ ],
+ "type": "object"
+ },
+ "kind": {
+ "enum": [
+ "decision",
+ "constraint",
+ "fact",
+ "procedure",
+ "result",
+ "failure",
+ "preference"
+ ],
+ "type": "string"
+ },
+ "predecessor_id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "proposed_memory": {
+ "additionalProperties": false,
+ "properties": {
+ "content": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "decision",
+ "convention",
+ "architecture",
+ "discovery",
+ "failure",
+ "project_structure",
+ "handoff",
+ "preference"
+ ],
+ "type": "string"
+ },
+ "outcome": {
+ "enum": [
+ "unknown",
+ "succeeded",
+ "failed",
+ "mixed"
+ ],
+ "type": "string"
+ },
+ "title": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "topic_key": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "title",
+ "content"
+ ],
+ "type": "object"
+ },
+ "scope": {
+ "enum": [
+ "session",
+ "project"
+ ],
+ "type": "string"
+ },
+ "support_ids": {
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 16,
+ "minItems": 1,
+ "type": "array"
+ },
+ "title": {
+ "maxLength": 500,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "scope",
+ "title",
+ "claim",
+ "proposed_memory",
+ "support_ids",
+ "generator"
+ ],
+ "type": "object"
+}Input schema / properties / observation_promotionAdded value: +{
+ "additionalProperties": false,
+ "description": "Promote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+ "properties": {
+ "observation_id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "observation_id"
+ ],
+ "type": "object"
+}Input schema / properties / observation_reviewAdded value: +{
+ "additionalProperties": false,
+ "description": "Review one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+ "properties": {
+ "basis": {
+ "enum": [
+ "root_user_confirmed",
+ "observable_validation",
+ "independent_review"
+ ],
+ "type": "string"
+ },
+ "observation_id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "policy": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "version": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "version"
+ ],
+ "type": "object"
+ },
+ "reason": {
+ "maxLength": 1000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "support_ids": {
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 16,
+ "minItems": 1,
+ "type": "array"
+ },
+ "verdict": {
+ "enum": [
+ "accepted",
+ "rejected"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "observation_id",
+ "verdict",
+ "basis",
+ "policy",
+ "reason",
+ "support_ids"
+ ],
+ "type": "object"
+}Input schema / properties / projectRemoved value: -{
- "description": "Project name",
- "type": "string"
-}Input schema / properties / project_keyAdded value: +{
+ "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / project_nameAdded value: +{
+ "description": "Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / root_session_keyAdded value: +{
+ "description": "Verified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent.",
+ "type": "string"
+}Input schema / properties / scopeRemoved value: -{
- "description": "Observation scope",
- "enum": [
- "project",
- "personal"
- ],
- "type": "string"
-}Input schema / properties / session_idRemoved value: -{
- "description": "Session ID (default: manual-save-{project})",
- "type": "string"
-}Input schema / properties / titleRemoved value: -{
- "description": "Short searchable title. Required for kind=observation",
- "type": "string"
-}Input schema / properties / topic_keyRemoved value: -{
- "description": "Stable key for observation upserts",
- "type": "string"
-}Input schema / properties / typeRemoved value: -{
- "description": "Observation category for kind=observation",
- "enum": [
- "decision",
- "architecture",
- "bugfix",
- "pattern",
- "config",
- "discovery",
- "learning",
- "session_summary",
- "manual"
- ],
- "type": "string"
-}Input schema / requiredPrevious value: -[
- "content"
-]New value: +[
+ "project_key",
+ "project_name"
+]mem_session17 fields changedInput schema / properties / actionRemoved value: -{
- "description": "Session action",
- "enum": [
- "start",
- "summary",
- "checkpoint"
- ],
- "type": "string"
-}Input schema / properties / content / descriptionRemoved value: -"Full session summary for action=summary"Input schema / properties / directoryRemoved value: -{
- "description": "Working directory for action=start",
- "type": "string"
-}Input schema / properties / event_keyAdded value: +{
+ "description": "Stable lifecycle event key; retries for the same operation must resend identical content/summary.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / harnessAdded value: +{
+ "description": "Verified native harness for root_session_key in project_key.",
+ "enum": [
+ "opencode",
+ "codex",
+ "claude",
+ "pi",
+ "mcp",
+ "cli",
+ "import"
+ ],
+ "type": "string"
+}Input schema / properties / idRemoved value: -{
- "description": "Session ID. Required for action=start; defaults to manual-save-{project} for summary/checkpoint",
- "type": "string"
-}Input schema / properties / operationAdded value: +{
+ "description": "Lifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final).",
+ "enum": [
+ "enroll",
+ "recover",
+ "capture_root",
+ "checkpoint_pre_compact",
+ "guide_post_compact",
+ "finalize"
+ ],
+ "type": "string"
+}Input schema / properties / projectRemoved value: -{
- "description": "Project name",
- "type": "string"
-}Input schema / properties / project_keyAdded value: +{
+ "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / project_nameAdded value: +{
+ "description": "Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / root_session_keyAdded value: +{
+ "description": "Stable verified root session key; required with harness for every operation.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / summary / additionalPropertiesAdded value: +falseInput schema / properties / summary / descriptionPrevious value: -"Short checkpoint summary for action=checkpoint"New value: +"Optional only for operation=\"checkpoint_pre_compact\" (kind=\"checkpoint\") or operation=\"finalize\" (kind=\"final\"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units."Input schema / properties / summary / propertiesAdded value: +{
+ "claims": {
+ "description": "1-32 atomic supported claims; keep the canonical summary within 20000 UTF-16 units.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "content": {
+ "description": "Atomic claim content; at most 2000 code points after privacy filtering.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "objective",
+ "completed",
+ "decision",
+ "changed_surface",
+ "verification",
+ "pending",
+ "blocker",
+ "next_action"
+ ],
+ "type": "string"
+ },
+ "outcome": {
+ "enum": [
+ "unknown",
+ "succeeded",
+ "failed",
+ "mixed"
+ ],
+ "type": "string"
+ },
+ "support_ids": {
+ "description": "1-16 distinct evidence ids from this project_key + root_session_key/harness session inside summary.coverage; never memory, summary, or observation ids.",
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 16,
+ "minItems": 1,
+ "type": "array"
+ }
+ },
+ "required": [
+ "kind",
+ "content",
+ "support_ids"
+ ],
+ "type": "object"
+ },
+ "maxItems": 32,
+ "minItems": 1,
+ "type": "array"
+ },
+ "coverage": {
+ "additionalProperties": false,
+ "description": "Inclusive session evidence coverage; start at 1 and advance to_sequence for this session and summary kind.",
+ "properties": {
+ "from_sequence": {
+ "description": "Inclusive first session event sequence; must start at 1.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ },
+ "to_sequence": {
+ "description": "Inclusive last session event sequence; must be >= from_sequence and exceed the current summary ending sequence for this session and kind.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "from_sequence",
+ "to_sequence"
+ ],
+ "type": "object"
+ },
+ "generator": {
+ "additionalProperties": false,
+ "properties": {
+ "config_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "kind": {
+ "enum": [
+ "root_agent",
+ "harness",
+ "model"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "version": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind",
+ "name"
+ ],
+ "type": "object"
+ },
+ "kind": {
+ "description": "Send checkpoint for operation=\"checkpoint_pre_compact\" or final for operation=\"finalize\".",
+ "enum": [
+ "checkpoint",
+ "final"
+ ],
+ "type": "string"
+ }
+}Input schema / properties / summary / requiredAdded value: +[
+ "kind",
+ "coverage",
+ "generator",
+ "claims"
+]Input schema / properties / summary / typePrevious value: -"string"New value: +"object"Input schema / requiredPrevious value: -[
- "action",
- "project"
-]New value: +[
+ "operation",
+ "harness",
+ "project_key",
+ "project_name",
+ "root_session_key",
+ "event_key"
+]v0.4.13mem_contextmem_getmem_projectmem_savemem_sessionv0.4.1mem_contextmem_getmem_projectmem_savemem_sessionv0.3.7mem_contextmem_getmem_projectmem_recallmem_savemem_sessionScored across 6 tools
Write vs. read paths are distinguishable (mem_save, mem_session vs. recall/get/context/project), but the read surface overlaps heavily: mem_context, mem_recall, mem_project, and mem_get all retrieve memory/continuity, and the dense, clause-heavy descriptions are what carry the distinction. An agent could plausibly choose the wrong retrieval tool without careful reading.
All six tools share a clean mem_ prefix and snake_case, which is highly predictable. However, the stems mix verbs (save, recall, get) with nouns (context, project, session), so the pattern is prefix-consistent rather than a strict verb_noun scheme.
Six tools for a memory/continuity server is well-scoped: write (mem_save, mem_session), search/expand (mem_recall, mem_get), context assembly (mem_context), and inspection (mem_project). Each tool covers a distinct capability and none feels redundant in count alone.
The surface covers create, search, expand, context, and project inspection, but there is no update, edit, forget, or delete operation for memories—only new saves and historical lineage. Agents cannot correct or remove a bad memory, which is a notable lifecycle gap for a memory store.
Persistent memory for AI agents. Search, store, and recall across sessions.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
