A living wiki
for your codebase
Almanac builds a self-updating wiki around your codebase, so every agent can build on what the last one learned.
your-repo/ |-- src/ |-- .almanac/ | |-- pages/ | | |-- supabase.md # why we chose it, how auth flows | | |-- checkout-flow.md # spans 4 files in 3 services | | |-- uuid-decision.md # tried auto-increment, here is why not | | `-- stripe-webhook.md # the deadlock gotcha | |-- topics.yaml # DAG of categories | `-- index.db # auto-generated SQLite index |-- .git/ `-- ...
Every agent starts from zero.
The last session found the risky files, failed paths, and hidden decisions. The next session does not know any of it unless that context gets written down.
Knowledge dies silently
Why you chose Postgres over DynamoDB. Why checkout has that timeout. It lived in a Claude conversation six months ago. Now it lives nowhere.
Root docs rot
A single flat file gets too long, too vague, and too stale. No graph structure, no search, and no clear way for agents to keep it current.
Sessions start from zero
Tuesday's agent does not know what Monday's agent discovered. The same rejected approach gets tried again and the same invariant gets violated.
From scattered signals to a self-updating wiki
Almanac gathers code, agent sessions, repo instructions, and existing docs into small linked pages that live beside your code.
Agent transcripts
Claude, Codex, and other coding-agent sessions with decisions, dead ends, and fixes
Source code
Files, folders, imports, config, and tests that anchor each page to the code it explains
Repo instructions
AGENTS.md, CLAUDE.md, and local setup notes agents already read before working
Existing docs
README files, architecture notes, and stale docs that still contain useful context
checkout-flow.md
The checkout flow spans four files across three services. Keep the webhook idempotent, avoid auto-increment IDs, and check the Stripe retry invariant before editing.
Write code. The wiki writes itself.
A scheduler captures the durable parts of agent work and keeps the repo wiki current.
You code
Work with Claude, Cursor, or Codex as usual. Make decisions, debug issues, and discover gotchas.
Sweep captures
A scheduled job runs almanac capture sweep, finds quiet transcripts, and distills durable knowledge into markdown pages.
The wiki grows
Pages appear in .almanac/pages. Review them like any other repo change because they are just files.
Agents orient
The next session can search decisions, invariants, and file mentions before touching code.
Built for agents to read
Agents can search by file, topic, or keyword and pull the exact page they need before editing.
Atomic pages
One page per stable concept: a decision, a flow, an invariant, or a gotcha.
Topic graph
Pages sit in a DAG, so auth can connect to JWTs, refresh tokens, and service boundaries naturally.
Wikilinks
Use [[checkout-flow]], [[src/handler.ts]], and cross-repo links without losing the thread.
Scheduled capture
Background jobs keep the repo wiki current without turning documentation into a manual chore.
Local index
SQLite plus full-text search makes file-reference lookups and topic queries fast.
--mentions
Before editing a file, agents can find every page that mentions it.
One command to set up
The wizard picks your provider, installs scheduled capture, and drops agent guides into your config.