agentbrain

Локальная долговременная память для AI-агентов — простое Markdown-хранилище + тонкий MCP-сервер. Локальная долговременная память для AI-агентов: чистое Markdown-хранилище + тонкий MCP-сервер.

Китайский быстрый старт · Английский быстрый старт

Почему agentbrain / Принципы дизайна

• Простой Markdown, без привязки — ваша память — это папка с файлами .md. Открывайте её в Obsidian, ищите через grep, версионируйте через Git. Удалите agentbrain — память останется.

• Экономия токенов — поиск сначала по индексу: Index.md — дешёвый первый слой, BM25 (с поддержкой CJK) только ранжирует кандидатов, а вывод запроса по умолчанию компактный (mode='index'); полный текст — только по требованию.

• Только добавление для агентов — агенты могут создавать уроки, но никогда не редактировать и не удалять их. Консолидация происходит через предложения в _consolidations/, которые утверждает человек, что обеспечивает отсутствие конфликтов при записи несколькими агентами.

• Простое подключение через MCP — один сервер, любой клиент: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...

• Секреты никогда не попадают в хранилище — учётные данные хранятся в переменных окружения/связке ключей; уроки ссылаются только на плейсхолдеры ${ENV:VAR_NAME}, которые раскрываются во время выполнения через shell.

Related MCP server: layer-memory

Структура хранилища

agentbrain/                    # vault root (git-friendly, Obsidian-friendly)
├─ AGENTS.md                     # rules every agent reads at session start
├─ Case-Learnings/
│  ├─ Index.md                   # auto-generated lesson index (retrieval layer 1)
│  ├─ log.md                     # append-only audit log
│  ├─ Learnings/                 # one lesson per file, YAML frontmatter
│  │  └─ case-001-lesson-01.md   # 文件名 = {case_id}-lesson-{NN}，自动生成
│  └─ _consolidations/           # merge/promotion proposals (human approval)
└─ Agent-Profile/
   ├─ Immutable/                 # owner preferences & environment (agent read-only)
   ├─ Mutable-Hints/             # soft preferences (agent read-only)
   └─ _suggestions/              # agent-suggested profile changes

Китайский быстрый старт

pip install -e .                 # 需要 Python >= 3.10
agentbrain init ~/agentbrain     # 生成 vault 脚手架（幂等，可重复执行）
agentbrain ingest --case demo --lesson "部署前必须先跑迁移脚本" --tags 部署,运维
agentbrain query "部署 迁移"
agentbrain profile                # 查看个人偏好（Immutable + Mutable-Hints）
agentbrain suggest --title "回复用中文" --change "偏好简洁的中文回复"   # 提交偏好建议
agentbrain lint                    # 体检：重复/过时/无标签/低置信度 → 生成整合提案
agentbrain apply lint-20260820-172206.md   # 人工审核后执行提案（自动归档）
agentbrain distill                 # 分析 log 中重复出现的模式 → 生成提升提案

Подключение в MCP-клиенте (на примере Claude Code):

claude mcp add agentbrain -- agentbrain serve

Универсальная JSON-конфигурация MCP (Cursor / Open WebUI и т.д.):

{
  "mcpServers": {
    "agentbrain": {
      "command": "agentbrain",
      "args": ["serve"],
      "env": { "AGENTBRAIN_VAULT": "D:\\agentbrain" }
    }
  }
}

Порядок разрешения пути хранилища: аргумент --vault > переменная окружения AGENTBRAIN_VAULT > ~/agentbrain.

Английский быстрый старт

pip install -e .                 # Python >= 3.10
agentbrain init ~/agentbrain     # scaffold the vault (idempotent)
agentbrain ingest --case demo --lesson "Always run migrations before deploy" --tags deploy,ops
agentbrain query "deploy migrations"
agentbrain profile                # print the owner profile
agentbrain suggest --title "Short replies" --change "Keep answers under 3 sentences."
agentbrain lint                    # health check → consolidation proposals
agentbrain apply lint-20260820-172206.md   # execute an approved proposal (archives it)
agentbrain distill                 # recurring-pattern analysis → promotion proposals
agentbrain serve                   # start the MCP server on stdio

