shift-labs-ai/napkin

解決的問題

Napkin 是一個專為 AI 代理設計的本地優先、基於檔案的知識系統，旨在作為其長期記憶。它透過避免將整個知識庫一次性注入 LLM 的提示中，而是允許代理逐步檢索資訊，從而解決上下文視窗限制的問題。

工作原理

該系統使用結構化的 Markdown 檔案倉庫（與 Obsidian 相容）和原生搜尋引擎（ferrosearch）來實現「漸進式揭露」。資訊以四個粒度層級逐步向代理揭露：

• 層級 0：高階專案背景筆記（NAPKIN.md）。
• 層級 1：包含經搜尋驗證關鍵字的倉庫地圖（napkin overview）。
• 層級 2：帶摘要的排序搜尋結果（napkin search）。
• 層級 3：完整檔案內容（napkin read）。

該系統避免使用複雜的嵌入或圖結構，轉而採用對 Markdown 檔案的 BM25 搜尋，專案聲稱這在長期對話記憶基準測試中提供了高準確度。

適用對象

• AI 代理開發者：需要一個可讀寫、結構化且持久的記憶系統來建構代理的開發者。
• 知識工作者：希望擁有一個本地優先的知識庫，既可透過 Obsidian 供人類閱讀，又可供代理存取的使用者。

核心亮點

• 代理優先設計：包含 --json 和 -q 標誌，用於結構化機器輸出，並提供專用「技能」用於萃取（將會話轉換為筆記）和維護（打理倉庫）。
• 本地優先：基於檔案儲存，無需外部資料庫或嵌入。
• 程式化 SDK：提供 TypeScript 套件，允許開發者在不使用 CLI 的情況下，將 Napkin 的邏輯直接整合至應用程式中。
• 領域範本：提供適用於程式設計、公司、產品、研究及個人用途的預先建構倉庫結構。
• Obsidian 相容性：可與 .obsidian/ 設定共存，使知識庫對人類可編輯。