Skip to content
Back to search

agent-memory-kb

Local-first, Git-backed AI-native Personal Knowledge Base & Read-Only MCP Server for Codex, Claude Code, Cursor, Antigravity & ChatGPT

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/JaydenWuGang123/agent-memory-kb with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/JaydenWuGang123/agent-memory-kb'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jaydenwugang123--agent-memory-kb/badge.svg)](/listings/jaydenwugang123--agent-memory-kb)

HTML

<a href="/listings/jaydenwugang123--agent-memory-kb"><img src="/api/listings/jaydenwugang123--agent-memory-kb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: Zero-Command Setup (Recommended for Codex / Claude / Antigravity Users)

Don't want to run terminal commands or edit JSON by hand? **Paste this single prompt directly into Codex, Claude Code, or Antigravity**:

Please clone https://github.com/JaydenWuGang123/agent-memory-kb and initialize it into ~/personal-kb (use --profile general if I am not a software developer, otherwise --profile dev). Complete the first sync, run kb_doctor.py, wire up the read-only MCP server, and add the global agent rules. Explain each step in plain language and ask me before any optional backup setup.

Option B: Manual Setup (Pure Python 3.9+ Stdlib)

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

# For developers (default, includes Git repo probe):
python3 init_kb.py --root ~/personal-kb --profile dev

# For non-developers / PMs / creators (goals & expression-preference templates):
python3 init_kb.py --root ~/personal-kb --profile general

2. Run Your First Sync, Health Check & Search

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. Connect Read-Only MCP & Offline Semantic Search (Optional)

pip install -r requirements.txt

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

4. Background Sync (macOS / Linux / Windows) & E2EE Mobile Sync (Optional)

