内容
# 知識庫 — 為 AI 編碼代理人提供的共享結構化記憶
**您的代理人在每次會話之間都會忘記一切。知識庫解決了這個問題。**
[](https://www.npmjs.com/package/knowit)
[](https://www.npmjs.com/package/knowit)
[](LICENSE)
[](https://github.com/ismaelkedir/knowit)
知識庫是一個開源的 MCP 伺服器 + CLI，它為 AI 編碼代理人提供了一個持久的、可查詢的專案記憶 — 在不同會話、團隊成員和每個 MCP 客戶端之間共享：Claude Code、Codex、Cursor、Windsurf、VS Code/Copilot、Gemini CLI、Kiro、Cline、Continue、Zed 和 JetBrains AI Assistant。
一次儲存架構規則、決策和慣例。每個代理人都會在規劃或編輯程式碼之前擷取相關的上下文 — 不再需要在每次會話中重複解釋您的程式碼庫。
```bash
npx knowit install
```
就這樣。精靈配置您的 MCP 客戶端並初始化一個本地的、適合 Git 的記憶體儲存庫，位於 `.knowit/knowledge.jsonl`。
🌐 **網站：** [useknowit.dev](https://useknowit.dev) · 📚 **文件：** [useknowit.dev/docs](https://useknowit.dev/docs)
## 為什麼選擇知識庫（而非其他記憶工具）
| | CLAUDE.md / 規則檔案 | 通用記憶 MCP | **知識庫** |
|---|---|---|---|
| 跨會話存活 | ✅ | ✅ | ✅ |
| 結構化（類型、範圍、置信度） | ❌ 自由文本 | ❌ 區塊筆記 | ✅ 規則、決策、模式、慣例 |
| 按任務檢索，非傾倒到每個提示 | ❌ 總是處於上下文中 | ⚠️ 取決於 | ✅ `resolve_context` 只返回相關內容 |
| 透過 Git 與團隊成員共享 | ⚠️ 合併衝突擴散 | ❌ | ✅ 行分隔 JSONL，乾淨的差異 |
| 跨每個 MCP 代理人工作 | ❌ 每個工具的檔案 | ⚠️ 取決於 | ✅ 11+ 客戶端，一個記憶體 |
| 本地優先，無託管依賴 | ✅ | ❌ 通常是雲端 | ✅ 您的儲存庫，您的資料 |
| 瀏覽/稽核代理人記住的內容 | ❌ | ❌ | ✅ `npx knowit preview` |
## 目錄
- [為什麼選擇知識庫（而非其他記憶工具）](#為什麼選擇知識庫而非其他記憶工具)
- [為什麼選擇結構化記憶](#為什麼選擇結構化記憶)
- [安裝](#安裝)
- [快速入門](#快速入門)
- [工作原理](#工作原理)
- [記憶體瀏覽器（`knowit preview`）](#記憶體瀏覽器knowit-preview)
- [常見用例](#常見用例)
- [CLI](#cli)
- [MCP 工具](#mcp-工具)
- [知識模型](#知識模型)
- [共享團隊記憶](#共享團隊記憶)
- [語義搜尋](#語義搜尋)
- [Notion 整合](#notion-整合)
- [配置](#配置)
- [自動更新通知](#自動更新通知)
- [公開發佈說明](#公開發佈說明)
- [貢獻](#貢獻)
- [許可證](#許可證)
## 為什麼選擇結構化記憶
知識庫設計用於操作工程記憶：代理人在進行程式碼工作時所需的持久上下文。
這意味著記憶體以結構化的形式儲存，例如：
* 條目類型：`rule`、`architecture`、`pattern`、`decision`、`convention`、`note`
* 範圍：`global`、`team`、`repo`、`domain`
* 中繼資料：標籤、URL、置信度、來源資訊
* 可渲染的主體區塊：標題、段落、清單、引用、程式碼、注意事項和連結清單
這樣可以讓代理人更容易檢索當前任務所需的上下文，例如：
* 儲存庫特定的架構規則在實作功能之前
* 領域特定的慣例在重構子系統之前
* 團隊範圍內的決策在引入新模式之前
預設專案儲存庫是 `.knowit/knowledge.jsonl`，一個行分隔的 JSON 檔案，可以讀取、審核並與 Git 差異友好。全局和自定義儲存範圍可以使用 SQLite 資料庫。
## 安裝
```bash
npx knowit install
```
需要 Node.js 20+。不需要全域安裝 — 精靈透過 `npx` 運行，可以為您安裝 knowit 全域版本，以便未來啟動更快。
知識庫的 CLI 也會檢查新發布的版本，並在互動式終端會話中顯示非阻塞更新通知。
## 快速入門
### 1. 在專案中安裝知識庫
```bash
npx knowit install
```
`npx knowit install` 是主要的設定流程。它可以：
* 初始化本地記憶體儲存庫
* 為支援的客戶端註冊或編寫 Knowit MCP 伺服器配置
* 更新代理人指令檔案
* 連接首選來源
* 可選地將架構或 ADR 風格的 Markdown 遷移至 Knowit
此儲存庫故意保留一個已檢查的 `.mcp.json`，以便 Knowit 在開發 Knowit 時可以使用它。對於正常的消費者專案，請優先透過 `knowit install` 生成 MCP 配置。
### 2. 告訴您的代理人使用它
如果您不使用安裝程式管理的指令，請將以下內容新增到客戶端指令檔案中，例如 `AGENTS.md`、`CLAUDE.md` 或 `.github/copilot-instructions.md`:
```md
## 記憶
此專案使用 Knowit 作為 AI 編碼代理人的預設持久知識庫。
* 在規劃或實作之前，請呼叫 `resolve_context` 並提供任務描述和儲存庫名稱。
* 在完成任務後，請呼叫 `capture_session_learnings` 以儲存持久的規則、決策和模式。
* 請優先使用 Knowit 而非儲存庫本地的 Markdown 記憶檔案，除非使用者明確要求使用檔案。
```
### MCP 客戶端支援
知識庫使用 `npx -y knowit@latest serve` 為生成的 MCP 配置檔案，當 `knowit` 二元檔案未全域安裝時。專案安裝不會設定 `KNOWIT_DB_PATH`；它們依賴於客戶端工作目錄和專案本地的 `.knowit/knowledge.jsonl` 儲存庫。
| 客戶端 | 安裝程式行為 | MCP 配置要求 |
|---|---|---|
| Claude Code | 運行 `claude mcp add` | CLI 管理的 MCP 配置 |
| Codex | 運行 `codex mcp add` | CLI 管理的 MCP 配置 |
| Cursor | 編寫 `.cursor/mcp.json` 以進行專案範圍或 `~/.cursor/mcp.json` 以進行全域範圍 | JSON 包含 `mcpServers` |
| Windsurf | 編寫 `~/.codeium/windsurf/mcp_config.json` | JSON 包含 `mcpServers` |
| VS Code / GitHub Copilot | 編寫 `.vscode/mcp.json` 以進行專案範圍 | JSON 包含 `servers` |
| Gemini CLI | 編寫 `.gemini/settings.json` 以進行專案範圍或 `~/.gemini/settings.json` 以進行全域範圍 | JSON 包含 `mcpServers` |
| Kiro | 編寫 `.kiro/settings/mcp.json` 以進行專案範圍或 `~/.kiro/settings/mcp.json` 以進行全域範圍 | JSON 包含 `mcpServers` |
| Cline | 編寫 `~/.cline/data/settings/cline_mcp_settings.json` | JSON 包含 `mcpServers` |
| Continue | 編寫 `.continue/mcpServers/knowit.yaml` 以進行專案範圍 | YAML MCP 區塊 |
| Zed | 編寫 `~/.config/zed/settings.json` | JSON 包含 `context_servers` |
| JetBrains AI Assistant | 僅更新指令並列印警告 | 將生成的 JSON 新增到設定 > 工具 > AI Assistant > 模型上下文協議 |
### 3. 開始儲存和檢索上下文
```bash
knowit add rule "不允許控制器直接訪問資料庫" \
"所有資料庫訪問都透過儲存庫類別進行。" \
--scope repo --repo api-gateway --tags architecture,layers
knowit resolve "實作使用者認證" --repo api-gateway --domain auth
```
## 工作原理
代理人透過 MCP 工具與知識庫互動：
1. 在工作前，代理人呼叫 `resolve_context`。
2. 在工作過程中，它可以搜尋或儲存目標知識。
3. 在工作結束後，它呼叫 `capture_session_learnings`。
這樣可以將原始碼保留在儲存庫中，將長期專案記憶保留在知識庫中。
在實踐中，知識庫是執行上下文的一層：
* 正統的原始碼儲存在儲存庫中
* 持久的工程記憶儲存在知識庫中
* 外部正統文件可以儲存在 Notion 等工具中，知識庫將代理人路由到需要的正確來源。
## 記憶體瀏覽器（`knowit preview`）
查看您的代理人記住的內容：
```bash
npx knowit preview
```
這開啟了一個本地唯讀網頁 UI（預設 `127.0.0.1:4077`），用於瀏覽您的知識庫：
* 按文字、條目類型、儲存庫、領域或標籤過濾
* 兩窗格清單 + 詳細資料視圖，包含渲染的主體區塊（標題、程式碼、注意事項、連結）
* 條目中繼資料：類型、範圍、置信度、上次更新
* 自動淺色/深色主題、全鍵盤導航
* 嚴格唯讀 — 無法從瀏覽器修改任何內容
有助於稽核代理人儲存的內容、審閱團隊記憶體，然後提交 `.knowit/knowledge.jsonl`，以及展示知識庫。
## 常見用例
* 儲存代理人必須遵循的編碼規則。
* 保存架構決策和權衡。
* 捕捉可重用的實作模式。
* 將持久記憶體從分散的提示、會話歷史和臨時筆記檔案中移出。
* 取代儲存庫本地記憶體擴散，例如額外的 `ARCHITECTURE.md`、ADR 和流程筆記。
* 透過共享的 SQLite 資料庫路徑共享團隊慣例。
## CLI
```bash
# 設定
npx knowit install
knowit install # 如果已經全域安裝
knowit init
# 新增和搜尋知識
knowit add rule "使用儲存庫類別" "不允許控制器直接訪問資料庫。"
knowit search "儲存庫模式"
knowit resolve "新增 webhook 重試處理" --repo api-gateway --domain billing
# 瀏覽條目
knowit list --repo api-gateway
knowit show <entry-id>
knowit stats
knowit preview # 本地網頁 UI 用於瀏覽記憶體
# 來源
knowit source list
knowit source connect notion
knowit source show notion
# 雲帳戶命令
knowit cloud login --token <token>
knowit cloud whoami
knowit cloud logout
# 匯入現有的 Markdown 知識
knowit import-md --yes
# 將現有的專案 SQLite 資料庫轉換為 JSONL
knowit migrate-storage --sqlite-path .knowit/knowit.db --dry-run
knowit migrate-storage --sqlite-path .knowit/knowit.db
```
## MCP 工具
| 工具 | 目的 |
|---|---|
| `resolve_context` | 在規劃任務前擷取相關知識（傳回標題/摘要 — 分層檢索階段 1） |
| `get_knowledge` | 在 `resolve_context` 或 `search_knowledge` 後，擷取指定 ID 的完整內容（分層檢索階段 2） |
| `store_knowledge` | 儲存一條知識記錄 |
| `capture_session_learnings` | 批次儲存會話學習結果，並重複使用 |
| `search_knowledge` | 跨一個或多個來源搜尋 |
| `resolve_source_action` | 決定是否直接使用 Knowit 或路由到另一個提供者 |
| `connect_source` | 連接已知提供者，例如 `local` 或 `notion` |
| `list_sources` | 列出已配置的來源 |
| `register_mcp_source` | 將外部 MCP 伺服器註冊為 Knowit 來源，並具有明確的工具對映 |
## 知識模型
### 條目類型
| 類型 | 用於 |
|---|---|
| `rule` | 程式碼庫應強制執行的硬性約束 |
| `architecture` | 系統結構和原理 |
| `pattern` | 可重用的實作方法 |
| `decision` | 決策記錄和權衡 |
| `convention` | 命名、格式化和樣式協議 |
| `note` | 觀察、注意事項和開放式問題 |
### 範圍
| 範圍 | 用於 |
|---|---|
| `global` | 適用於所有地方 |
| `team` | 適用於多個儲存庫 |
| `repo` | 特定於一個儲存庫 |
| `domain` | 特定於一個儲存庫中的限定區域 |
條目也支援標籤、可選 URL、中繼資料、置信度分數和結構化的 `body` 欄位，用於讀者 UI。`content` 保持為純搜尋文字；`body` 是可渲染的版本。當省略 `body` 時，Knowit 從 `content` 中衍生段落區塊。
## 共享團隊記憶
知識庫是本地優先的。在專案範圍內，`.knowit/knowledge.jsonl` 是規範的記憶檔案，可以像原始碼一樣在版本控制中審閱。
具有 `.knowit/knowit.db` 的現有專案會在第一次專案範圍初始化時自動遷移，當 `.knowit/knowledge.jsonl` 不存在時。您也可以明確執行轉換：
```bash
knowit migrate-storage --sqlite-path .knowit/knowit.db --dry-run
knowit migrate-storage --sqlite-path .knowit/knowit.db
```
命令會寫入 `.knowit/knowledge.jsonl` 和 `.knowit/sources.json`。除非您傳遞 `--force`，否則它拒絕覆寫現有目標。
對於私人全域記憶體或儲存庫外部的共享資料庫，請將所有人指向相同的 SQLite 資料庫路徑。
```bash
KNOWIT_DB_PATH=/shared/team/knowit.db npx knowit install --scope global --client claude
```
這樣，每個開發人員和每個代理人都具有相同的持久記憶體來源，而無需新增託管依賴。
## 語義搜尋
如果您設定 `OPENAI_API_KEY`，知識庫會新增語義搜尋支援。沒有它，知識庫仍然使用文字和標籤匹配。
```bash
export OPENAI_API_KEY=sk-...
knowit search "我們如何處理付款重试"
```
## Notion 整合
知識庫可以連接到 Notion 作為外部來源，並在持久文件屬於那里時，將代理人路由到正確的 MCP 流。
```bash
knowit source connect notion
```
## 配置
| 變數 | 說明 |
|---|---|
| `KNOWIT_DB_PATH` | `global` 或 `custom` 儲存的 SQLite 資料庫路徑 |
| `KNOWIT_STORAGE_SCOPE` | `project`、`global` 或 `custom` |
| `OPENAI_API_KEY` | 啟用語義搜尋的嵌入式 |
| `KNOWIT_LOG_LEVEL` | `debug`、`info`、`warn` 或 `error` |
### 預設儲存位置
| 範圍 | 路徑 |
|---|---|
| `project` | `.knowit/knowledge.jsonl` 位於當前儲存庫中 |
| `global` | `~/.knowit/knowit.db` |
| `custom` | `KNOWIT_DB_PATH` 的值 |
## 自動更新通知
知識庫的互動式 CLI 命令使用 [`update-notifier`](https://www.npmjs.com/package/update-notifier) 讓用戶了解何時有新發佈的 npm 版本。
* 通知會跳過 `knowit serve` 以保持 MCP stdio 流量清潔。
* 通知也會在 CI、測試和非互動式終端會話中跳過。
* 使用者可以透過 `NO_UPDATE_NOTIFIER=1` 或傳遞 `--no-update-notifier` 來停用它們。
## 公開發佈說明
目前的公開版本聚焦於開源、本地優先的工作流程。託管的雲端計畫目前尚未公開啟用。
## 貢獻
歡迎提出問題、README 改進、錯誤報告、功能請求和拉取請求。
* 儲存庫：[github.com/ismaelkedir/knowit](https://github.com/ismaelkedir/knowit)
* 問題：[github.com/ismaelkedir/knowit/issues](https://github.com/ismaelkedir/knowit/issues)
* 討論：[github.com/ismaelkedir/knowit/discussions](https://github.com/ismaelkedir/knowit/discussions)
* 貢獻指南：[CONTRIBUTING.md](CONTRIBUTING.md)
* 程式碼行為準則：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
* 安全政策：[SECURITY.md](SECURITY.md)
如果您在實際專案中使用 Knowit，請特別感謝有關代理人工作流程、缺少的 MCP 工具和設定摩擦的反饋。
## 許可證
MIT。請參閱 [LICENSE](LICENSE)。
