# Muse Memory

> Persistent, local-first memory for AI coding agents. Runs in-process on the user's
> machine: sub-2ms recall, write-time citation verification, the majority
> of coding agents wired by one command, 0 background daemons, MIT licensed.
>
> Version 3.0.2 · https://harshsinghmp.github.io/musememory/

Muse Memory gives an AI coding agent a memory that survives between sessions. Every
memory is checked against the real code before it is stored and re-checked before it
is served, so an agent is never handed a fact that has since become false.

## Install

```bash
npx musememory connect
```

No account, no API key, no configuration file, no background daemon. The store is
two plain directories: `.memory/` inside each project and `~/.memory/` globally.

## Pages

- [Home — the problem, how it works, architecture, the command surface, proof, FAQ](https://harshsinghmp.github.io/musememory/)
- [Docs — quickstart, CLI, MCP tools, hooks, trust gates](https://harshsinghmp.github.io/musememory/docs/)
- [Compare — 14-capability comparison against other memory approaches](https://harshsinghmp.github.io/musememory/compare/)

## Canonical documentation (authoritative)

- Repository README: https://github.com/harshsinghmp/musememory#readme
- Agent reference (exact CLI, MCP and file-layout contracts): https://github.com/harshsinghmp/musememory/blob/main/docs/agent-reference.md
- User guide: https://github.com/harshsinghmp/musememory/blob/main/docs/user-guide.md
- Core concepts: https://github.com/harshsinghmp/musememory/blob/main/docs/concepts.md
- Team setup: https://github.com/harshsinghmp/musememory/blob/main/docs/team-getting-started.md
- Full text of this site: https://harshsinghmp.github.io/musememory/llms-full.txt

## MCP tools an agent should know

| Tool | Purpose |
| --- | --- |
| `get_context` | Mandatory on the first turn of a session. Fused recall: constraints, ranked memories, negative lessons, code anchors, under one token budget. |
| `memory_capture` | Persist a decision, fix or constraint. Every write is secret-scanned and citation-verified. |
| `search` | Full-text search across the store. |
| `memory_current` | Read or write the active working constraints in CURRENT.md. |
| `muse_context` | Task-shaped fused context for a specific job. |
| `muse_why` | Explain why the code is the way it is, from ADRs and past fixes. |
| `memory_supersede` | Replace an outdated memory with a newer one. |

115 tools are registered in total, exposed through 7 task-focused
profiles (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`, `full`).

## Behaviour an agent must know

1. Call `get_context` on the first turn of any session.
2. Capture decisions, fixes and constraints as they happen — `memory_capture`.
3. Supersede rather than delete when knowledge changes — `memory_supersede`.
4. Every write is scanned for credentials and refused if one is present.
5. Every code citation is verified against the live filesystem at write time and
   re-checked at recall; drifted memories are withheld and reported, not served.

## Optional

- [npm](https://www.npmjs.com/package/musememory) · [GitHub](https://github.com/harshsinghmp/musememory)