agentbrain

Lokale, langfristige Speicherung für KI-Agenten – ein einfacher Markdown-Vault + ein schlanker MCP-Server. Lokale Langzeitspeicherung für KI-Agenten: ein reiner Markdown-Wissensspeicher + ein schlanker MCP-Server.

Schnellstart auf Chinesisch · Englischer Schnellstart

Warum agentbrain / Designphilosophie

• Einfaches Markdown, keine Bindung – Ihr Speicher ist ein Ordner mit .md-Dateien. Öffnen Sie ihn in Obsidian, durchsuchen Sie ihn mit grep, versionieren Sie ihn mit Git. Entfernen Sie agentbrain und der Speicher bleibt.

• Token-effizient von Natur aus – Index-zuerst-Abfrage: Index.md ist die günstige erste Ebene, BM25 (CJK-fähig) bewertet nur Kandidaten, und die Abfrageausgabe ist standardmäßig kompakt (mode='index'); Volltext nur auf Anfrage.

• Nur-Anhängen für Agenten – Agenten dürfen Lektionen erstellen, aber nie bearbeiten oder löschen. Konsolidierung erfolgt über Vorschläge in _consolidations/, die ein Mensch genehmigt, was Mehrfach-Agenten-Schreibvorgänge konfliktfrei hält.

• Plug-and-play über MCP – ein Server, jeder Client: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...

• Geheimnisse gelangen nie in den Vault – Anmeldedaten leben in env/keyring; Lektionen referenzieren nur ${ENV:VAR_NAME}-Platzhalter, die zur Laufzeit über die Shell aufgelöst werden.

Related MCP server: layer-memory

Vault-Layout

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

Chinesischer Schnellstart

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

Einbindung in MCP-Clients (am Beispiel von Claude Code):

claude mcp add agentbrain -- agentbrain serve

Allgemeine MCP-JSON-Konfiguration (Cursor / Open WebUI usw.):

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

Vault-Pfadauflösungsreihenfolge: --vault-Parameter > AGENTBRAIN_VAULT-Umgebungsvariable > ~/agentbrain.

Englischer Schnellstart

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-Werkzeuge

MCP-Ressourcen

Von Agenten wird erwartet, dass sie AGENTS.md im Vault-Root befolgen: Profil zu Sitzungsbeginn lesen, zu Aufgabenbeginn abfragen, bei Erkenntnissen aufnehmen, bestehende Lektionen nie bearbeiten, nie Geheimnisse in den Vault schreiben. Konsolidierungsvorschläge enthalten maschinenlesbare Direktivenblöcke (agentbrain); nur der Besitzer führt sie über agentbrain apply aus.

Designhinweise

• Abruf-Bewertung: BM25 über Zusammenfassung (×3), Tags (×2), Fall-ID und Textkörper, mit einem CJK-Bigramm-Tokenizer, sodass chinesische Abfragen sofort funktionieren; Ergebnisse werden durch verified, use_count und aktuelles last_verified_at verstärkt, bei Veraltung (> 1 Jahr) herabgestuft.

• Selbstwartungssignale: Jeder Abfragetreffer erhöht use_count; log.md speist die Musteranalyse von memory_distill; lint aktualisiert nichts stillschweigend – jede Änderung der Historie erfolgt über von Menschen genehmigte Vorschläge.

• Einzelbenutzer, lokal zuerst: kein Daemon, keine Ports; gleichzeitige Schreibvorgänge mehrerer Agenten werden durch eine transiente .vault.lock serialisiert (automatisch bereinigt, nach 60 s veraltet zurückgeholt), und alle Dateischreibvorgänge sind atomar (temp + rename), sodass Leser nie zerrissene Dateien sehen.

Änderungsprotokoll

• 0.3.1 — Datenintegritätskorrekturen: Gleichzeitige Aufnahmen desselben Falls überschreiben sich nicht mehr gegenseitig (Lektions-ID-Vergabe in die Vault-Sperre verschoben); confidence: 0.0 wird korrekt rundgereicht (wurde stillschweigend auf 0.8 gezwungen); Lint/Distill-Vorschläge werden atomar unter der Sperre mit kollisionsfreien Namen geschrieben; Merge-Vorschläge behalten jetzt die häufiger verwendete Lektion als Bewahrer; Duplikaterkennung vor-tokenisiert (O(n²) ohne erneutes Tokenisieren pro Paar). Sitzungsabschlussregel zu AGENTS.md hinzugefügt. 59 Tests.

• 0.3.0 — Nebenläufigkeit & Robustheit: prozess-/threadübergreifende Vault-Schreibsperre (.vault.lock, reentrant, veraltet zurückgeholt), atomare Schreibvorgänge (temp + rename), apply ist jetzt eine einzelne Transaktion; Abfrage baut den Index nicht mehr pro Treffer neu auf (eine Neuerstellung pro Abfrage); verirrte Nicht-Lektions-.md-Dateien in Learnings/ werden ignoriert; confidence auf [0,1] begrenzt; unbekannter mode fällt auf index zurück; Vorschläge in derselben Sekunde überschreiben sich nicht mehr. 54 Tests.

• 0.2.0 — Besitzerprofilebene (memory_profile / memory_suggest + MCP-Ressourcen), Lint/Distill-Vorschläge mit maschinenlesbaren Direktivenblöcken, agentbrain apply mit Zyklus-/Selbstüberschreibungs-/Verwaistheitsprüfungen.

• 0.1.0 — Erstes MVP: Vault + Frontmatter + CJK-fähiges BM25-Abruf, MCP-Server (query/ingest/lint/distill) + CLI, Gerüstvorlagen.

Roadmap

• Hybride Fallback-Suche (SQLite FTS5 + lokale Einbettung, RRF-Fusion) für große Vaults

• agentbrain apply <proposal> zur Ausführung genehmigter Konsolidierungen

• Besitzerprofilebene: memory_profile / memory_suggest + MCP-Ressourcen

• Temp-Ebenen-Brücke (Mem0-artiges Kurzzeitgedächtnis → Distill-Beförderungen)

• Keyring-gestützter ${ENV:...}-Auflösungshelfer

• Git-Snapshot-Hook bei Ingest/Distill

Entwicklung

pip install -e ".[dev]"
pytest

Lizenz

Apache-2.0 – siehe LICENSE.