v3.2.0 · Runs on your machine · No account · MIT

Persistent, self-verifying memory for AI coding agents

Muse stores what your agent learned — the decisions, the fixes, the constraints — checks every note against the code it cites, and hands back only what still holds. In-process, sub-2ms, no daemon.

npx musememory connect

Get memory in one command Read the docs

Recall latency: sub-2ms
Hot cache lookup: <50µs
Import formats: 30
Tests passing: 1,443

The problem

Why your agent forgets everything by Thursday

An assistant only knows what fits in its context window. When the session ends that context is discarded, so the next session starts from zero — and the cost compounds every time you re-explain something that was settled yesterday.

Every session starts from zero

You re-explain the architecture, the auth flow, the one decision nobody else understands. Every morning. The context window is a scratch pad, not a notebook.

Memory that ignores your git state

Check out a hotfix and the agent still applies rules from the branch you abandoned. Stale facts leak into stable code and nobody notices until it ships.

A flat MEMORY.md is a cache killer

Every edit invalidates the whole prefix. You pay to re-read the same context each session, and the file becomes nobody's source of truth.

No blame, no rollback

A hallucinated rule poisons every future recall. There is no `git blame` for memory, no checkout, no way back to the state before the mistake.

Show, don't tell

Every memory gets one of three outcomes

Nothing is stored on faith. A note is either confirmed against the code it cites, refused because that code does not exist, or withheld because the code moved on since — and in that last case you are told why.

Ten seconds on the engine's story — every number on screen is a measured benchmark, not a claim.

Remembered
auth uses jose, not jsonwebtoken
The cited symbol exists — handed back next session.
Refused
see src/legacy/auth.ts
The file does not exist — the write never happens.
Withheld
session store uses Redis
The code drifted since the note — held back, and you are told why.

How it works

Your data never leaves the machine

Muse runs as a process you start and stop. There is no server to operate, no account to create, and no network call in the path of a recall. The whole engine is a SQLite database and a folder of YAML files you can open in any editor.

One process, two scopes. Project memory travels with the repo; global memory holds the preferences that follow you.

Remember it

When your agent makes a decision or fixes a bug, Muse saves a short note — what changed and why.

Every write passes a credential scan first, and the note lands as a readable YAML file beside a SQLite row.

Check it

Before the note is stored, Muse confirms the file or function it mentions actually exists.

Citations are structural fingerprints, not line numbers, so moving a function does not silently break the note.

Hand it back

Next session, Muse returns the notes that fit the task — sized to your budget, not the whole archive.

One in-process query over SQLite FTS5. Under 2ms, with a hard token ceiling. No daemon, no network, no model call.

Everything is a file you can read

Delete the folder and the memory is gone. Commit it and memory becomes code — reviewable in a pull request, revertible withgit revert.

.memory/                                  # project scope
├── memory.db                             # SQLite: memories, anchors, graph
├── memories/                             # one YAML file per memory
├── CURRENT.md                            # active constraints
├── USER.md                               # your persona
├── observations.jsonl                    # the event log the harvester mines
└── audit.jsonl                           # tamper-evident write ledger

~/.memory/                                # global scope

The surface

Real commands, real tools

Every capability below is something you can run right now. No dashboards to configure, no workflows to author — a command, or a tool your agent calls.

One command wires your tools

Muse detects the coding agents you already run and connects the memory server to each one over MCP — with no permission prompts and no config file to hand-edit.

npx musememory connect

Writes are scanned, not trusted

Every write — capture, import, sync packet — is matched against credential patterns first. A suspected secret stops the write instead of landing in a file you might later commit.

memory capture "auth uses jose" --project core

Citations are verified at write time

A note that points at a file or function which does not exist is rejected on the spot. Hallucinated citations never reach the store.

memory anchor create --file src/auth.ts --symbol verify

Stale notes are withheld, not served

At recall time Muse re-checks every citation. If the code moved on, the note is held back and reported — never handed over as if it were still true.

muse_context  # returns withheld_memories + freshness_notice

Memory is versioned like code

Scope memory to a branch, blame a note back to the session that wrote it, and roll back to a known-good state. Git for AI memory.

memory branch m_1700… --path core/auth
memory blame m_1700…

Failures become permanent lessons

Muse watches the error → fix → no-recurrence sequence in your session logs and distills a negative memory, so the same mistake is not made twice.

memory capture --negative "AVOID: jwt.sign without an explicit algorithm"

Proof

Measured, not claimed

Recall takes under two milliseconds because it is a local database query, not an API call. The hot cache answers in under fifty microseconds. Run memory benchmark to reproduce every number on this page.

Latency on the same machine, same store. The network row is a reference point, not a Muse claim.

Recall latency: sub-2ms; SQLite FTS5 BM25, in-process
Hot cache lookup: <50µs; L0 in-process cache
Import formats: 30; other memory systems
Tests passing: 1,443; 217 files, runs offline
Background services: 0; nothing to keep running
MCP tools: 115; 7 task-focused profiles

Four gates, every time

On every writeCredential scanThe write is refused and the rule is named. The value is never echoed.

On every writeCitation checkA note citing a file or symbol that does not exist is refused.

On every recallFreshness gateNotes whose code drifted are withheld and reported, not served.

