Zettelkasten as a note-taking method for coding agents

I wanted to give AmblerTS, my Deno/TypeScript state-machine framework, the ability to record non-obvious learnings that would otherwise require significant context to reconstruct across sessions.

I turned to the classic note-taking methodology developed by the German sociologist Niklas Luhmann: the Zettelkasten (German for slip box). The methodology is elegantly simple: take atomic notes, link them explicitly to related ones, and organise them so they can be retrieved precisely when they become relevant again.

The Concept

The idea translates naturally to agentic coding:

1. Describe the protocol in an AGENTS.md file, a convention that coding agents like Gemini and Claude read as project-level instructions.
2. Implement a lightweight abstraction using AmblerTS itself, a unified zettel walk that supports the full set of operations: search, create, get, update, link and delete.
3. The agent searches for relevant notes before working on a prompt, then feeds any new learnings back into the slip box when done.

The result is a local SQLite database that accumulates project-specific metadata (design decisions, gotchas, constraints) accessible to any coding agent that works on the repository. Search blends FTS5 keyword matching with optional semantic re-ranking via embeddings (degrading gracefully to keyword-only when no local embeddings host is available).

Current Implementation

The implementation is intentionally minimal, enough to validate the idea. A single deno task zettel <subcommand> command exposes all six operations:

deno task zettel search "<query>"
echo '{"title":"...","body":"...","tags":["..."]}' | deno task zettel create
deno task zettel get <id>
echo '{"body":"..."}' | deno task zettel update <id>
deno task zettel delete <id>
deno task zettel link <fromId> <toId> "<relation>"

What's Next

A few variants I have in mind:

• User-level note store: a single knowledge base spanning all coding agent activity across projects, backed by a user-level AGENTS.md and a shared command, rather than one database per repository.
• Hybrid Markdown + SQLite storage, keeping notes as version-controlled Markdown files with SQLite used purely as a search index. Whether that adds value likely depends on the development process: projects with meaningful git history and code review may benefit from diffable notes; others probably won't.

──────

AmblerTS is open source. You can explore the implementation and try the Zettelkasten-RAG setup at https://github.com/argenkiwi/ambler-ts.