rutter

# rutter

**Recall past decisions and the notes your AI session cited.**

An MCP (Model Context Protocol) server over a folder of markdown notes. As a session decides
something, your client leaves one line about it. A hook stores that line, without rewriting it for style, in a
dated file inside your notes folder, with the path and a content hash 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`](./docs/getting-started.md); Claude Code users can [install the
plugin](#install-as-a-claude-plugin) in a few minutes. Everyone else installs from npm, where the
package is [`rutter-memory`](https://www.npmjs.com/package/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, and Antigravity. 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.

| Client | How it captures | Setup |
|--------|-----------------|-------|
| Claude Code | The hook reads the whole session transcript. | [Install the plugin](#install-as-a-claude-plugin) |
| Grok | The hook reads the final reply. | [Uses the Claude Code plugin](#grok) |
| Codex | The hook reads the final reply only. | [npm install, then four steps](#codex) |
| Antigravity CLI (`agy`) | The hook reads the current turn from `agy`'s transcript. | [npm install, then four steps](#antigravity-cli) |

Every client can read the memory once its MCP server is registered. Writing needs a hook that runs after each turn, and these four
have one. Any other MCP client can read but not write, running the server through `npx`
([recall only, with npx](./docs/getting-started.md#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 and Codex read `LIBRARIAN_VAULT_PATH` from the shell that launches them.
Antigravity's installer takes `--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, or Antigravity Stop hook appends that line to `<notes>/_librarian/sessions/<date>.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`](./docs/memory-of-use.md#where-rutter-keeps-what-it-remembers)). 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](./docs/memory-of-use.md#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.
- Four 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`.
  - `librarian-positions` — *"what do I think about X, and did that change?"* Query one of three ways: `topic` for an exact topic key (one answer or an explicit not-found), `query` for free text matched against your recorded stances, or `note` for the positions that reference a note by path. Each answer is the topic's current stance with the dates it was formed and last revised; add `chain: true` for the whole supersession history.
- **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** *(decision-graph Phase A)*. When your client forms, changes, reaffirms, or retires a stance on a topic, it leaves a second, rarer kind of line — a position directive — appended to `<notes>/_librarian/positions/<YYYY-MM>.md`, a wholly separate append-only stream from session records. The directive's kind (`assert`, `revise`, `reaffirm`, `retire`) selects what the event does; the stance prose is not classified, and only two strings in it are read — a `[[wikilink]]` becomes a versioned reference and `revises: <event-id>` records the event it replaces — with neither removed from the stored text. Not rewritten for style, idempotent per distinct directive.
- **Position recall** *(decision-graph Phase B)