On every importContext strippingInjected context blocks and base64 payloads are removed before storage.

Lifecycle

Notes have a life, and an end

Nothing is written and forgotten. Every note moves through a deterministic lifecycle, decays on a schedule tied to how much you trust it, and can be restored if you delete it by mistake.

confirmed is the only state served by default. A deletion is a tombstone — memory restore brings it back.

Landscape

How it is different

Vector stores optimise for similarity and graph platforms for relationships. Muse optimises for what a coding assistant actually needs: recall that is fast, local and tied to your code — and that never passes off a stale fact as current.

Capability comparison between Muse Memory, dense vector stores, and entity-relationship graph platforms.
Capability	Muse Memory	Vector stores dense embedding-based	Graph platforms entity relationship-based
Runs 100% local, zero daemons	✓	✕	✕
No API key required	✓	✕	✕
Sub-2ms retrieval, in-process	✓	✕	✕
Write-time citation verification	✓	✕	✕
Recall-time freshness gate	✓	✕	✕
Deterministic lifecycle state machine	✓	✕	✓
Structural anchors that survive refactors	✓	✕	✕
Secret scanning on every write	✓	✕	✕
One command wires your agents	✓	✕	✕
Memory files you can review in git	✓	✕	✕

Generalizations — each platform evolves quickly, so check their docs. The Muse column reflects v3.2.0.

See the full comparison →

Get started

One line. That's the whole setup.

Open a terminal in your project, paste the line, press enter. Muse finds the coding agents you already run and connects each one over MCP, with only the tools its task needs. Time to first value: under a minute.

1
Paste one line
No install step, no config file, no account.
```
npx musememory connect
```
2
Let it wire your tools
Each agent gets the memory tools its task needs — nothing more.
```
memory hooks install   # optional: hands-free recall
```
3
Keep working
Ask why something is the way it is — your agent can now look it up.
```
memory context --query "how does auth work" --budget 2000
```

CLI80+ commands, scriptable, no daemon

MCP115 tools over stdio

Profiles7 task-shaped tool sets

FilesYAML + SQLite, yours to read

Everything stays on your machine. Read the docs,point your agent at llms.txt, orread the source.

Free forever. No paid tier, no telemetry.

Muse is MIT-licensed. The whole engine — capture, ranking and recall — runs in-process on your machine, so there is no hosted component to charge for and nothing to phone home about. Clone it, fork it, ship it inside your product.

Install from npm Read the source ↗

Licence: MIT
Cost: Free
Account: None
Telemetry: None
Network calls: None by default
Background daemons: 0

Plain English

Words in this page, explained

No prior knowledge assumed. Skip it if you already live in a terminal.

AI coding agent: An AI assistant that reads and edits code in your project — Claude Code, Cursor, Codex, Windsurf and similar tools.
Agent memory: What an assistant keeps between sessions: decisions, fixes and preferences it can look up later instead of rediscovering.
Context window: The fixed amount of text an assistant can consider at once. Anything outside it is invisible — which is why sessions forget.
MCP: Model Context Protocol — the standard way assistants connect to outside tools like Muse. You never have to use the acronym.
Local-first: The data lives and is processed on your own machine. No account, no upload, no service that can go down or change its pricing.
Code anchor: A pointer from a note to a specific file or function. Muse uses a structural fingerprint instead of a line number, so refactors do not break it.

FAQ

Questions people ask before installing

Do I need to know how to program to install it?

No, but you do need a terminal. The setup is one line you paste and run — no config file to write, no server to set up, no account to create.

Do I need an API key or a subscription?

No account, no API key, no subscription. Muse is MIT-licensed and free. It never calls a model: recall is a database query on your own machine, so there is nothing to bill.

Where is my data stored?

Two folders on your computer: .memory/ inside each project, and ~/.memory/ for anything that applies everywhere. Plain SQLite and YAML you can read, edit, back up, ignore, or commit to git. Nothing is uploaded.

Will it slow my assistant down?

No. A lookup runs in under two milliseconds locally with a hard token budget, so it returns a short list rather than everything. That is far cheaper than re-explaining your architecture in every new session.

Does it work with the tools I already use?

Yes. Muse connects to the majority of the coding agents people actually run — Claude Code, Cursor, Codex, Windsurf, Gemini CLI, OpenCode, Hermes, OpenClaw and the rest of the mainstream field. One command wires each of them; you keep working exactly as you do today.

What if it remembers something wrong?

Muse checks citations before storing them and re-checks them at recall. If the code a note points at has changed or disappeared, the note is withheld and you are told why, rather than served as if it were still true. Contradictions are marked conflicted instead of silently overwritten.

What happens to passwords and API keys?

They are refused. Every write is scanned for API keys, tokens, private keys and connection strings, and a suspected secret stops the write instead of being stored in a file you might later commit.

Can I bring my existing notes?

Yes. The importer reads other memory systems, and existing session transcripts can be turned into candidate notes. Your memory starts populated rather than empty.

Is it really free?

Yes. MIT-licensed, no paid tier, no telemetry. The whole engine — capture, ranking and recall — runs in-process on your machine, so there is no hosted component to charge for.

Stop re-explaining. Start remembering.

One command connects every assistant you use. The memory verifies itself from there.

Install now Read the source ↗