agentbrain

AI 에이전트를 위한 로컬 우선 장기 메모리 — 일반 Markdown 볼트 + 가벼운 MCP 서버. AI 에이전트를 위한 로컬 우선 장기 메모리: 순수 Markdown 지식 베이스 + 가벼운 MCP 서버.

중국어 빠른 시작 · 영어 빠른 시작

왜 agentbrain인가 / 설계 철학

• 단순한 Markdown, 종속 없음 — 기억은 .md 파일 폴더입니다. Obsidian으로 열거나, grep 하거나, Git으로 버전을 관리할 수 있습니다. agentbrain을 제거해도 기억은 그대로 남습니다.

• 설계 단계에서 토큰 효율적 — 인덱스 우선 검색: Index.md는 저비용 1차 계층이고, BM25(CJK 인식)는 후보만 랭킹하며, 쿼리 출력은 기본적으로 간결합니다(mode='index'). 전체 텍스트는 필요할 때만 요청합니다.

• 에이전트에 대해 추가 전용(append-only) — 에이전트는 학습 항목(lesson)을 만들 수 있지만 수정하거나 삭제할 수 없습니다. 통합은 사람이 승인하는 _consolidations/ 제안을 통해서만 이루어지며, 다중 에이전트 쓰기 충돌을 방지합니다.

• MCP로 플러그 앤 플레이 — 서버 하나로 모든 클라이언트에서 사용: Claude Code, Codex CLI, OpenCode, Cursor, DSH, Open WebUI, ...

• 비밀 값은 볼트에 절대 저장하지 않음 — 자격 증명은 환경 변수/keyring에 있으며, lesson은 ${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

범용 MCP JSON 설정(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를 따라야 합니다. 세션 시작 시 프로필을 읽고, 작업 시작 시 쿼리를 실행하며, 학습 사항이 생기면 수집하고, 기존 lesson을 수정하며, 볼트에 비밀 값을 기록하지 않습니다. 통합 제안은 기계가 읽을 수 있는 명령 블록(```agentbrain)을 포함하며, 소유자만 agentbrain apply로 실행합니다.

Design notes

• 검색 점수화: 요약(×3), 태그(×2), case id와 본문에 대한 BM25와 함께 CJK 바이그램 토크나이저를 사용해 중국어 쿼리도 바로 동작합니다. 결과는 verified, use_count, 최근 last_verified_at로 가중치가 올라가고, 오래된(> 1년) 항목은 낮아집니다.

• 자기 유지 신호: 쿼리 적중할 때마다 use_count가 증가하며, log.md는 memory_distill 패턴 분석에 사용됩니다. lint는 조용히 아무것도 갱신하지 않으며, 모든 기간 변경은 사람이 승인한 제안을 거쳐서만 이루습니다.

• 단일 사용자, 로컬 우선: 데몬도 포트도 없습니다. 여러 에이전트의 동시 쓰기는 일시적 .vault.lock으로 직렬화되고(60초 후 stale로 정리됨), 모든 파일 쓰기는 임시 파일+rename 방식의 원자적 작업이 이루어지므로 읽는 중 파일이 찢어지지 않습니다.

변경 로그

• 0.3.1 — 데이터 무결성 수정: 동일 케이스의 동시 지정 사실이 서로 덮어쓰지 않도록 lesson-id 할당을 볼트 락 내부로 이동. confidence: 0.0이 0.8로 조용히 강제되지 않고 올바르게 왕복됨. lint/distill 제안이 락 하에서 충돌 없는 이름과 함께 원자적으로 작성됨. 병합 제안은 사용 빈도가 더 높은 lesson을 유지자로 선택. 중복 감지가 사전 토큰화(쌍마다 재토큰화하지 않아 O(n²)). AGENTS.md에 세션 마무리 규칙 추가. 테스트 59개.

• 0.3.0 — 동시성 및 강건성: 프로세스/스레드 교차 vault 쓰잠금(.vault.lock, 재진입, stale 회수) 및 원자적 쓰기(temp + rename). apply는 이제 단일 트랜잭션. 쿼리 적중마다 인덱스를 재구축하지 않고 쿼리당 1회만 재구축. Learnings/에 있는 lesson이 아닌 .md 파일은 무시됨. confidence는 [0,1]로 클램프됨. 알 수 없는 mode는 index로 폴백. 같은 초에 만들어진 제안이 서로 덮어쓰지 않음. 테스트 54개.

• 0.2.0 — 소유자 프로필 계층(memory_profile / memory_suggest + MCP resource), lint/distill 제안의 기계 판독 가능한 명령 블록, 순환/자기 대체/dangling 검사가 있는 agentbrain apply.

• 0.1.0 — 최초 MVP: 볼트 + frontmatter + CJK-aware BM25 검색, MCP 서버(query/ingest/lint/distill) + CLI, 스캐폴드 템플릿.

로드맵

• 대형 볼트용 하이브리드 폴백 검색 (SQLite FTS5 + 로컬 임베딩, RRF fusion)

• 승인된 통합을 실행하는 agentbrain apply <proposal>

• 소유자 프로필 계층: memory_profile / memory_suggest + MCP 리소스

• 임시 계층 브리지 (Mem0 스타일 단기 메모리 → distill 승격)

• 키링 기반 ${ENV:...} 해석 헬터

• ingest/distill 시 Git 스냅샷 훅

개발

pip install -e ".[dev]"
pytest

라이선스

Apache-2.0 — LICENSE 참조.