shift-labs-ai/napkin

What it solves

Napkin provides a local-first, file-based knowledge system specifically designed to act as a long-term memory for AI agents. It solves the problem of context window limits by preventing the need to dump entire knowledge bases into an LLM's prompt, instead allowing agents to retrieve information progressively.

How it works

The system uses a structured vault of Markdown files (compatible with Obsidian) and a native search engine (ferrosearch) to implement "progressive disclosure." Information is revealed to the agent in four levels of granularity:

• Level 0: A high-level project context note (NAPKIN.md).
• Level 1: A vault map with search-validated keywords (napkin overview).
• Level 2: Ranked search results with snippets (napkin search).
• Level 3: Full file content (napkin read).

It avoids complex embeddings or graphs in favor of BM25 search on markdown files, which the project claims provides high accuracy for long-term conversational memory benchmarks.

Who it’s for

• AI Agent Developers: Those building agents that need a structured, persistent memory system they can read from and write to.
• Knowledge Workers: Users who want a local-first knowledge base that is both human-readable (via Obsidian) and agent-accessible.

Highlights

• Agent-First Design: Includes --json and -q flags for structured machine output and dedicated "skills" for distillation (converting sessions to notes) and upkeep (tending the vault).
• Local-First: File-based storage with no requirement for external databases or embeddings.
• Coded SDK: A TypeScript library that allows developers to integrate Napkin's logic directly into their applications without using the CLI.
• Domain Templates: Pre-built vault structures for coding, company, product, research, and personal use cases.
• Obsidian Compatibility: Works alongside .obsidian/ configurations, making the knowledge base human-editable.