- **macOS (`launchd` + Keychain AES-256 iCloud mirror)**: [`examples/personal-kb-sync.sh.example`](examples/personal-kb-sync.sh.example) & [`examples/launchd.personal-kb-sync.plist.example`](examples/launchd.personal-kb-sync.plist.example). - **Linux (`systemd` user timer)**: [`examples/linux-systemd/agent-memory-kb.service`](examples/linux-systemd/agent-memory-kb.service) & [`examples/linux-systemd/agent-memory-kb.timer`](examples/linux-systemd/agent-memory-kb.timer). - **Windows (PowerShell + Task Scheduler)**: [`examples/windows-sync.ps1`](examples/windows-sync.ps1). - **Zero-cost E2EE Mobile Sync**: open `~/personal-kb` in Obsidian and follow [`templates/跨设备配置.md`](templates/跨设备配置.md) (Remotely Save + OneDrive App Folder + RClone Crypt).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 145 lines
  1. # agent-memory-kb
  2. [![CI](https://github.com/JaydenWuGang123/agent-memory-kb/actions/workflows/ci.yml/badge.svg)](https://github.com/JaydenWuGang123/agent-memory-kb/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB.svg)](https://www.python.org/)
  5. [![Local-First](https://img.shields.io/badge/Local--First-Zero%20Cloud%20API%20Cost-059669.svg)](#why-agent-memory-kb)
  6. [简体中文首页 (README.zh-CN.md)](README.zh-CN.md) · [Architecture](docs/architecture.md) · [Full Reference](docs/reference.md) · [Team & FAQ](docs/team-and-faq.md)
  7. **A local-first, Git-backed, AI-native Personal Knowledge Base & Read-Only MCP Server for multi-agent developers** — connecting **Codex, Claude Code, Cursor, Antigravity, and ChatGPT** to one structured, privacy-safe, self-evolving brain on your own machine.
  8. > **Core Philosophy**: *In the AI coding era, the first reader of your knowledge base is your Agent — not you.*
  9. > Zero cloud memory API fees. 100% local Markdown + SQLite FTS5 + offline INT8 ONNX semantic search + automated AI mistake-book evolution + industrial DLP & encrypted 4-way disaster recovery.
  10. ![agent-memory-kb Terminal & Obsidian Showcase](docs/assets/demo-overview.svg)
  11. ---
  12. ## Why `agent-memory-kb`?
  13. | Dimension | Traditional Notes / Ad-Hoc Prompts | `agent-memory-kb` (Agent-First) |
  14. | --- | --- | --- |
  15. | **Capture** | Manual copy-paste; breaks coding flow, abandoned in 2 weeks | Background sync every 30 min across 5 AI tools (read-only, zero friction) |
  16. | **Cross-Agent Handoff** | 5–15 min re-explaining branch, blockers, and decisions | **~10 seconds**: Agent reads 30-line `INDEX.md` → live Git-probed project board |
  17. | **Token Overhead** | ~12k–25k tokens/session pasting history or giant rule dumps | **~3k tokens** via 3-Hop Progressive Disclosure + local SQLite Top-K retrieval |
  18. | **Repeated Mistakes** | Same bugs keep recurring across sessions | Auto-detects multi-correction sessions → deduplicated `[复发 xN]` guardrails |
  19. | **Security & Backup** | Cloud SaaS lock-in or unguarded local folders | 100% local Markdown + Keychain AES-256 + DLP `pre-commit` + 4-way restore drill |
  20. ---
  21. ## Who Is This For?
  22. Whether you write code or simply use **Codex / Claude Code / Antigravity / ChatGPT** for daily work, `agent-memory-kb` gives your AI one persistent local brain:
  23. | Role | What You Get Out of the Box |
  24. | --- | --- |
  25. | **Developers (Frontend / Backend / Indie)** | Multi-repo live Git probe, 10-second cross-agent handoff, coding mistake-book guardrails (`--profile dev`) |
  26. | **Product Managers & Operations** | Auto-archive every PRD discussion & research thread, keep confirmed decisions separated from guesses (`--profile general`) |
  27. | **Creators, Writers & Solo Founders** | Capture ideas & script iterations automatically, teach Codex your tone/style and avoid repeating edits (`--profile general`) |
  28. | **Lifelong Learners & Investors** | Track long-term reading, study plans, and personal rules across months; search exact past quotes in milliseconds (`--profile general`) |
  29. ---
  30. ## 5-Minute Quickstart
  31. ### Option A: Zero-Command Setup (Recommended for Codex / Claude / Antigravity Users)
  32. Don't want to run terminal commands or edit JSON by hand? **Paste this single prompt directly into Codex, Claude Code, or Antigravity**:
  33. ```text
  34. Please clone https://github.com/JaydenWuGang123/agent-memory-kb and initialize it into ~/personal-kb (use --profile general if I am not a software developer, otherwise --profile dev). Complete the first sync, run kb_doctor.py, wire up the read-only MCP server, and add the global agent rules. Explain each step in plain language and ask me before any optional backup setup.
  35. ```
  36. ### Option B: Manual Setup (Pure Python 3.9+ Stdlib)
  37. ```bash
  38. git clone https://github.com/JaydenWuGang123/agent-memory-kb.git
  39. cd agent-memory-kb
  40. # For developers (default, includes Git repo probe):
  41. python3 init_kb.py --root ~/personal-kb --profile dev
  42. # For non-developers / PMs / creators (goals & expression-preference templates):
  43. python3 init_kb.py --root ~/personal-kb --profile general
  44. ```
  45. ### 2. Run Your First Sync, Health Check & Search
  46. ```bash
  47. python3 ~/personal-kb/_同步/build_kb_index.py --output-root ~/personal-kb --skip-icloud
  48. python3 ~/personal-kb/_同步/kb_doctor.py --root ~/personal-kb
  49. python3 ~/personal-kb/_同步/kb_search.py --root ~/personal-kb -q "your query" --mode fts
  50. ```
  51. ### 3. Connect Read-Only MCP & Offline Semantic Search (Optional)
  52. ```bash
  53. pip install -r requirements.txt
  54. ```
  55. Register `~/personal-kb/_同步/kb_mcp.py` in Codex / Cursor / Claude Code / Antigravity using [`examples/mcp_config.example.json`](examples/mcp_config.example.json), and add [`examples/agent-rules.md`](examples/agent-rules.md) to your global agent instructions (`AGENTS.md` / `CLAUDE.md` / `GEMINI.md`).
  56. ### 4. Background Sync (macOS / Linux / Windows) & E2EE Mobile Sync (Optional)
  57. - **macOS (`launchd` + Keychain AES-256 iCloud mirror)**: [`examples/personal-kb-sync.sh.example`](examples/personal-kb-sync.sh.example) & [`examples/launchd.personal-kb-sync.plist.example`](examples/launchd.personal-kb-sync.plist.example).
  58. - **Linux (`systemd` user timer)**: [`examples/linux-systemd/agent-memory-kb.service`](examples/linux-systemd/agent-memory-kb.service) & [`examples/linux-systemd/agent-memory-kb.timer`](examples/linux-systemd/agent-memory-kb.timer).
  59. - **Windows (PowerShell + Task Scheduler)**: [`examples/windows-sync.ps1`](examples/windows-sync.ps1).
  60. - **Zero-cost E2EE Mobile Sync**: open `~/personal-kb` in Obsidian and follow [`templates/跨设备配置.md`](templates/跨设备配置.md) (Remotely Save + OneDrive App Folder + RClone Crypt).
  61. ---
  62. ## Architecture at a Glance
  63. ```mermaid
  64. flowchart TD
  65. subgraph Funnel["Horizontal: 4-Stage Knowledge Distillation Funnel"]
  66. F1["L1 · 5-Source Read-Only Archive<br/>Codex / ChatGPT / Cursor / Antigravity / Claude Code"]
  67. F2["L2 · Cold/Hot Fact Baseline<br/>个人档案.md (&lt;200 lines, dated citations + monthly cold archive)"]
  68. F3["L3 · Living Dashboards & Live Git Probe<br/>进行中的项目.md + AI协作错题本.md"]
  69. F4["L4 · Cross-Agent Guardrails & Read-Only MCP<br/>INDEX.md (~33 lines) + kb_mcp.py (5 tools) + Agent Rules"]
  70. F1 -->|"30-min sync + flock + Dual Classification"| F2
  71. F2 -->|"archive_profile.py + Evidence Gate"| F3
  72. F3 -->|"kb_retrospect.py + Pre-Flight Self-Check"| F4
  73. end
  74. subgraph Security["Vertical: 3-Tier Physical Security Isolation"]
  75. S1["Tier 1 · Machine-Only Secrets (Keychain + DLP pre-commit)"]
  76. S2["Tier 2 · Local Private Vault (Local Git + E2EE OneDrive + AES-256 iCloud + Private Git)"]
  77. S3["Tier 3 · Public Sanitized Layer (Zero business/personal data)"]
  78. end
  79. ```
  80. ---
  81. ## Core Capabilities
  82. - **5-Source Automated Capture**: Strictly read-only exporters for Codex, Cursor, Antigravity, Claude Code, and ChatGPT with `fcntl.flock` concurrency protection and 180s timeout isolation.
  83. - **Offline Hybrid Search**: SQLite FTS5 (`contentless_delete=1` + CJK unigram tokenization + synonym expansion) fused with local CPU **INT8 ONNX** embeddings via **RRF** (`kb_search.py`).
  84. - **Native Read-Only MCP Server**: 5 atomic tools (`kb_overview`, `kb_project_context`, `kb_mistakes_and_guardrails`, `kb_search_query`, `kb_read_note`) with strict root path-traversal protection.
  85. - **Self-Evolving AI Mistake Book**: Automatically detects multi-correction sessions, deduplicates root causes with `[复发 xN]` counters, and injects top guardrails into new sessions.
  86. - **Industrial DLP & 4-Way DR**: `kb_doctor.py` + `.git/hooks/pre-commit` block secret leaks, broken links, missing citations, and budget overflows; `kb_restore_verify.py` verifies 4-way Git `HEAD` parity.
  87. ---
  88. ## Deep Documentation
  89. | Guide | What's Inside |
  90. | --- | --- |
  91. | [**Architecture & Core Mechanisms**](docs/architecture.md) | Multi-agent handoff sequence diagram, 3-Hop Token Economics, CJK FTS5 + RRF design, anti-hallucination evidence chain, DLP & 4-way DR |
  92. | [**Complete Reference**](docs/reference.md) | Generated directory tree, all 5 MCP tool signatures, 16-script reference table, full `kb_config.json` schema, daily CLI cheat sheet |
  93. | [**Team Adoption & FAQ**](docs/team-and-faq.md) | Enterprise internal GitLab setup, SSOT team/personal separation, 3-phase rollout roadmap, and 8 detailed FAQs |
  94. ---
  95. ## Running Tests
  96. ```bash
  97. PERSONAL_KB_SKIP_KEYCHAIN=1 python3 -m unittest discover -s scripts -p 'test_*.py' -v
  98. ```
  99. All **16 regression unit tests** run in ~7 seconds and are continuously verified on Python 3.11 & 3.12 via GitHub Actions CI.
  100. ## License
  101. [MIT](LICENSE) — Stars, Issues, and PRs are welcome!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.