Durable memory for coding agents.
Your agent has been here before. bilbo kept the notes.
You fix a bug, settle a design decision, and finally figure out that strange test failure. Then a new session begins, ready to rediscover all three.
bilbo gives your agent a notebook: plain Markdown notes it writes in one session
and finds again in the next, plus a library of sources it can cite. Its plugin
for Claude Code, Codex and Antigravity CLI helps your agent save decisions and gotchas, and
brings relevant notes into later conversations. You rarely need to type a
bilbo command yourself.
Contents
A new Claude Code session with the bilbo plugin. The prompt hook hands the agent a saved note, and the agent answers from it. The notes come from bilbo's synthetic eval set.
In your own work, notes like that one come from earlier sessions: you tell the agent to note a fix, and it saves one. Getting started shows the text the hook hands the agent.
With an embedder, bilbo recall matches what you mean, not only the words you
type, and one query brings back the gotcha, the plan and the decision on the
same problem. Your agent runs the same search when you ask "What did we decide
about the database layer?".
The watcher records every version of every note. When an agent rewrites a note
and loses something, bilbo history shows what changed and bilbo restore
brings the old version back.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/delucca/bilbo/releases/latest/download/bilbo-installer.sh | shCheck it with bilbo --version, which prints bilbo <version>.
On Nix, try it with nix run github:delucca/bilbo -- --version. Release
binaries cover macOS (arm64 and Intel) and Linux (x86_64 and arm64, glibc).
docs/install.md covers PATH, upgrades, NixOS, home-manager
and removal.
-
Run setup.
bilbo setup
It asks which embedder to use for search by meaning (none is fine to start), shows its plan and asks once. Then it creates the store and the config, installs the plugin in Claude Code, Codex and agy (each one found on your
PATH) and installs a login service that records note history. It prints one line per step; docs/getting-started.md shows them, and docs/guides/setup.md lists every option. -
Use it through your agent. Open Claude Code or Codex and try
Note this as a gotcha: <something you learned today>, then in a new sessionWhat do we know about <that topic>?. The agent needs no command from you. See docs/guides/agents.md. -
Try the commands yourself. Create a note and search it:
$ bilbo new gotcha sqlite-busy-timeout --title "SQLite needs a busy timeout" /Users/me/.local/share/bilbo/notes/gotcha-sqlite-busy-timeout.md
Open the file it prints and add these lines under the title, after a blank line:
Two writers on the same database file fail with `SQLITE_BUSY` unless each connection sets `PRAGMA busy_timeout`. ## Fix Set `busy_timeout = 5000` right after opening the connection.
Then check the store and search it:
$ bilbo check $ bilbo recall busy timeout /Users/me/.local/share/bilbo/notes/gotcha-sqlite-busy-timeout.md:11 gotcha 2026-10-06T14:39-03:00 SQLite needs a busy timeout > Fix Set `busy_timeout = 5000` right after opening the connection.
checkprints nothing when the store is clean.recallprints the path and line of the best passage, the kind andcreated, the heading path and the start of the text. These are the bytes a pipe or an agent gets; a terminal shows the same facts laid out for a person.
More detail: docs/getting-started.md.
- Plain files. One note per topic in
<root>/notes/, named<kind>-<topic>.md, with a small YAML frontmatter. Read, edit, grep or version them like any other file. See files. - Keyword search out of the box, meaning search with an embedder. Point bilbo at Ollama, OpenAI or any OpenAI-compatible URL, or let it run a local model. See embedders.
- History for every note. A background watcher records each version, so a
careless rewrite is one
bilbo restoreaway from undone. See history. - Agent plugin. Four skills for Claude Code, Codex and agy (
note,recall,reference,ingest), a prompt hook that hands the agent the notes that bear on each prompt, and a reminder to write down what a session settled after a compaction. See agents. - A library of cited sources. Pages, files and PDF text kept verbatim, read
in full and cited by id, with every citation checked by
bilbo cite. See library. - Scopes, and optional encrypted sync. Group notes by part of your work and keep a scope local to one machine. Sync between your devices, devices and the relay are all optional: bilbo works fully without them. See scopes and sync.
You install bilbo, run bilbo setup once, and reach for bilbo restore when a
note went wrong. The rest happens in the conversation:
| You say | Your agent |
|---|---|
| "Note this" or "save this as a decision" | Writes or updates the note with the note skill, then runs bilbo check |
| "Recall X" or "what do we know about X" | Searches with the recall skill (bilbo recall) |
| A question the library answers | Answers with the reference skill, citing sources |
| "Ingest this page" | Adds it with the ingest skill |
| Anything at all | Gets the digest of the notes that bear on the prompt, before it starts |
bilbo new gotcha <topic> --title "<text>" # start a note, prints its path
bilbo check # lint the store, changes nothing
bilbo recall <words> # search notes, best first
bilbo recall <words> --library # search the library's sources
bilbo index # embed new passages for search by meaning
bilbo history <topic> # list a note's versions (the topic, not the path)
bilbo restore <topic> <version> # write a past version back
bilbo setup --remove # undo setup, keep your notesbilbo --help lists the verbs, and bilbo <verb> --help prints a verb's
options, output and exit codes. The rest is in
docs/reference/commands.md.
docs/README.md is the index. The main pages:
- Start: getting started, install, troubleshooting
- Guides: setup, agents, embedders, scopes, history, library
- Sync, all optional: devices, sync, relay
- Reference: commands, configuration, files
- Understand: concepts, security
Pull requests are welcome. Behavior changes start as an
OpenSpec change under
openspec/changes/; openspec/specs/ holds the current
contract. CONTRIBUTING.md covers the workflow, and
AGENTS.md holds the rules for agents working on the repo. To run
the tests, with Nix: nix develop -c cargo test --locked.