trusty-memory
A local memory server for coding agents, with searchable notes, a small knowledge graph and a background tidy-up pass.
by Bob Matsuoka (bobmatnyc)
In short
trusty-memory runs as a small daemon on your machine and speaks MCP. The agent (or a hook) saves notes, called drawers, into a named palace, usually one per project. Each note is embedded locally and kept next to a small knowledge graph of facts. A Claude Code hook adds the standing rules and the notes that match each prompt before Claude answers. When the machine is idle, a background pass merges near-duplicate notes and deletes old unimportant ones. An optional step uses an AI model to merge overlapping notes and flag contradictions.
Who it’s for
Developers who run coding agents such as Claude Code or Codex and want project memory that stays on their own machine. Also anyone building on its MCP tools or Rust library.
What it remembers
Notes the agent or you choose to save (decisions, conventions, project facts), facts as subject-predicate-object triples, short standing rules, and chat session history.
- Memory lives
- Your machine
- API keys
- None for the core; an OpenRouter key or local model for the optional AI merge step
- Works with
- Claude Code, Codex, Any MCP client
- License
- Open sourceMIT
- Price
- Free
Under the hood
- Who writes memories
- The agent or a hook calls a save tool (memory_remember, memory_note, kg_assert). A filter checks the text first. Facts in the graph are also pulled from saved notes by fixed rules, with no AI call.
- Where they're kept
- Files on your machine: a redb database for notes and the knowledge graph, an HNSW vector index, and a BM25 text index.
- How they're found
- By meaning, by keywords and by tags, with importance tilting the score. Notes are searched in layers: identity, a hot cache of top notes, then full search.
- Extra AI calls
- None for the core. The optional merge step makes AI calls to OpenRouter or a local model, up to 20 per cycle.
How it works
- 1Agent savesA tool call or hook sends a note or a fact.
- 2FilterNoise, short text and secrets are rejected.
- 3StoreEmbedded locally; kept with a small graph of facts.
- 4Dream passWhen idle, near-duplicates merge and faded notes are deleted.
- 5Hook recallStanding rules and matching notes are added to the next prompt.
What stands out
- Runs fully on your machine: local embeddings, no API key needed for the core features.
- Facts can carry a slot name and an expiry, so a point-in-time fact such as a pull request's state is replaced when the next one is written.
- A hook injects always-on standing rules and the notes that match each prompt, so memory reaches the agent without a tool call.
- The dream pass records every deletion with its reason, and surfaces high-value notes that are fading instead of silently boosting them.
What it doesn’t do
- Notes are not written for you. The agent or a hook has to call a save tool, and a filter rejects short, noisy or secret-looking text.
- Recalling a note does not make it stronger. The code has a counter for this, but nothing in the released version updates it.
- No emotional weighting, no reminders that fire on a date, and no beliefs or profiles built up about people.
- A corrected fact only replaces the old one when the writer names the slot or the predicate is single-valued. Contradicting free-text notes are not found on their own.
- Old unimportant notes are deleted by the background pass, not archived. A log records what was removed.
Measured against human memory
2 built, 7 partly, 2 not of the Field Guide’s 11 mechanisms
Encoding
Salience
Decides what's worth keeping, and how much, as a memory is written.
A save filter drops short, noisy and secret-looking text by stated rules, and notes carry an importance score. The score is a default or a value the caller sets. source
Emotion
Gives memories written with feeling more weight.
No emotional weighting. Nothing in the code reads or records feeling.
Storage
Forgetting
Lets unused memories fade over time on its own.
Each note's importance halves every 90 days from when it was written, and the dream pass deletes notes that have sunk to the floor and are more than 30 days old. source
Interference
When a new memory closely matches an old one, notices and lets the newer one win.
The dream pass merges notes whose meaning is 95% alike, keeping the one with higher importance, not the newer. A named slot replaces its old fact. source
Retrieval
Retrieval
Remembering something makes that memory stronger.
Being recalled does not strengthen a note. The access counter and boost exist in the code, but no released code path calls them. source
Association
Links memories, so recalling one brings its neighbours.
Saving a note adds graph links by fixed rules (tags, room, a few patterns like "X uses Y"). Recall does not follow them. Walking the graph is a separate query. source
Prospective
Brings a memory back at the right time without being asked.
A hook adds standing rules and the notes that match each prompt before Claude answers. The cue is the prompt itself. There are no date reminders. source
Transformation
Consolidation
Reworks memories between sessions: strengthening, merging, reorganising.
While idle, a dream pass merges near-duplicates, deletes noise and faded notes, cleans the index and flags fading high-value notes. Deletions are logged with a reason. source
Reconsolidation
Corrects a memory when it's contradicted, and keeps what it used to say.
Replacing a slot or a single-valued fact closes the old version, which is kept as history. Contradicting free-text notes are only flagged, and only in the optional AI step. source
Gist
Turns many specific moments into general knowledge.
An optional AI step, off by default, collapses overlapping notes into one canonical note and links aliases. It merges; it does not draw lessons. source
Schemas
Forms beliefs about people and projects, and weighs new facts against them.
A small set of standing facts per palace (aliases, conventions, shorthands) is always injected, capped at 20. There is no profile of a person or project that updates itself. source
Not every system is trying to be a human memory, so a hollow dot isn’t a flaw. It just says what the system doesn’t do. What the mechanisms are.
trusty-memory’s makers haven’t shared what they’re building next, so only today shows here. Makers can add their roadmap the same way they correct an entry.
Compare trusty-memory with the others, side by sideQuestions
- Who is trusty-memory for?
Developers who run coding agents such as Claude Code or Codex and want project memory that stays on their own machine. Also anyone building on its MCP tools or Rust library.
- Where does trusty-memory keep its memories?
Your machine. Files on your machine: a redb database for notes and the knowledge graph, an HNSW vector index, and a BM25 text index.
- Does trusty-memory forget?
Forgetting: built, basic. Each note's importance halves every 90 days from when it was written, and the dream pass deletes notes that have sunk to the floor and are more than 30 days old. source
- Does trusty-memory correct a memory when it turns out to be wrong?
Reconsolidation: partly. Replacing a slot or a single-valued fact closes the old version, which is kept as history. Contradicting free-text notes are only flagged, and only in the optional AI step. source
- Is trusty-memory open source?
Yes, it's open source. License: MIT. Code: github.com/bobmatnyc/trusty-tools.
- Does trusty-memory work with Claude Code?
Yes. Works with: Claude Code, Codex, Any MCP client.
- Does trusty-memory need an API key?
API keys: None for the core; an OpenRouter key or local model for the optional AI merge step.
- How much does trusty-memory cost?
Price: Free.