rutter

rutter

A personal memory layer for AI agents. One memory. Multiple agents. Yours.

The model isn't the memory. Your notes are. rutter recalls past decisions and the notes your AI session cited. The records are plain markdown in your own notes folder (in a _librarian/ folder beside the notes), not inside a model or a vendor's account.

It is an MCP (Model Context Protocol) server over that folder. As a session decides something, your client leaves one line about it. A hook (a script the client runs after each turn) stores that line, without rewriting it for style, in a dated file inside your notes folder, with the path and a content hash (a fingerprint of the note's contents) of each note it cited.

Weeks later you ask what you concluded, in the same AI tool or another one you have set up, and get the line back with its date and its notes. A note renamed without edits is followed by its hash. A reference rutter cannot place is shown as unresolved rather than dropped. A note changed in place is not flagged yet.

It suits people who keep markdown notes and are comfortable configuring an AI client. Start with docs/getting-started.md; Claude Code users can install the plugin in a few minutes. Everyone else installs from npm, where the package is rutter-memory (the name rutter there belongs to an unrelated library).

There is no model inside it. It is code plus storage, so the reasoning stays in your client.

The name is from the age of sail: a rutter was the logbook of the routes actually sailed, as against the map. The map records what is known. The rutter records what you did about it.

A personal tool, published as a reference implementation — not a supported product. Built for

one person's workflow and shared because the mechanism might be useful. No roadmap promises, no

support commitment, no guarantee the next commit won't move something you depend on. Fork it, take

the ideas, file an issue if you like. Please don't put anything load-bearing on top of it.

One memory across your AI tools

rutter keeps one set of records for Claude Code, Grok, Codex, Copilot CLI, Antigravity, and Muse Code. Each client writes its session summaries to the same notes folder. Each client reads them back through the same MCP server.

A decision you made in Codex on Tuesday is there when you ask Claude Code on Thursday, provided Codex wrote a line for it and its hook ran. You copy nothing between clients. This works because the memory is a folder of markdown files you own, not a feature inside one tool.

Grok was verified on Linux only (known issues). The npm-only paths (Codex, Copilot CLI, Antigravity, Muse Code) were tested on a machine that also had Claude Code, so a clean machine is untested; see known issues.

Every client can read the memory once its MCP server is registered. Writing needs a hook that runs after each turn, and these six have one. Any other MCP client can read but not write, running the server through npx (recall only, with npx). The Antigravity row covers the agy command-line tool, not the Antigravity IDE.

Point every client at the same notes folder. Each sets it differently. The Claude Code plugin asks for it at install. Grok, Codex, and Copilot CLI read LIBRARIAN_VAULT_PATH from the shell that launches them. Antigravity's and Muse Code's installers take --vault. Each record notes which client wrote it, when the hook can tell (see *Known limitations*).

How this differs from memory you already have

Your harness almost certainly does this already, after a fashion. Claude Code writes session recaps and infers preferences into a memory folder, then consolidates them over time — merging duplicates, dropping what looks stale.

Consolidation is a reasonable default. It is also the opposite of what this does.

Nothing here ever rewrites a stored line. Records are append-only, grouped by session when you read them, and a line is not rewritten for style on the way in: only a one-line normalization and a 2,000-character cut apply.

The second difference is the one that matters more. A summary on its own is not a record — it is an assertion. A summary plus the versioned state of the notes it cited is a record, because it gives you a fingerprint to compare against.

Neighboring approaches each do part of that second part. Architecture decision records capture the *what* and the *why* without pinning the version they applied to. Event-sourced logs timestamp events but rarely carry file-level provenance. Supply-chain provenance formats hash content properly, but they are built for auditors rather than for your next working session. So decisions drift quietly away from the code that produced them, and nothing announces it.

Here, every reference carries the content hash of the note as it stood when the line was captured. A renamed note is followed by exact hash match, and a note that cannot be placed is shown as unresolved instead of silently dropped. The stored hash also lets you compare a file against what it was then. Reporting a note that changed in place is not built yet.

Two smaller things follow from the design. The store is yours — markdown in your own notes directory, not a vendor's account or a tool's private folder, so it stays portable, greppable, git-committable, and readable if this project disappears. It is also why every client you use can write to and read from the same records. And because your client writes the summary while its context is still loaded, capture needs no second model call and no network call. The trade is that quality depends on your client honoring the style contract, set out in *What the server tells the client*.

None of this competes on retrieval. A capable agent reading a well-organized notes directory already retrieves well. This exists for the part an ephemeral session cannot be: memory across time.

What it does today

• Indexes the notes directory into a local SQLite FTS5 full-text index — a disposable, regenerable cache. Your files stay the source of truth.
• Ambient capture. As a session decides or produces something, your client leaves a line about it, and a Claude Code, Grok, Codex, Copilot CLI, Antigravity, or Muse Code Stop hook appends that line to /_librarian/sessions/ .md, referencing touched notes by content hash. The client is asked for one line per separable outcome rather than one per session — a working session usually leaves three or four — grouped back into a single account of that session when you read it. A line the same session already recorded is skipped (the exact rule is in docs/memory-of-use.md). Durable, git-committable, written by your client.
• A style contract on that line. Write for a smart reader in a hurry who wasn't in the session: outcome first, common words over session shorthand, no invented codenames or version tags, about 40 words. The contract is guidance carried in the server's MCP instructions. The server does not rewrite a summary for style — over-budget summaries are reported on the capture path and then stored without edits. It does normalize each line to one line (control characters dropped, whitespace collapsed) and cut it past 2,000 characters; see the style contract.
• Workspace provenance. Each entry carries the session's working directory, a project name derived from it, and the git remote URL when there is one, so a day spanning three efforts reads cleanly. Nothing to configure; resolution is pure local file reads — it never runs git and never contacts a remote.
• Three read-only MCP tools:
• librarian-search — ranked full-text search. Every result carries its path, type/status/created provenance, and a matching snippet. Multi-word queries are AND-matched, so "blue man group" finds notes with all three rather than any. A result you engaged before also carries a quiet prior-engagement note, additive only, never re-ranking.
• librarian-get-note — one note's full content, by path.
• librarian-recent — *"what was I working on lately?"* Sessions newest-first, with dates, project, and provenance; optional project filter, window in days, or count.
• Instructions that travel with the server. Any connected client is told to reach for librarian-recent on recency questions and librarian-search on "have I seen this?" questions before reading files directly, and to report recalled summaries in plain language — including entries written before the contract existed, which is the only way dense old records ever read clearly. No per-project client configuration.
• Instruments its own use. A local per-ISO-week count of how often the stateful behavior gets reached for.
• Position capture: stopped (v0.10.0); the positions tool is removed (v1.0.0). Rutter no longer asks your client for a second, rarer position line, and the capture hook stores none. No new positions are recorded. Session lines now say when you made the call and keep your reason; the belief questions that originally motivated positions have not been rerun to confirm that is enough. Existing streams in _librarian/positions/ stay as your own history, which rutter no longer reads or changes. Why: docs/position-retirement-2026-11.md.
• Note identity survives a rename. A reference records the note's path *and* its content hash as captured. "Dead" means the path is missing from disk, full stop, regardless of file type — a reference to any confined vault artifact (a .gitignore, an exported .html, a file under _librarian/ itself) is live for as long as that file exists, whether or not it's an indexed markdown note. Rename a referenced note without touching its content and the next npm run reindex binds the old reference to its new path automatically — no heuristics, no similarity scoring, just an exact content-hash match — and librarian-recent / search enrichment quietly resolve through it. If reindex can't tell (the note was also edited, so no current note's hash matches; or more than one current note shares the hash), the reference renders explicitly as unresolved with its candidates on librarian-recent, and on search enrichment against any candidate note that happens to be a search result, and stays that way until you confirm it with npm run identity-confirm. A reference with no candidates at all (rename