Provides a personal memory layer for AI agents by storing and recalling session decisions and note citations in local markdown files.
Also known as shinytoyrobots/rutter, rutter-memory
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 14, 2026
- License
- MIT
What is rutter MCP?
rutter provides a personal memory layer for AI agents by storing and recalling session decisions and note citations in local markdown files.
Summary generated from the project's README
About rutter MCP server
rutter acts as a personal memory layer for AI agents by storing session decisions and note citations in local markdown files. Unlike vendor-managed memory, this server saves records in a dedicated folder within your own notes directory, making the data portable, searchable, and compatible with git. It is designed for developers who use markdown-based note-taking systems and want to maintain a consistent history across different AI tools.
The system works by using client-side hooks to append one-line summaries of decisions to dated files. It tracks the specific state of your notes by storing content hashes, which allows the server to recognize a note even if it is renamed. It supports several clients including Claude Code, Grok, Codex, GitHub Copilot CLI, Antigravity, and Muse Code. While most supported clients can both read and write to this memory, other MCP clients can use the server for recall-only purposes via npx.
Users interact with the memory through three primary tools: librarian-search for full-text queries, librarian-get-note to retrieve specific file contents, and librarian-recent to view recent session activity. The server also maintains a local SQLite FTS5 index to facilitate fast searching without altering your original markdown files.
What you can do with it
- 1Retrieve past session decisionsAsk your AI client to recall what you concluded during a previous coding session.
- 2Maintain memory across different toolsAccess decisions made in Codex while working within Claude Code.
- 3Search through historical session summariesPerform a ranked full-text search to find specific topics or decisions within your recorded history.
Written from the project's README. Every use case is checked against a quote from it.
How to install rutter MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall rutter MCP in Claude Code
$ claude mcp add --env 'LIBRARIAN_VAULT_PATH=<LIBRARIAN_VAULT_PATH>' rutter -- npx -y rutter-memoryInstall rutter MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"rutter": {
"command": "npx",
"args": [
"-y",
"rutter-memory"
],
"env": {
"LIBRARIAN_VAULT_PATH": "<LIBRARIAN_VAULT_PATH>"
}
}
}
}Install rutter MCP in VS Code
.vscode/mcp.json
{
"servers": {
"rutter": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"rutter-memory"
],
"env": {
"LIBRARIAN_VAULT_PATH": "<LIBRARIAN_VAULT_PATH>"
}
}
}
}Install rutter MCP in VS Code CLI
$ code --add-mcp '{"name":"rutter","type":"stdio","command":"npx","args":["-y","rutter-memory"],"env":{"LIBRARIAN_VAULT_PATH":"<LIBRARIAN_VAULT_PATH>"}}'Install rutter MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"rutter": {
"command": "npx",
"args": [
"-y",
"rutter-memory"
],
"env": {
"LIBRARIAN_VAULT_PATH": "<LIBRARIAN_VAULT_PATH>"
}
}
}
}Install rutter MCP in Codex
$ codex mcp add rutter --env 'LIBRARIAN_VAULT_PATH=<LIBRARIAN_VAULT_PATH>' -- npx -y rutter-memoryInstall rutter MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.rutter] command = "npx" args = ["-y", "rutter-memory"] [mcp_servers.rutter.env] LIBRARIAN_VAULT_PATH = "<LIBRARIAN_VAULT_PATH>"
Install rutter MCP in Gemini CLI
$ gemini mcp add -s user -e 'LIBRARIAN_VAULT_PATH=<LIBRARIAN_VAULT_PATH>' rutter npx -- -y rutter-memoryInstall rutter MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"rutter": {
"command": "npx",
"args": [
"-y",
"rutter-memory"
],
"env": {
"LIBRARIAN_VAULT_PATH": "<LIBRARIAN_VAULT_PATH>"
}
}
}
}Configuration
LIBRARIAN_VAULT_PATHRequiredFolder of markdown notes (an Obsidian vault works)
LIBRARIAN_USER_LABELName the server uses for whose work this is; defaults to 'the user'
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableshinytoyrobots/rutter is public and reachablegithub.com/shinytoyrobots/rutter ↗Pass
- Package names this repository as its sourcerutter-memory names shinytoyrobots/rutter as sourcenpmjs.com/package/rutter-memory ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for rutter-memorynpmjs.com/package/rutter-memory/v/1.0.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/shinytoyrobots/rutter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from rutter-memoryPass
- No critical advisory in the package or its dependencies109 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubrutter
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.
| You use | Follow | What it takes |
|---|---|---|
| Claude Code | Fast path for Claude Code | A few minutes; nothing to clone |
| Grok | Grok path | One npm install, a hook, and one grok mcp add |
| Codex | Codex path | One npm install, and a hook you trust |
| GitHub Copilot CLI | Copilot CLI path | One npm install, a hook, and an instructions file |
Antigravity CLI (agy) |
Antigravity path | One npm install, a hook, and a rule file |
Muse Code (muse) |
Muse Code path | One npm install and one installer run |
| Any other MCP (Model Context Protocol) client | Recall only, with npx | One config entry. Search and recall only: with no hook, nothing is captured |
| Claude Code, from a clone | From source | Eight steps (M1 to M8), starting with a record written by hand. For contributors |
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
<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 indocs/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
gitand never contacts a remote. - Three read-only MCP tools:
librarian-search— ranked full-text search. Every result carries its path,type/status/createdprovenance, 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; optionalprojectfilter,windowin days, orcount.
- Instructions that travel with the server. Any connected client is told to reach for
librarian-recenton recency questions andlibrarian-searchon "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 nextnpm run reindexbinds the old reference to its new path automatically — no heuristics, no similarity scoring, just an exact content-hash match — andlibrarian-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 onlibrarian-recent, and on search enrichment against any candidate note that happens to be a search result, and stays that way until you confirm it withnpm run identity-confirm. A reference with no candidates at all (renamed and edited) is visible onlibrarian-recentonly — that listing is the complete discovery surface for unresolved references; enrichment is candidate-anchored and cannot mention what has no candidate. On the search surface, a mere candidate is never annotated as if it had been engaged with; the unresolved state and its candidates render as a separate, explicit note instead. A confirmed binding is sticky: if the vault later changes such that automatic exact-hash matching would point somewhere else, the confirmed binding still wins, and the disagreement is surfaced ("confirmed X; the hash now matches Y") rather than silently overridden — only re-runningnpm run identity-confirmmoves it. The stored session record is never rewritten either way.
Known limitations
Stated here rather than discovered later:
- Older records are dense. The style contract and its word budget arrived after the first fortnight of capture, and existing records are never retrofitted. Early entries read like build logs. Read-time guidance is the only layer that reaches them.
- Quality depends on your client. The server holds no model, so a client that ignores the style contract produces summaries the server will faithfully store anyway.
- Shared across your tools, not across people. One person's tools share one memory. Nothing here addresses records shared between people, ratification, or whose version of a decision wins. Those are the hard problems at team scale and none of them are solved here.
- Records name the client, not the model. A session entry carries a
clientlabel (claude,grok,codex,agy,copilot, ormuse) when the hook can establish it, so you can see which client stopped writing summaries. It is the host, not the model:agyruns Gemini and Claude models, and no hook payload says which. A label is left off rather than guessed, so records from before the label existed, hand-registered hooks, and ambiguous turns show none. You cannot filter or search by client yet. - Capture depends on each tool's model following the instructions. The hook only lifts a line the model wrote. Claude Code, Grok, Codex, Copilot CLI, Antigravity, and Muse Code were each checked with a real session. A model that skips the line leaves nothing to capture.
- A rebuild can briefly overlap another session. The server rebuilds its index when it starts and finds changes, which drops and recreates the tables for about a second per few thousand notes. A search from another open session at that instant can come back empty. It is rare, because an unchanged index is never rebuilt, and it clears on the next call.
- A reference shows what was captured, not what was read. The client chooses which paths to list, and the hash is taken when capture runs, after the turn. rutter cannot establish that the model read a file, that a file produced the conclusion, that capture is complete, or that a note at an unchanged path has not changed since (that report is not built). Append-only is a rule the server follows, not tamper-proof auditing. See what rutter can and cannot establish.
- Semantic search is stubbed.
embeddings.tsis a port with no implementation; retrieval is full-text only. - Under active evaluation. The stateful behavior is behind a usage gate — the project measures whether it actually gets reached for, and is prepared to conclude that it doesn't.
Requirements
- Node ≥ 22 (uses the built-in
node:sqlite— no native build step; FTS5 included). Verified on Node 26. - A directory of markdown notes. Obsidian is what it was built against — wikilinks and frontmatter are understood — but nothing requires Obsidian itself.
- Claude Code, Grok, Codex, Copilot CLI, Antigravity, or Muse Code, for ambient capture. The MCP tools work with any MCP client. The table in One memory across your AI tools shows how each of the six captures and links to its setup. Claude Code lifts the directive from the transcript, and so do Copilot CLI and Antigravity (from the current turn). Grok, Codex, and Muse Code use the Stop event's final assistant message, so with Codex and Muse Code the directive must be in the final reply.
Setup
Point it at your notes first. The default is the author's own path, and an unreadable directory is not an error — you get a successful reindex reporting zero notes, which looks like a working install until you search and find nothing.
From npm:
export LIBRARIAN_VAULT_PATH=/path/to/your/notes # do this before reindexing
npm install -g rutter-memory
rutter-memory reindex # expect a non-zero note count; zero means the path is wrong
The rutter-memory command starts the MCP server when run with no arguments, which is how a
client launches it. It also takes reindex [--force], recent, and install-hook;
rutter-memory help lists them. Installing rutter-memory also gives you a rutter command,
the same program under a shorter name; that is unrelated to the rutter package on npm.
From a clone, to work on the code:
export LIBRARIAN_VAULT_PATH=/path/to/your/notes # do this before reindexing
npm install
npm run build # compile to dist/ (optional; tsx runs the TS directly)
npm run reindex # expect a non-zero note count; zero means the path is wrong
Config via environment variables:
| Var | Default | Meaning |
|---|---|---|
LIBRARIAN_VAULT_PATH |
~/Documents/knowledge-vault |
Notes directory to index (read-only). Set this. |
LIBRARIAN_DB_PATH |
npm install: ~/.local/share/rutter/<id>/librarian.db, one per notes folder. Clone: <repo>/data/librarian.db |
Where the derived index lives. An npm install honors $XDG_DATA_HOME in place of ~/.local/share. An index serves only the notes folder that built it; a second folder pointed at the same file is refused, and reindex --force hands the file over. |
LIBRARIAN_USER_LABEL |
the user |
How the server describes whose work this is, in the instructions and tool descriptions your client receives. Set it to your name and the client is told it is looking at your work, which reads more naturally than "the user's". |
Memory-of-use (session records, the use log) lives under <notes>/_librarian/ — inside your notes
directory, never in this code repo. See docs/memory-of-use.md.
New here? Read docs/overview.md for what the librarian is and how it
works, then docs/memory-of-use.md for the capture / recall /
enrichment / gate behaviors in depth. The same docs are published readable at
shinytoyrobots.github.io/rutter —
npm run site-drift reports when that site has drifted from these files. docs/roadmap.md is the current
sequencing.
docs/decision-graph.md is the design behind positions, which v1.0.0 removed — why a position is a
projection over the append-only event log rather than a second thing you maintain — and
docs/decision-graph-plan.md is the build plan that split it into phases.
Try it from the CLI
From an npm install, rutter-memory recent takes the same arguments as npm run recent below.
Search, the usage gate, and identity-confirm run only from a clone:
npm run search -- bitemporal forgetting memory # full-text search
npm run recent # recent session summaries
npm run recent -- --days 7 # just the last week
npm run recent -- --project rutter # just one project (case-insensitive)
npm run gate # per-ISO-week use count
Entries captured before workspace provenance existed simply show no project — there is no
placeholder, and a --project filter skips them rather than guessing.
If npm run recent shows a ref as [UNRESOLVED -- candidates: ...] after a rename that also
changed the note's content (or landed on duplicate content), confirm the right target by hand —
this is a local-only command, never an MCP tool, so an agent can't rewrite what a dead reference
means on its own:
npm run identity-confirm -- Notes/old-name.md Notes/new-name.md
Enable ambient capture (two steps, one-time)
There is nothing to add to your CLAUDE.md. The whole capture contract — that a summary
should be left, the exact syntax, and how to write it — ships inside the server as MCP
instructions, which the server sends to every client on connect. Register the hook, restart, done.
Antigravity and Copilot CLI are the exceptions. Antigravity saves those instructions as a file instead
of putting them in the prompt, and Copilot loads them only once a rutter tool is called, so both
installers also write an instructions file. (Full detail in
docs/memory-of-use.md.)
1. Register the Stop hook. From an npm install, run:
rutter-memory install-hook # adds the hook to ~/.claude/settings.json
rutter-memory install-hook --client codex # Codex: ~/.codex/hooks.json (then trust it via /hooks)
rutter-memory install-hook --client antigravity # Antigravity: ~/.gemini/config/hooks.json
rutter-memory install-hook --client copilot # Copilot CLI: ~/.copilot/hooks/rutter.json
Install globally (npm install -g), not through npx: the hook is registered by absolute path, and
the npx cache can be cleared at any time. After switching Node versions, reinstall and re-run the
same line; it moves the existing hook to the new path rather than adding a second one.
From a clone, either run:
npm run build && npm run install-hook # adds the hook to ~/.claude/settings.json
npm run build && npm run install-hook -- --client codex # Codex: ~/.codex/hooks.json (then trust it via /hooks)
npm run build && npm run install-hook -- --client antigravity # Antigravity: ~/.gemini/config/hooks.json
npm run build && npm run install-hook -- --client copilot # Copilot CLI: ~/.copilot/hooks/rutter.json
…or add it to ~/.claude/settings.json by hand (the hook runs dist/capture-cli.js, so
build first):
{
"hooks": {
"Stop": [ { "hooks": [ { "type": "command", "command": "/ABSOLUTE/PATH/hooks/librarian-stop.sh" } ] } ]
}
}
2. Restart Claude Code. Hooks are read at session start; a fresh session also picks up
the newly built server. Verify with /mcp (four tools), then check captures land in
<notes>/_librarian/sessions/ after your next real session.
rutter MCP questions
How do I add rutter MCP to Claude Code?
Run claude mcp add --env 'LIBRARIAN_VAULT_PATH=<LIBRARIAN_VAULT_PATH>' rutter -- npx -y rutter-memory in your terminal. Add --scope user to make it available in every project.
How do I add rutter MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Where is my data stored?
Your records are stored as plain markdown files in a _librarian/ folder located beside your existing notes folder.
Can I use rutter with different AI clients?
Yes, it works across multiple clients like Claude Code, Grok, Codex, and Copilot CLI by reading from and writing to the same local markdown folder.
Does rutter use a model to process my notes?
No, there is no model inside the server; it is code and storage, meaning the reasoning remains within your AI client.
What happens if I rename a note?
If you rename a note without editing its content, rutter uses the content hash to automatically bind the old reference to the new path during reindexing.