Skip to main content
Glama
agent-memory-kb MCP Server

agent-memory-kb MCP Server

agent-memory-kb

中文文档 (README.zh-CN.md)

A local-first, Git-backed, AI-native Personal Knowledge Base & Read-Only MCP Server for multi-agent developers (Codex, Claude Code, Cursor, Antigravity, and ChatGPT).

Zero cloud memory API fees. 100% local Markdown + SQLite FTS5 + offline INT8 ONNX semantic vectors + automated AI mistake-book evolution + industrial-grade DLP & encrypted disaster recovery.


Why agent-memory-kb?

Developers juggling multiple AI coding agents hit the same four walls:

  1. Fragmented memory: Conversations and decisions are trapped inside Codex, Cursor, Claude Code, Antigravity, and ChatGPT silos.

  2. Context rot & bloat: Dumping giant markdown notes into prompts wastes tokens and decays over time.

  3. Repeated AI mistakes: You correct an agent 3 times today, and tomorrow a new session makes the exact same mistake.

  4. Privacy & backup risk: Cloud memory services require sending private code/life notes to third-party APIs; DIY repos risk leaking tokens or losing history.

agent-memory-kb solves all four with a 3-Tier Isolation + 4-Stage Distillation Funnel architecture:

flowchart TD
    subgraph Funnel["4-Stage Knowledge Distillation Funnel"]
        F1["L1: 5-Source Auto Capture<br/>Codex / ChatGPT / Cursor / Antigravity / Claude Code"]
        F2["L2: Fact Baseline & Changelog<br/>个人档案.md (Hot Snapshot + Monthly Cold Archive)"]
        F3["L3: Living Dashboards & Active Git Probe<br/>INDEX.md + 笔记/进行中的项目.md + AI协作错题本.md"]
        F4["L4: Cross-Agent Guardrails & Read-Only MCP<br/>kb_mcp.py (Hybrid FTS5 + ONNX RRF) + Agent Rules"]
        F1 -->|"30-min launchd + Dual Classification"| F2
        F2 -->|"Auto Cold-Archive + Citations"| F3
        F3 -->|"Retrospect Queue + Guardrails"| F4
    end

Related MCP server: shelfmark

Core Capabilities

Layer

Capabilities

5-Source Automated Capture

Incremental read-only exporters for Codex, Cursor, Antigravity, Claude Code, and ChatGPT (scripts/export_*.py) into clean, traceable Markdown.

Offline Hybrid Search

SQLite FTS5 (contentless_delete=1 + CJK unigram & natural-language rescue) fused with local offline INT8 ONNX multilingual embeddings (kb_embed.py) via RRF (kb_search.py). Zero API cost.

Native Read-Only MCP Server

scripts/kb_mcp.py exposes 5 tools (kb_overview, kb_search_query, kb_project_context, kb_mistakes_and_guardrails, kb_read_note) with strict root path-traversal protection for Codex, Cursor, Claude Code, and Antigravity.

AI Mistake-Book Closed Loop

scripts/kb_retrospect.py automatically detects high-friction multi-correction conversations, maintains a pending review queue, and injects Top guardrails into new agent sessions.

Industrial DLP & Health Gate

scripts/kb_filters.py + scripts/kb_doctor.py bound to .git/hooks/pre-commit: blocks JWT, Bearer, Cookie, DB DSN passwords, .env keys, ID numbers, contextual high-entropy secrets, broken links, missing citations, budget overflows, and stale project notes.

4-Way Disaster Recovery

Local Git + atomic git bundle + macOS Keychain AES-256 encrypted iCloud bundle (with decrypt round-trip check & orphan temp cleanup) + private Git remote (with anti-public-URL safety gate) + isolated clone restore drill (kb_restore_verify.py).

Zero-Cost E2EE Mobile Sync

Ready-to-use Obsidian + Remotely Save (OneDrive App Folder + RClone Crypt) workflow & ignore patterns (templates/跨设备配置.md).


5-Minute Quickstart

1. Clone & Initialize Your Local Knowledge Base

git clone https://github.com/JaydenWuGang123/agent-memory-kb.git
cd agent-memory-kb

# Bootstrap a fresh local KB repo (defaults to ~/personal-kb)
python3 init_kb.py --root ~/personal-kb

2. Run Your First Sync & Health Check (Zero External Dependencies)

Core indexing, FTS5 search, DLP checks, Git snapshots, and backup verification only require Python 3.9+ stdlib:

python3 ~/personal-kb/_同步/build_kb_index.py --output-root ~/personal-kb --skip-icloud
python3 ~/personal-kb/_同步/kb_doctor.py --root ~/personal-kb
python3 ~/personal-kb/_同步/kb_search.py --root ~/personal-kb -q "your query" --mode fts

3. (Optional) Enable Read-Only MCP Server & Local ONNX Semantic Vectors

pip install -r requirements.txt

Register ~/personal-kb/_同步/kb_mcp.py in Codex / Cursor / Claude Code / Antigravity using examples/mcp_config.example.json, and drop examples/agent-rules.md into your global agent instructions (AGENTS.md / CLAUDE.md / GEMINI.md).

4. (Optional) Enable 30-Minute Background Sync & Encrypted iCloud Mirror (macOS)

  1. Copy examples/personal-kb-sync.sh.example to ~/.local/bin/personal-kb-sync.sh and chmod +x.

  2. Store an encryption passphrase in macOS Keychain (never stored in files):

    security add-generic-password -U -a "$USER" -s "agent-memory-kb.icloud-bundle" -w
  3. Load examples/launchd.personal-kb-sync.plist.example into ~/Library/LaunchAgents/ (grant /bin/zsh Full Disk Access if backing up to iCloud Drive in background).


Running Tests

python3 -m unittest discover -s scripts -p 'test_*.py' -v

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.
      2
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search, read, create, and maintain a local-first knowledge base using hybrid retrieval and Markdown note management through the Model Context Protocol.
      14 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides coding agents with persistent local memory by exposing tools to save, search, and retrieve decisions, bugs, and context as Markdown with hybrid keyword and semantic search.
      4
      MIT