知识库管理工具

---
last-verified-commit: a60044b1010084ebdb0a054e661bb8e8cb85829c
last-verified-at: 2026-04-25T15:30:00.000Z
code-repo: /Users/dante/develop/auto-hotelier
code-tracks: ["packages/db/prisma/schema.prisma","packages/db/prisma/migrations/"]
---

# Doc title
... body ...

git clone https://github.com/Dantesong/knowledge-mcp.git
cd knowledge-mcp
npm install
npm run build

mkdir -p ~/knowledge/{systems,ops,decisions}
cd ~/knowledge && git init
echo "# Knowledge Base" > ~/knowledge/_index.md
git add -A && git commit -m "init: knowledge base"

~/knowledge/
├── _index.md          ← Auto-generated index (rebuilt by kb_index)
├── systems/           ← System architecture docs
├── ops/               ← Operations & deployment docs
└── decisions/         ← Technical decision log

# Global (all projects)
claude mcp add --scope user knowledge -- node /path/to/knowledge-mcp/dist/index.js

# Or with custom KB location
claude mcp add --scope user knowledge -- node /path/to/knowledge-mcp/dist/index.js -e KNOWLEDGE_DIR=/path/to/knowledge

mkdir -p ~/.claude/hooks
chmod +x hooks/kb-session-start.sh hooks/kb-stop-guard.sh
ln -sf "$(pwd)/hooks/kb-session-start.sh" ~/.claude/hooks/kb-session-start.sh
ln -sf "$(pwd)/hooks/kb-stop-guard.sh" ~/.claude/hooks/kb-stop-guard.sh

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/kb-session-start.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/kb-stop-guard.sh"
          }
        ]
      }
    ]
  }
}

## Knowledge Protocol (MANDATORY — GLOBAL)

`~/knowledge/` is the **global source of truth** for all projects.

**Tools available** (via the `knowledge` MCP server, prefix `mcp__knowledge__`):
- `kb_search` — grep across all `*.md` in the knowledge base
- `kb_read` — read a specific file by relative path
- `kb_write` — write/overwrite a file (auto-commits)
- `kb_log_decision` — append a decision entry to `decisions/decisions.md`
- `kb_index` — rebuild `_index.md` from current files

**Rules:**
1. Before modifying code/schema/deployment, read the relevant knowledge docs first.
2. After completing meaningful changes, update knowledge via `kb_write`, then `kb_index`.
3. A Stop hook enforces this: code changes without a knowledge update will block session end.
4. Trivial changes (typos, formatting) are exempt — tell the user and ask for confirmation.
5. If knowledge contradicts code, stop and ask — don't silently fix either side.

stop_hook_active = true?            → allow (loop guard, prevents infinite block)
cwd in ~/knowledge/ or ~/.claude/?  → allow (excluded dirs)
cwd not in a git repo?              → allow (nothing to enforce)
working tree clean AND no commits
  in the last hour?                 → allow (no code changes to document)
session transcript has kb_write?    → allow (knowledge was updated via MCP)
none of the above                   → BLOCK (code changed, knowledge not updated)

EXCLUDED_DIRS=(
  "$HOME/knowledge"
  "$HOME/.claude"
  # Add more dirs to exclude from enforcement:
  # "$HOME/throwaway-experiments"
)

# Ubuntu/Debian
sudo apt install jq
# or Homebrew
brew install jq

> Initialize my knowledge base from all my projects
  → calls kb_init(scan_dirs="~,~/dev,~/projects")

> Search my knowledge base for "webhook"
  → calls kb_search("webhook")

> Read the hotel automation doc
  → calls kb_read("systems/hotel-automation.md")

> Add a note about the new API endpoint
  → calls kb_write("systems/api.md", "## New Endpoint\n...", "append")

> Log why we chose PostgreSQL over MongoDB
  → calls kb_log_decision("PostgreSQL over MongoDB", "Need ACID transactions for...")

# Machine A (after Claude writes knowledge)
cd ~/knowledge && git push

# Machine B
cd ~/knowledge && git pull

Claude Code ←→ stdio ←→ knowledge-mcp ←→ ~/knowledge/ (local files)
                                              ↓
                                          git auto-commit
                                              ↓
                                      GitHub (optional remote sync)