iamsikun/cairn-workbench

A Markdown research knowledge base that your agent writes while you read.
Read a paper with the Finch skill in Claude Code or Codex. As the discussion progresses,
the agent saves a note for the paper and files it under topics, such as
*Generative recommendation* or *Large recommendation models*. Those topics nest under
broader ones like *Recommendation systems*. Over many sessions and both clients, the notes
grow into a connected network.
Brainstorming works the same way. When you develop a research idea with the agent, it
saves an idea note, files it under topics and links it to papers. Later sessions resume
it, and its dated minutes record how the idea developed.
Setup
Keep the knowledge base private and outside this repository. cairn refuses a folder
inside any git checkout, though the knowledge base may be its own private git repo.
--dry-run prints the registration command without running it, and --remove
unregisters it. Finch is installed separately; Cairn does not install or modify it.
How it works
The knowledge base is a folder of Markdown files, and it opens as an Obsidian vault:
- **Notes.** A note's file name is its slug. One DOI or arXiv id always maps to the same
note. Renaming a note keeps its slug and adds the old title to aliases, so links still
work.
- **Links.** topics: puts a paper in a topic, and a topic in its broader topics. A topic
may have several broader topics. [[slug]] in a body links any two notes. Backlinks and
the topic tree are computed from these links.
- **Saving and linking.** The connected agent calls Cairn's MCP tools. Cairn runs no model
of its own:
- search, get_note and list_topics read the knowledge base.
- save_reading saves a paper note and its topics.
- save_idea saves a research idea and adds an entry to its minutes.
- save_note saves a topic or a free-standing note.
- **Topics.** Naming a topic that does not exist creates it. Each save returns
suggested_topics: existing topics whose names appear in the note but are not linked
yet. The server's instructions tell the agent to save after each substantive step, reuse
existing topics, add broader topics, and link the suggestions that are real.
- **Ideas.** An idea note has two parts. Above ## Minutes is its current account, which
the agent revises: question, hypothesis, related work, evidence and open questions.
Below it are dated minutes. Cairn only ever appends to these, and an entry that is
already there is not added twice. Each line is attributed to the user, the agent or a
source. status is one of seed, exploring, testing, parked and developed, and
a change records its reason in the minutes. next_action names the next useful step.
last_discussed and last_review are dated by Cairn. A save marked as a review, such
as a maintenance pass, cannot change the status.
- **Safe updates.** Updating a note requires the revision returned by get_note. Edits you
make in an editor, or that another session makes, are never silently overwritten.