agentbrain
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
agentbrain
Local-first long-term memory for AI agents — a plain Markdown vault + a thin MCP server. 给 AI Agent 用的本地长期记忆:纯 Markdown 知识库 + 薄 MCP server。
Why agentbrain / 设计理念
Plain Markdown, no lock-in — your memory is a folder of
.mdfiles. Open it in Obsidian, grep it, version it with Git. Remove agentbrain and the memory stays.Token-efficient by design — index-first retrieval:
Index.mdis the cheap first layer, BM25 (CJK-aware) only ranks candidates, and query output is compact by default (mode='index'); full text only on demand.Append-only for agents — agents may create lessons, never edit or delete them. Consolidation happens through proposals in
_consolidations/that a human approves, which keeps multi-agent writes conflict-free.Plug-and-play via MCP — one server, every client: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...
Secrets never enter the vault — credentials live in env/keyring; lessons reference
${ENV:VAR_NAME}placeholders only, resolved at runtime via shell.
Related MCP server: pulse8-ai-cortex-knowledge-vault
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 changesChinese quickstart
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 中重复出现的模式 → 生成提升提案Connect in MCP clients (using Claude Code as an example):
claude mcp add agentbrain -- agentbrain serveGeneric MCP JSON configuration (Cursor / Open WebUI, etc.):
{
"mcpServers": {
"agentbrain": {
"command": "agentbrain",
"args": ["serve"],
"env": { "AGENTBRAIN_VAULT": "D:\\agentbrain" }
}
}
}Vault path resolution order: --vault parameter > AGENTBRAIN_VAULT environment variable > ~/agentbrain.
English quickstart
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 stdioCodex CLI (~/.codex/config.toml):
[mcp_servers.agentbrain]
command = "agentbrain"
args = ["serve"]MCP tools
Tool | Purpose |
| Search lessons. |
| Save a new lesson (facts + scenario + fix, ≤ 30 lines). Creates a file, updates Index.md and log.md. |
| Health check: duplicates, stale, expired, untagged, low-confidence. Writes a merge proposal to |
| Finds cases/tags ingested ≥ N times in the window and writes a promotion proposal. |
| Returns the owner profile (hard rules + soft preferences). Read-only; agents call it once per session to tailor behavior. |
| Proposes a profile change into |
MCP resources
URI | Content |
|
|
|
|
| merged owner profile (read-only) |
Agents are expected to follow AGENTS.md in the vault root: read the profile at
session start, query at task start, ingest on learnings, never edit existing
lessons, never write secrets into the vault. Consolidation proposals carry
machine-readable directive blocks (```agentbrain); only the owner
executes them via agentbrain apply.
Design notes
Retrieval scoring: BM25 over summary (×3), tags (×2), case id and body, with a CJK bigram tokenizer so Chinese queries work out of the box; results are boosted by
verified,use_countand recentlast_verified_at, demoted when stale (> 1 year).Self-maintenance signals: every query hit increments
use_count;log.mdfeedsmemory_distillpattern analysis;lintrefreshes nothing silently — every mutation of history goes through human-approved proposals.Single-user, local-first: no daemon, no ports; concurrent writes from several agents are serialized by a transient
.vault.lock(auto-cleaned, stale-reclaimed after 60 s), and all file writes are atomic (temp + rename) so readers never see torn files.
Changelog
0.3.1 — Data-integrity fixes: concurrent same-case ingests no longer overwrite each other (lesson-id allocation moved inside the vault lock);
confidence: 0.0round-trips correctly (was silently coerced to 0.8); lint/distill proposals are written atomically under the lock with collision-free names; merge proposals now keep the more-used lesson as the keeper; duplicate detection pre-tokenizes (O(n²) without re-tokenizing per pair). Session wrap-up rule added to AGENTS.md. 59 tests.0.3.0 — Concurrency & robustness: cross-process/thread vault write lock (
.vault.lock, re-entrant, stale-reclaim), atomic writes (temp + rename),applyis now a single transaction; query no longer rebuilds the index once per hit (one rebuild per query); stray non-lesson.mdfiles inLearnings/are ignored;confidenceclamped to [0,1]; unknownmodefalls back toindex; same-second suggestions no longer overwrite each other. 54 tests.0.2.0 — Owner profile layer (
memory_profile/memory_suggest+ MCP resources), lint/distill proposals with machine-readable directive blocks,agentbrain applywith cycle/self-supersede/dangling checks.0.1.0 — Initial MVP: vault + frontmatter + CJK-aware BM25 retrieval, MCP server (query/ingest/lint/distill) + CLI, scaffold templates.
Roadmap
Hybrid fallback search (SQLite FTS5 + local embedding, RRF fusion) for large vaults
agentbrain apply <proposal>to execute approved consolidationsOwner profile layer:
memory_profile/memory_suggest+ MCP resourcesTemp-layer bridge (Mem0-style short-term memory → distill promotions)
Keyring-backed
${ENV:...}resolution helperGit snapshot hook on ingest/distill
Development
pip install -e ".[dev]"
pytestLicense
Apache-2.0 — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Shared long-term memory vault for AI agents with 20 MCP tools.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first, file-based memory layer for AI agents — one shared Markdown vault across Claude, Codex, Gemini, Cursor and any MCP client. Provides read/write memory tools with an audit trail, per-agent trust levels, and Git sync; no cloud and no lock-in.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to persist, search, and evolve knowledge through a Markdown vault with a typed knowledge graph and MCP interface.32 PyPI15Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides local-first, project-aware durable memory for coding agents, with a human-reviewed Markdown vault, MCP daemon, and dashboard for managing and retrieving shared knowledge.56 PyPI15MIT
- AlicenseNot gradedqualityBmaintenanceDurable memory with sources, proof, history, and review for MCP-capable agents. It turns a Markdown/Obsidian vault into a local knowledge substrate, enabling agents to store, search, and retrieve governed knowledge.4,284 PyPI9AGPL 3.0