Napkin boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

This run analyses Napkin as a file-based memory/knowledge/context-engineering system, not as an enclosing agent runtime. Its intended use is to give agents retained Markdown knowledge through staged orientation, search and reading, with agent instructions for admission and upkeep. The boundary is the whole shipped repository artifact: the CLI and SDK, vault scaffolding, state mutations and reload paths, packaged skills, design documents, compatibility forwarders and evaluator drivers. A model need not run inside the core for this target to qualify: the shipped skills direct model-dependent knowledge selection and maintenance, and shipped benchmarks feed stored notes to an external agent (SRC-1, README.md, skills/distill/SKILL.md, skills/tend/SKILL.md, bench/longmemeval-eval.ts).

napkin is designed as a memory system for agents. Instead of dumping the full vault into context, it reveals information gradually: --- README.md

You are preserving knowledge from this session into a napkin vault. Write the knowledge itself, not a record of the conversation. --- skills/distill/SKILL.md

Entry-point tracing starts with package.json: the executable is dist/main.js, the library export is dist/index.js, and the package includes dist and skills. Their source counterparts are src/main.ts and src/index.ts. The CLI registers read, search, overview, write, maintenance-inspection and auxiliary command groups. The SDK routes these responsibilities to src/core/ and src/utils/; it is not the entire target by itself (SRC-1, package.json, src/main.ts, src/index.ts, src/sdk.ts).

The state loop includes scaffolding folders, templates and NAPKIN.md; creating, overwriting, appending, moving and deleting notes; discovering vault layout on subsequent construction; reading files again for retrieval; and loading or rebuilding search and overview caches. The distill skill supplies retention gates, deduplication searches and merge/create decisions. Tend supplies bounded link repair, retirement and duplicate merging. These are model-facing procedures, not an internally scheduled model service (SRC-1, src/core/init.ts, src/templates/coding.ts, src/core/crud.ts, src/utils/vault.ts, src/core/search.ts, src/core/overview.ts, skills/distill/SKILL.md, skills/tend/SKILL.md).

const content = fs.readFileSync(path.join(vaultPath, resolved), "utf-8"); return { path: resolved, content }; --- src/core/crud.ts

The evaluators are included callers, not excluded applications. LongMemEval writes per-round notes into day directories, assigns modification times from session dates, writes a context note, launches pi with a substituted prompt, parses tool activity and scores answers. LoCoMo writes session notes with supplied summaries, observations and adjacent-session links; HotpotQA writes paragraph notes and related links. These paths establish distinct benchmark ingestion and later consumption responsibilities. They do not establish that a normal working session executes the distill or tend skills: benchmark invocations explicitly disable skills (SRC-1, bench/longmemeval-eval.ts, bench/longmemeval-prompt.md, bench/locomo-eval.ts, bench/hotpotqa-eval.ts).

"--no-extensions", "--no-skills", "--no-prompt-templates", "--system-prompt", systemPrompt, userPrompt, --- bench/longmemeval-eval.ts

Frozen evidence and external limits

The single frozen evidence source is the acquired Git checkout at full commit 7582d6a46f5a11995956e60a59c41a5b242109f1. HEAD was checked against that pin and the tracked tree inspected read-only. The applicability cutoff is 2026-10-12; this says which evidence the run uses, not that the checkout represents the latest release on that date. Overall evidence is code-grounded. No target, test, benchmark or model call was executed. Code and prompts support an implementation/design account; reported benchmark numbers remain attributed reports rather than observed runs or causal experiments (SRC-1, bench/README.md).

External dependencies include the filesystem, Node/Bun tooling, Commander, FerroSearch, Markdown/frontmatter parsers, SQL/expression support and optional Glimpse rendering. Their declarations are available; their implementations are not frozen here. This prevents conclusions about dependency internals, platform behavior and performance beyond Napkin's calling code (SRC-1, package.json, src/core/search.ts).

Pi, model providers, the separate pi-napkin integration and the benchmark's .pi/extensions/napkin-context/index.ts are outside the frozen tree. The benchmark references that extension and checks for it; the tracked tree contains no such file. This is an unavailable external dependency, not an omitted shipped driver. It prevents verification of actual context injection, external tool registration and host scheduling. Napkin's shipped callers and prompts remain included, but host responsibilities are not attributed to Napkin (SRC-1, README.md, bench/longmemeval-eval.ts, bench/hotpotqa-eval.ts).

Napkin is LLM-free. The distill extension adds intelligence without coupling it to the core tool. The extension: --- docs/distill.md

docs/distill.md describes timer-driven automatic distillation in pi. It is included as doctrine/design, not evidence that the extension implementation ships in this checkout. Likewise, older progressive-disclosure design text is not proof of command availability; the CLI registrations and shipped skills control implementation conclusions (SRC-1, docs/distill.md, docs/agent-memory-progressive-disclosure.md, src/main.ts).

Benchmark datasets, result JSON, private data-kbs/ corpora and generated build output are not tracked in the frozen tree. .gitignore declares these exclusions. Their absence prevents reproducing reported scores, inspecting run traces or auditing private-corpus exposure results. No new source or capture is introduced to fill those gaps (SRC-1, .gitignore, bench/README.md, bench/exposure-all.sh). Package metadata names a different repository URL; the run retains the supplied normalized source identity unchanged and does not follow that URL to another revision (SRC-1, package.json).

Top-level coverage

“Included” establishes the functional boundary, not a claim that every line has already been inspected. Initial inspection follows the entry points through persistence, reload, admission instructions, maintenance and agent consumption. Available material pending detailed inspection is identified separately from unavailable evidence and deliberate exclusions. All rows refer to SRC-1.

Source register