Codex CLI (~/.codex/config.toml):

[mcp_servers.agentbrain]
command = "agentbrain"
args = ["serve"]

MCP-инструменты

MCP-ресурсы

Ожидается, что агенты следуют AGENTS.md в корне хранилища: читают профиль в начале сессии, выполняют запрос в начале задачи, добавляют уроки при получении новых знаний, никогда не редактируют существующие уроки и не записывают секреты в хранилище. Предложения консолидации содержат машиночитаемые блоки директив ( ```agentbrain ); только владелец выполняет их через agentbrain apply.

Заметки о дизайне

• Оценка поиска: BM25 по summary (×3), tags (×2), case id и body, с биграммным токенизатором для CJK, поэтому китайские запросы работают сразу; результаты повышаются при наличии verified, use_count и недавнего last_verified_at, понижаются при устаревании (> 1 года).

• Сигналы самоподдержки: каждый результат запроса увеличивает use_count; log.md питает анализ паттернов memory_distill; lint ничего не обновляет молча — любое изменение истории проходит через одобренные человеком предложения.

• Однопользовательский, локальный: нет демона, нет портов; конкурентные записи от нескольких агентов сериализуются временным .vault.lock (автоматически очищается, устаревшие блокировки снимаются через 60 с), а все файловые записи атомарны (временный файл + переименование), поэтому читатели никогда не видят повреждённых файлов.

Журнал изменений

• 0.3.1 — Исправления целостности данных: одновременные добавления одного и того же кейса больше не перезаписывают друг друга (выделение lesson-id перенесено внутрь блокировки хранилища); confidence: 0.0 корректно проходит туда и обратно (раньше молча приводилось к 0.8); предложения lint/distill записываются атомарно под блокировкой с именами без коллизий; предложения об объединении теперь сохраняют более используемый урок; обнаружение дубликатов предварительно токенизирует (O(n²) без повторной токенизации для каждой пары). Добавлено правило завершения сессии в AGENTS.md. 59 тестов.

• 0.3.0 — Параллельность и надёжность: блокировка записи хранилища между процессами/потоками (.vault.lock, реентерабельная, со снятием устаревших), атомарные записи (временный файл + переименование), apply теперь одна транзакция; запрос больше не перестраивает индекс для каждого результата (одно перестроение на запрос); посторонние файлы .md, не являющиеся уроками, в Learnings/ игнорируются; confidence ограничено [0,1]; неизвестный mode откатывается к index; предложения, созданные в одну и ту же секунду, больше не перезаписывают друг друга. 54 теста.

• 0.2.0 — Слой профиля владельца (memory_profile / memory_suggest + MCP-ресурсы), предложения lint/distill с машиночитаемыми блоками директив, agentbrain apply с проверками циклов/самозамены/висячих ссылок.

• 0.1.0 — Начальный MVP: хранилище + frontmatter + поиск BM25 с поддержкой CJK, MCP-сервер (query/ingest/lint/distill) + CLI, шаблоны-заготовки.

Дорожная карта

• Гибридный резервный поиск (SQLite FTS5 + локальные эмбеддинги, RRF-слияние) для больших хранилищ

• agentbrain apply <proposal> для выполнения одобренных консолидаций

• Слой профиля владельца: memory_profile / memory_suggest + MCP-ресурсы

• Мост временного слоя (кратковременная память в стиле Mem0 → продвижение через distill)

• Вспомогательный инструмент для разрешения ${ENV:...} через связку ключей

• Хук создания Git-снимков при ingest/distill

Разработка

pip install -e ".[dev]"
pytest

Лицензия

Apache-2.0 — см. LICENSE.