agentbrain

Local-first long-term memory for AI agents — a plain Markdown vault + a thin MCP server. Memoria a largo plazo local-first para agentes de IA: una bóveda Markdown simple + un servidor MCP ligero.

Inicio rápido en chino · Inicio rápido en inglés

Por qué agentbrain / Filosofía de diseño

• Markdown simple, sin dependencias — tu memoria es una carpeta de archivos .md. Ábrela en Obsidian, haz grep, versiona con Git. Elimina agentbrain y la memoria permanece.

• Eficiente en tokens por diseño — recuperación index-first: Index.md es la primera capa económica, BM25 (compatible con CJK) solo clasifica candidatos, y la salida de consulta es compacta por defecto (mode='index'); texto completo solo bajo demanda.

• Solo añadir para agentes — los agentes pueden crear lecciones, nunca editarlas ni eliminarlas. La consolidación ocurre mediante propuestas en _consolidations/ que un humano aprueba, lo que mantiene las escrituras multi-agente sin conflictos.

• Plug-and-play vía MCP — un servidor, todos los clientes: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...

• Los secretos nunca entran en la bóveda — las credenciales viven en env/keyring; las lecciones solo referencian marcadores ${ENV:VAR_NAME}, resueltos en tiempo de ejecución vía shell.

Related MCP server: layer-memory

Estructura de la bóveda

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

Inicio rápido en chino

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 中重复出现的模式 → 生成提升提案

Conecta en el cliente MCP (con Claude Code como ejemplo):

claude mcp add agentbrain -- agentbrain serve

Configuración JSON MCP genérica (Cursor / Open WebUI, etc.):

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

Orden de resolución de la ruta de la bóveda: parámetro --vault > variable de entorno AGENTBRAIN_VAULT > ~/agentbrain.

Inicio rápido en inglés

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"]

Herramientas MCP

Recursos MCP

Se espera que los agentes sigan AGENTS.md en la raíz de la bóveda: leer el perfil al inicio de la sesión, consultar al inicio de la tarea, ingerir al aprender, nunca editar lecciones existentes, nunca escribir secretos en la bóveda. Las propuestas de consolidación llevan bloques de directivas legibles por máquina (agentbrain); solo el propietario las ejecuta vía agentbrain apply.

Notas de diseño

• Puntuación de recuperación: BM25 sobre resumen (×3), etiquetas (×2), id de caso y cuerpo, con un tokenizador de bigramas CJK para que las consultas en chino funcionen de serie; los resultados se potencian con verified, use_count y last_verified_at reciente, y se degradan cuando están obsoletos (> 1 año).

• Señales de auto-mantenimiento: cada acierto de consulta incrementa use_count; log.md alimenta el análisis de patrones de memory_distill; lint no refresca nada en silencio — cada mutación del historial pasa por propuestas aprobadas por humanos.

• Un solo usuario, local-first: sin daemon, sin puertos; las escrituras concurrentes de varios agentes se serializan con un .vault.lock transitorio (auto-limpiado, reclamado tras 60 s si está obsoleto), y todas las escrituras de archivos son atómicas (temp + rename) para que los lectores nunca vean archivos rotos.

Registro de cambios

• 0.3.1 — Correcciones de integridad de datos: las ingestiones concurrentes del mismo caso ya no se sobrescriben entre sí (la asignación de id de lección se movió dentro del bloqueo de la bóveda); confidence: 0.0 se conserva correctamente (antes se forzaba silenciosamente a 0.8); las propuestas de lint/distill se escriben atómicamente bajo el bloqueo con nombres sin colisiones; las propuestas de fusión ahora mantienen la lección más usada como conservadora; la detección de duplicados pre-tokeniza (O(n²) sin re-tokenizar por par). Regla de cierre de sesión añadida a AGENTS.md. 59 pruebas.

• 0.3.0 — Concurrencia y robustez: bloqueo de escritura de la bóveda entre procesos/hilos (.vault.lock, reentrante, reclamación de obsoletos), escrituras atómicas (temp + rename), apply ahora es una transacción única; la consulta ya no reconstruye el índice una vez por acierto (una reconstrucción por consulta); los archivos .md no-lección sueltos en Learnings/ se ignoran; confidence se limita a [0,1]; el mode desconocido cae a index; las sugerencias del mismo segundo ya no se sobrescriben entre sí. 54 pruebas.

• 0.2.0 — Capa de perfil del propietario (memory_profile / memory_suggest + recursos MCP), propuestas de lint/distill con bloques de directivas legibles por máquina, agentbrain apply con comprobaciones de ciclo/auto-superación/colgantes.

• 0.1.0 — MVP inicial: bóveda + frontmatter + recuperación BM25 compatible con CJK, servidor MCP (query/ingest/lint/distill) + CLI, plantillas de andamiaje.

Hoja de ruta

• Búsqueda híbrida de respaldo (SQLite FTS5 + embedding local, fusión RRF) para bóvedas grandes

• agentbrain apply <propuesta> para ejecutar consolidaciones aprobadas

• Capa de perfil del propietario: memory_profile / memory_suggest + recursos MCP

• Puente de capa temporal (memoria a corto plazo estilo Mem0 → promociones distill)

• Helper de resolución ${ENV:...} respaldado por keyring

• Hook de snapshot Git en ingest/distill

Desarrollo

pip install -e ".[dev]"
pytest

Licencia

Apache-2.0 — ver LICENSE.