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/ 配置共存，使知识库对人类可编辑。