# MinniMemoryMCP docs

> Source: https://minniai.com/minnimemorymcp/docs (canonical HTML page)

MinniMemoryMCP splits your agent’s memory into a small always-on part (AlwaysOnMemory) and files that load only when a task needs them.

minnimemory 1.5.0 · [Changelog](https://minniai.com/minnimemorymcp/changelog)

try it in a terminal, no install needed

```
$ npx -y minnimemory init .
```

**On this page**

## What it is

A memory file is the instruction file your coding agent loads on every turn, such as `AGENTS.md`. The agent re-reads all of it each time, and most of it is not needed for the task in front of it. An edit near the top also breaks prompt caching, so everything after the edit has to be processed again.

MinniMemoryMCP checks that file and splits it in two: a small always-on part that still loads every turn, and files the agent opens only when a task needs them.

- Nothing is reworded. Every line is kept.
- No model, no key and no network.
- Your originals are backed up, and `undo` restores them.
- The MCP server never writes your memory files. Its one write is `init`’s record of where Claude Code loads from.
- Nothing has to keep running. The result is plain Markdown your agent reads with its normal file tools.

### Before

AGENTS.md

all of it loads every turn
- Rules you always need
- Status and dated notes
- History
- Task-specific detail

apply

### After

AGENTS.md

AlwaysOnMemory, loads every turn
- Rules you always need
- The OnDemandMemory list

OnDemandMemory, opened only when needed AGENTS__history.md

- Status and dated notes
- History

AGENTS__detail.md

- Task-specific detail

Every line is kept, word for word.

- Loaded every turn
- Opened only when needed

One large memory file before, a small AlwaysOnMemory plus OnDemandMemory files after.

Sorted this way, the agent searches less: in our latest test it went looking in its memory 17 times instead of 89 over the same 87 answers.

Over whole Claude Code sessions on our test memory, the figure that matters: the same 30 questions, three full sessions a side, cost $0.47 a session before and $0.29 after on average at API rates, 37.7% less, with the answers held. Measured on MinniMemoryMCP 1.6.0, 15 November 2026. The runs and their method are on the [evidence page](https://minniai.com/evidence).

## Quick start

Run these commands in a terminal, or install the server and ask your agent in plain words (see In Claude Code below).

Try the whole loop in a few minutes. The first command writes nothing to your memory.

### What you need

- Node 18 or later.
- A memory file in the folder you run it in: `CLAUDE.md`, `.claude/CLAUDE.md`, `AGENTS.md`, `.claude/AGENTS.md`, `GEMINI.md` or `.cursorrules`. A folder of Markdown memory files or the project’s Claude Code memory folder also works.
- Claude Code, only if you want your agent to run the commands for you. The terminal commands work without it.

### The loop

terminal

```
$ npx -y minnimemory init .
```

- Open a terminal in your project folder and run `npx -y minnimemory init .`. It is always the first step. It reads your memory and changes none of it. It saves only a record of this folder in your Claude config folder.
- Read the preview: the map of what Claude Code loads, the findings, the files it would write, and a diff of each one.
- The preview ends with the exact `apply` command to run, with a plan hash in it. Copy that line and run it. Your originals are backed up first.
- Keep working as usual. After you edit a memory file by hand, run `doctor`, then `apply` again.
- To go back, run `npx -y minnimemory undo`. It restores your files as they were before the first `apply`.

`doctor` is for later. Before `init` has run for a project it refuses and says to run `init` first.

### Reading the preview

The real preview is longer. This is its shape, from `init` on the example file shipped in the package, shortened.

init, shortened

```
  memory map for /path/to/your/repo: every file Claude Code loads, by its own rules

  setup
    host file       AGENTS.md
    file to change  AGENTS.md
    state           not compiled

  MM003  "Current status" (lines 28-33) holds a status heading and  high
         status language in the always-loaded prefix
         at AGENTS.md:28-33
         -> move it to an OnDemandMemory file; editing it here invalidates
         the prompt cache every time

  ...more findings, then the saving and the verdict...

  operations:
    write     .minnimemory/.gitignore  +5 -0
    copy      1 file(s) -> .minnimemory/original/ (AGENTS.md -> AGENTS.md.bak)
    write     .claude/OnDemandMemory/AGENTS__history.md  +53 -0
    write     AGENTS.md  +6 -47
    write     .minnimemory/graph.json  +446 -0
    write     .minnimemory/manifest.json  +46 -0

  diff:
    ...the full diff of every file above...

  plan: a904645a74edea51
  dry run, nothing written. To write these files, run:
    npx -y minnimemory apply --plan a904645a74edea51 --budget 2000 .
```

- **The map** comes first. Its `setup` block names the file Claude Code starts from, the one file `apply` will rewrite, and whether it is already compiled.
- **A finding** has a rule id such as `MM003`, a severity (`low`, `med` or `high`) and a suggested fix. `doctor --rules` lists every rule.
- **Operations** are the files `apply` would write. Your original is copied to `.minnimemory/original/` before anything else changes. Each line ends with the lines added and removed.
- **The plan hash** pins what you saw. `apply --plan <hash>` refuses if anything changed since.
- **The last lines** are the command to run. Copy it as printed.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Clean. |
| `1` | Findings at or above `--fail-on`. |
| `2` | An error, such as no memory file found, `doctor` before `init`, or a refused `undo`. |

In CI, on a repo whose compiled memory is committed, `npx -y minnimemory doctor --ci --fail-on med` fails the build on memory bloat the way a lint error would.

## How it works

Your memory has two layers, and this is what each one holds.

- **AlwaysOnMemory** is small and loaded every turn. It holds nothing that changes often.
- **OnDemandMemory** is a set of files the agent opens only when the task matches their words.

1 Every turn

AlwaysOnMemory

your rules and the OnDemandMemory list

2 The agent reads the list

Task: why did the last deploy fail?

- AGENTS__history.md: **deploys**, status, error
- AGENTS__detail.md: database, migrations

3 It opens only what matches

AGENTS__history.md

opened

AGENTS__detail.md

stays closed

An opened file stays in the conversation for the rest of the session.

- Loaded every turn
- Opened only when needed

A turn loads AlwaysOnMemory. The agent opens an OnDemandMemory file only when the task matches it.

What moves out is the dated, often-changing or task-specific sections. They are merged into `<parent>__history.md` and `<parent>__detail.md`. A large task-specific part is split into several `<parent>__detail-<section>.md` pieces instead, each with its own list line, so reading one section does not load every module of the file.

the list left in your file

```
<!-- minnimemory:ondemand-list -->
# OnDemandMemory

AlwaysOnMemory ends here. Read one file below only when the task matches its words.
New memory files go in .claude/OnDemandMemory/.

- `.claude/OnDemandMemory/AGENTS__history.md`: test, src, error, deploys, status, services
<!-- /minnimemory:ondemand-list -->
```

This is a routing list, not a summary. Each line names a file and the words that should make the agent open it.

What the saving depends on

A file the agent opens becomes part of the conversation for the rest of the session. The saving is on the turns where it stays closed. Run `minnimemory bench` to see the best case, the worst case and the break-even point for your own memory.

### A host file or a memory folder

It works on two shapes, through one engine. A host file is `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `.cursorrules`, and it is trimmed in place. A memory folder is a main file such as `MEMORY.md` plus topic files, and it is sorted in place.

a host file, before

```
your-repo/
  AGENTS.md                    one large file, all loaded every turn
```

a host file, after apply

```
your-repo/
  AGENTS.md                    AlwaysOnMemory body + the OnDemandMemory list
  .claude/
    OnDemandMemory/
      AGENTS__history.md          dated, volatile sections, merged
      AGENTS__detail.md           task-specific sections, merged
  .minnimemory/                   backups and bookkeeping
```

a memory folder, before

```
~/.claude/CLAUDE.md                     loaded every turn
  @.../memory/feedback_a.md
~/.claude/projects/<project>/memory/
├── MEMORY.md                           main file, loaded every turn
├── feedback_a.md                       always loaded: rules + incident history + dated notes
└── project_x.md                        on demand, nobody imports it
```

a memory folder, after apply

```
~/.claude/CLAUDE.md                     same text; only the import path changed
  @.../memory/AlwaysOnMemory/feedback_a.md
~/.claude/projects/<project>/memory/
├── MEMORY.md                           same hook lines, link targets updated, list appended
├── AlwaysOnMemory/
│   └── feedback_a.md                   the rules only, same file name
├── OnDemandMemory/
│   ├── project_x.md                    moved, untouched
│   └── feedback_a__history.md          the dated notes routed out of feedback_a
└── .minnimemory/                       bookkeeping: manifest.json, original/, previous/
```

### Your Claude Code memory folder

Your Claude Code memory folder (`~/.claude/projects/<project>/memory`) is loaded with files outside it: your `~/.claude/CLAUDE.md` and anything it imports. The tool never searches for those files. It reads only the files it is told Claude Code loads, so it cannot guess wrong.

In Claude Code your agent tells it. In a terminal, give it Claude Code’s own load log, or name the files by hand.

terminal

```
$ npx -y minnimemory init ~/.claude/projects/<project>/memory --from-log
$ npx -y minnimemory init ~/.claude/projects/<project>/memory --loaded ~/.claude/CLAUDE.md
```

`init` checks each path, works out from their lines which files load the folder, and saves the set for `apply`, `doctor` and `undo`. The report lists each linked file and how it links, and any place the report and the lines disagree.

A memory folder needs a report

`apply` on a memory folder refuses until something was reported, because moving a file that an unseen outside file imports would break that import. If nothing outside loads the folder, pass `--only-this-folder`.

### Words used here

| Word | Meaning |
| --- | --- |
| Memory file | The instruction file your agent loads every turn, such as `AGENTS.md`. |
| AlwaysOnMemory | The small always-on part that still loads every turn. |
| OnDemandMemory | Files the agent opens only when a task matches their words. |
| Compile | What `apply` does: split the memory into those two layers. |
| Routed | Moved out of the always-on part into an OnDemandMemory file. |
| Drift | A memory file changed since the last `apply`. |
| Plan hash | A short code that pins the exact change a preview showed. |
| Host file | A single memory file in a project root, such as `AGENTS.md`. |
| Memory folder | A main file such as `MEMORY.md` plus topic files, such as Claude Code’s own memory folder. |
| Load log | A record of the memory files Claude Code loaded, kept on your machine by a hook that `install` adds. |
| Usage log | A count of which OnDemandMemory files your sessions open, kept on your machine by a hook that `install` adds. `doctor` reads it. |
| Memory hook | The prompt hook that places the one OnDemandMemory section a prompt needs, so the agent does not open the file. |
| MCP | Model Context Protocol, the standard way AI tools connect to add-ons. |

## Install in Claude Code

Two routes connect the server to Claude Code, so your agent can call the four commands. Pick one per machine.

### As a Claude Code plugin

Inside a Claude Code session, one command installs the plugin from our marketplace: the server and its hooks (the memory hook, the drift notice, the load log and the usage log), in one folder that Claude Code manages and updates.

in Claude Code

```
/plugin install minnimemory --marketplace MinniAI-com/minnimemory-plugin
```

Or from your shell: `claude plugin marketplace add MinniAI-com/minnimemory-plugin`, then `claude plugin install minnimemory@minniai`. The plugin loads in Claude Code, and in Cowork when the session runs on your computer; claude.ai chat ignores it. Source and support: [github.com/MinniAI-com/minnimemory-plugin](https://github.com/MinniAI-com/minnimemory-plugin).

### With npm

terminal

```
$ npm i -g minnimemory
$ minnimemory install
```

- It registers the server for every project on this machine.
- It turns on the memory hook and the drift notice by default (see The hooks below).
- It adds a load log: a hook that records which memory files Claude Code loads, on this machine only. `init --from-log` reads it. And a usage log: a hook that notes which OnDemandMemory files your sessions open, file names and counts only, so `doctor` can tell you when one of them belongs always-on.
- It prints the next step. Restart Claude Code.
- It is safe to run again. Run it again after you upgrade the package, so the server and the hooks point at the new copy.
- If you installed the plugin, skip this route: the server would be registered twice. `minnimemory uninstall` removes the registration.

| You want | Run |
| --- | --- |
| This repo only, not every project | `minnimemory install --scope project` |
| See the command without running it | `minnimemory install --dry-run` |
| Re-register over an existing entry | `minnimemory install --force` |
| Skip every hook | `minnimemory install --no-hook` |
| Precise reads, opt in (see below) | `minnimemory install --precise-reads` |
| Remove the registration and the notice | `minnimemory uninstall` |

The registration points at the copy that `install` ran from, so that copy has to stay. Run as `npx -y minnimemory install`, it would be the npx cache, which npm clears on its own. So from the npx cache `install` writes nothing and prints the two lines above. The other commands (`init`, `doctor`, `apply`, `undo`, `uninstall`) still run with `npx -y minnimemory`.

### The hooks

`install` registers four small hooks in Claude Code. They run on your machine, store no prompt text, and `install --no-hook` skips them all.

- **The memory hook** runs before each prompt and places the one short OnDemandMemory section the prompt clearly needs, once per session, so the agent answers in one call instead of opening files. It places a section only on a strong match; a weaker match on a rare word that names a section prints a one-line pointer instead, and anything weaker prints nothing. It stays quiet on short follow-ups about the work in progress, when the always-on memory already covers the question, and when the section is already in the conversation; after Claude Code compacts the conversation it can place the section again. The first section placed from a file ends with a line naming that file’s other sections, so the agent knows the file holds more.
- **The drift notice** runs before each prompt and prints one line when a memory file changed since the last `apply`. See The drift notice.
- **The load log** records which memory files Claude Code loaded for each project, machine-local. `init --from-log` reads it.
- **The usage log** runs after a file Read and notes which OnDemandMemory files a session opened, file names and counts only. Once ten sessions are logged, `doctor` flags a file nearly every session reads (`MM024`), because such a file is cheaper always-on. Advice only; nothing moves.

Opt in with `install --precise-reads`: when the agent reads a whole memory file that is large, the Read hook hands back only the sections the current prompt needs and names the rest by line range, so the agent can read one of them if it has to. Off by default.

A session started in a subfolder of a compiled project still gets its memory: `init` records which files were loaded there, and the hooks place from the compiled folders of those files. Started somewhere `init` never ran, the drift notice asks once per session for `init` to run there.

### The drift notice

The notice tells your agent when a memory file has changed since the last `apply`, so you never have to remember to run `doctor`. It checks the project and its Claude Code memory folder. It prints one short line, only when something changed, and only once for each distinct change. Editing a routed OnDemandMemory file, such as a saved memory, does not raise a notice. `doctor` still lists it.

Claude Code and Codex

Claude Code and Codex are the supported hosts. For Codex, see Install in Codex. Cursor, Windsurf, Claude Desktop and SDK clients are not supported. `install --host cursor`, `windsurf` or `json` prints a config snippet to paste, but the hooks and the load model are not built for them, and nothing there has been tested end to end.

## Install in Codex

Codex loads one chain of `AGENTS.md` files every turn: your user file (`$CODEX_HOME/AGENTS.md`), then one file per folder from the repo root down to your working directory. The project files share `project_doc_max_bytes` (32 KiB by default): the file that crosses it is cut there. Nothing loads on demand, so a long `AGENTS.md` is paid in full on every turn. The same four commands trim it the same way.

terminal

```
$ npm i -g minnimemory
$ minnimemory install --host codex
```

- It runs `codex mcp add minnimemory` for you and adds the two minnimemory hooks to `~/.codex/hooks.json` (`--scope project` writes `<repo>/.codex/hooks.json`). It is safe to run again.
- Without the `codex` command on your machine, it prints the `[mcp_servers.minnimemory]` block to paste into `~/.codex/config.toml`.
- Open Codex and run `/hooks` once to trust the two minnimemory hooks. Do not skip this: Codex skips a hook it does not trust, and without the memory hook the routed sections never reach a turn. Until the hook has run, `init` says so.
- Then ask Codex to run `init`. In a terminal: `npx -y minnimemory init . --host codex`.

In `codex exec` there is no one to approve a tool call, so Codex refuses MCP calls that need approval. The four commands only read, so you can let them run without asking:

~/.codex/config.toml

```
[mcp_servers.minnimemory]
default_tools_approval_mode = "approve"
```

### What is different on Codex

- **Small files stay whole.** A file Codex already loads whole, under the cap, is left as it is: `init` says so, and `apply` needs `--force` to split it.
- **The map shows the chain:** each file, its size, whether it loads, and the cap in force.
- **`doctor` adds two checks:** `MM022` (a file past the cap) and `MM023` (an `AGENTS.override.md` hiding an `AGENTS.md`).
- **One `apply` covers the session.** Started in a subfolder, it writes every file the session loads, each with its own backups, and one `undo` there puts them all back.
- **No project file?** `init` works on your user `AGENTS.md`, which Codex loads in every project, and says so.
- **Slash commands are Claude Code only.** Codex does not show MCP prompts, so ask for the command by name.
- The discovery record lives under `$CODEX_HOME/minnimemory/`. Codex’s own memories are listed with their size and never compiled.

## The four commands

The same four commands work in the terminal and in Claude Code. The only difference is who writes.

| Command | What it does | Does it write? |
| --- | --- | --- |
| `init` | Always first. Takes where Claude Code loads from, checks and saves it, then maps every file Claude Code loads here and previews every file `apply` would write. | Only its record of those locations, in your Claude config folder. Never a memory file. |
| `doctor` | After `init`, never first. Checks your memory, shows what drifted since the last `apply`, and previews the re-apply. | No. |
| `apply` | Writes what `init` or `doctor` showed, originals backed up first. | In the terminal, yes. Over MCP, no: it returns the command to run and the list of operations. |
| `undo` | Puts your original memory files back and removes `.minnimemory/`. | In the terminal, yes. Over MCP, no: it returns the command and the operations. |

The order is always the same: `init`, then `apply`. Later, after you edit a memory file by hand, `doctor`, then `apply` again. `undo` works at any time.

init

then doctor on later runs

read-only checks and previews, writes no memory file

apply

writes originals backed up first

You edit your memory

by hand, as before

run doctor: it shows the drift

run doctor: it shows the drift

undo

writes any time: puts your originals back and removes .minnimemory/

- Read-only
- A write

The loop: init, apply, edit, doctor, apply again. Undo works at any point.

### init

`init` is the first command on any folder. It takes where Claude Code loads from, checks every path, and saves the set in your Claude config folder (`~/.claude/minnimemory/discovery.json`). `apply`, `doctor`, `undo` and the drift notice read it, so nothing is asked twice. That record is the one thing `init` writes. It never writes a memory file.

Then it prints a map of every file Claude Code loads here, tagged with when it loads, whose it is and its tokens, followed by the findings, the plan and a diff of every file `apply` would write.

The map opens with a `setup` block: the host file Claude Code starts from, the file it points at when it is only a pointer (a `CLAUDE.md` that holds `@AGENTS.md`), the one file `apply` will rewrite, and whether that file is already compiled. An `AGENTS.md` that Claude Code does not load is named at the end with the reason, and counts toward no total.

A project root reads only itself: no `CLAUDE.md` from a parent folder and no user files. A file outside the folder is read only when it is reported as loaded.

terminal

```
$ npx -y minnimemory init [path]
```

| Flag | Effect |
| --- | --- |
| `--from-log` | Take the loaded files from Claude Code’s own load log for this folder. |
| `--loaded <path>` | A file Claude Code loads this session. Repeatable. The only way a file outside the folder is read. |
| `--memory-dir <path>` | The memory folder Claude Code names. Also the folder to use. |
| `--map` | Print only the map of loaded files. |
| `--diff summary` | The plan and the list of operations, without the file diffs. |
| `--budget <n>` | The token budget AlwaysOnMemory must fit. The default is three fifths of the file, and never under 2000. |
| `--force` | Preview the re-apply plan on a compiled workspace with no drift. |
| `--profile <name>` | How much guidance to embed in the always-on part: `auto` (the default, the same as `none` today), `none`, `routing`, `output` (the answer-length rules alone) or `full`. |
| `--allow-secrets` | Preview as if a credential-shaped source were allowed through. |

`init` warns when the folder it reads is another project’s Claude Code memory folder. The map also flags an instruction file Claude Code cuts short: a subfolder `CLAUDE.md` or path-scoped rule too long for Claude Code to load whole, and a file too large to load at all.

### doctor

Use `doctor` after `init`, whenever you want to know what changed. It checks the memory, shows what drifted since the last `apply`, and prints the command to run. It never modifies anything, and works on a repo, a memory folder or a single file.

Before `init` has run for a project, `doctor` refuses and says to run `init` first. With no path, it uses the folder `init` saved.

It reads only the folder you name and the folders below it. Your user-level `~/.claude/CLAUDE.md` is counted only when it was reported to `init` as loading a memory folder.

terminal

```
$ npx -y minnimemory doctor [path]
```

| Flag | Effect |
| --- | --- |
| `--json` | Machine-readable output. |
| `--ci` | Short output, no colour. |
| `--fail-on <sev>` | Exit 1 at this severity or above: `low`, `med` or `high` (default `high`). |
| `--budget <n>` | The token budget for the always-on part. The default is the budget the workspace was compiled at. |
| `--policy <file>` | Check against your team's rule pack (`policy.json`): lines every memory must hold (`MM020`) and text none may hold (`MM021`). Plain text, no regex. |
| `--only <ids>` | Run only these rules, comma separated. |
| `--ignore <ids>` | Skip these rules, comma separated. |
| `--force` | On a compiled workspace with no drift, show the re-apply plan anyway. |
| `--rules` | List the rule set and exit. |

### The rule set

Every finding carries one of these rule ids. `doctor --rules` prints the same list.

| Rule | Severity | What it flags |
| --- | --- | --- |
| `MM001` | `high` | Always-loaded memory exceeds the budget of a policy or of a compiled workspace. A `--budget` you pass to `init` or `doctor` is the plan’s first line instead: how far over it is and where the plan brings it. |
| `MM002` | `med` | Content derivable from the repo itself. |
| `MM003` | `high` | Volatile content in the always-loaded prefix. |
| `MM004` | `low` | OnDemandMemory file unreachable from any OnDemandMemory list. |
| `MM005` | `med` | Duplicated content across memory files. |
| `MM006` | `low` | OnDemandMemory list line exceeds the character cap. |
| `MM007` | `med` | Flat memory directory with no OnDemandMemory list. |
| `MM008` | `high` | Credential-shaped string in a memory file. |
| `MM009` | `low` | Flat section over the granularity threshold. |
| `MM010` | `med` | Compiled workspace has drifted since apply. |
| `MM014` | `med` | The anchor list costs more than it saves. |
| `MM015` | `med` | A duplicate file that nothing links to. |
| `MM017` | `high` | MEMORY.md lines past what Claude Code loads. |
| `MM018` | `med` | OnDemandMemory list links a file that does not exist. |
| `MM019` | `med` | OnDemandMemory list line describes another file better than the one it links. |
| `MM020` | `med` | A line your team's rule pack requires is not in the always-loaded memory. |
| `MM021` | `med` | A memory file holds text your team's rule pack bans. |
| `MM024` | `low` | An OnDemandMemory file that nearly every logged session reads. Cheaper always-on. Advice only. |

`MM017`, `MM018` and `MM019` are new in 1.2. `MM020` and `MM021` are new in 1.3 and run only with `--policy`. `MM024` is new in 1.4.2 and needs the usage log, with ten sessions in it. A rule only flags. Your words are not changed.

### apply

Use `apply` once the preview looks right. It does the right thing for what it finds: a fresh compile, a re-apply that keeps every hand edit, or "nothing to apply".

terminal

```
$ npx -y minnimemory apply --plan <hash> [path]
```

You do not have to type this. `init` and `doctor` print the exact line to run.

| Flag | Effect |
| --- | --- |
| `--plan <hash>` | Recomputes the plan from disk and refuses if it no longer matches the hash `init` or `doctor` showed, so what you saw is what gets written. |
| (no `--plan`) | Plain `apply` works too. It skips that check and writes the current plan. |
| `--force` | Write a compile that would not shrink the always-on part. |
| `--allow-secrets` | Write even when the source holds a credential-shaped string. |
| `--only-this-folder` | Apply to a memory folder with nothing reported, when nothing outside loads it. |
| `--budget <n>` | The token budget to compile at. A re-apply keeps the budget the workspace was applied with. |

`apply` follows a pointer. If `CLAUDE.md` is only `@AGENTS.md`, it compiles `AGENTS.md` and leaves the pointer alone.

Rules stay in AlwaysOnMemory. A section whose heading or first line reads as a hard rule (HARD STOP, never, always or must), or that holds `<!-- minnimemory:keep -->`, is placed in the always-on part before size decides. One that still does not fit is named in the plan as a rule.

`apply` refuses, and writes nothing, in these cases.

- A memory folder that nothing was reported for. See Your Claude Code memory folder.
- A file changed since the preview, when you passed `--plan`.
- Sorting a folder would move a file that an `AGENTS.md` names by path. It names the lines.
- On Windows or macOS, a folder with a topic file named `memory.md` and no `MEMORY.md`. Rename the file first.
- A source that holds a credential-shaped string, or that is not valid UTF-8.
- A compile that would not shrink the always-on part, unless you pass `--force`.

### undo

Use `undo` to go back. It restores every original from `.minnimemory/original/`, exactly as it was before the first `apply`, and removes `.minnimemory/`. On a memory folder it also moves every sorted file back and removes `AlwaysOnMemory/` and `OnDemandMemory/` once they are empty.

terminal

```
$ npx -y minnimemory undo [path]
```

| Flag | Effect |
| --- | --- |
| `--force` | Restore anyway when a compiled file was edited since the last `apply`, or the workspace was re-applied since the first. `undo` first copies the files it discards to `~/.claude/minnimemory/undo-backups/` and says where. |

After a re-apply, or after you edit a compiled file, `undo` refuses without `--force`. It goes back to before the first `apply`, so every change made to those files since would be discarded. It names the files and exits with code 2.

A memory folder and a project are separate targets. Each has its own `undo`.

### In Claude Code

After the install, open Claude Code in your project and say what you want in plain words.

| You say | The agent calls | You see |
| --- | --- | --- |
| "clean up my memory" | `init` | The files that load your memory and how, then the findings and a summary of the plan: one line per file (action, path, lines added and removed). The locations are saved, so nothing is asked again. |
| "apply it" | `apply` | The `apply --plan <hash>` command to run (through `npx -y minnimemory`, or the plugin’s own `server/cli.mjs` when you installed the plugin), and the operations it performs. Your originals are the first files written, to `.minnimemory/original/`. |
| "check my memory" (a week later) | `doctor` | The findings, what drifted since the last `apply`, and the re-apply plan, or "nothing to re-apply". |
| "undo the memory compile" | `undo` | The command that restores the originals and removes `.minnimemory/`, and the operations it performs. |

The four commands are also slash commands in Claude Code: `/mcp__minnimemory__init`, `/mcp__minnimemory__doctor`, `/mcp__minnimemory__apply` and `/mcp__minnimemory__undo`. Each one runs the same call the plain-words request does.

Your agent passes `init` its memory folder and every file Claude Code shows as loaded. The server never searches for them.

"Clean up my memory" works on your memory folder. The project’s `AGENTS.md` is a separate target. The reply names it, and gives its own command when it also has changes. Ask for both if you want both.

Every write goes through your own approval prompt. The server itself only reads your memory, and `apply` and `undo` return the command and the list of operations, not the content of your files.

## Editing, drift and re-apply

After `apply` you keep editing your memory the way you always have, and the tool catches up when you ask.

- A file with `__` in its name is the tool’s, such as `<parent>__history.md`. It is a merge of the sections routed out of one parent.
- Every other file is yours: the AlwaysOnMemory files, the plain OnDemandMemory topic files and `MEMORY.md`. Edit them as before.

Drift is a memory file that changed since the last `apply`. You find out from the drift notice in Claude Code, or by running `doctor`. Editing a routed OnDemandMemory file raises no notice, but `doctor` still lists it and `undo` still checks it before it discards anything.

`apply` on a workspace with drift keeps every hand edit. A section you added may be moved to an OnDemandMemory file if it is dated or task-specific. It is never dropped.

- Edit a memory file by hand.
- Run `doctor`. It shows what drifted and the re-apply plan.
- Run `apply --plan <hash>` with the new hash.

Your originals stay in `.minnimemory/original/`. A re-apply backs up what it replaces under `.minnimemory/previous/`. `undo` always restores the originals.

## Using it in a team

One person compiles the memory, and the rest of the team gets the result through git.

- Run `init`, then `apply`, on a branch.
- Commit the trimmed memory file, the new files under `.claude/OnDemandMemory/`, and `.minnimemory/manifest.json` and `.minnimemory/graph.json`.
- Open a pull request. The change is plain Markdown, so it reviews like any other diff.
- Teammates pull. Their agents read the new files with no extra setup.
- Anyone who wants to run the commands from Claude Code runs `npm i -g minnimemory`, then `minnimemory install`, once.
- Optional: add `npx -y minnimemory doctor --ci --fail-on med` to CI. It runs on the committed compile with no `init`. See Exit codes.

Undo is local

The backups in `.minnimemory/original/` are kept out of git, so they exist only on the machine that ran `apply`. From any other machine, go back by reverting the commit.

Nothing to run in production

The tool is a converter. After `apply`, nothing has to keep running, and the result works without the package installed.

It is free to use, including at work. See Version and licence and Security and privacy.

## Other commands

These sit around the four main commands. Most people only need `install`.

| Command | What it does |
| --- | --- |
| `mcp` | Starts the MCP server. The default profile is the four read-only commands. A `full` profile for maintainers also exists. |
| `install` | Registers the server with Claude Code and turns on the hooks: the memory hook, the drift notice, the load log and the usage log. |
| `uninstall` | Takes out what `install` added and lists each folder still compiled with its `undo` command. Your memory stays as it is. |
| `recall` | Ranks the OnDemandMemory sections of a compiled workspace against a query. Changes nothing. |
| `hook` | The memory hook: a Claude Code prompt hook that places the one OnDemandMemory section a prompt clearly needs, a one-line pointer on a weaker match, or nothing. It skips files Claude Code already loads. `install` registers it for you. See The hooks . |
| `drift` | A Claude Code prompt hook that prints a one-line notice when memory changed since the last `apply`. `install` registers it for you. |
| `loaded` | A Claude Code hook that records which memory files Claude Code loaded. `install` registers it for you, and `init --from-log` reads it. |
| `read` | The usage log: a Claude Code hook that runs after a file Read and notes which OnDemandMemory files a session opens, names and counts only. `install` registers it for you, and `doctor` reads it for `MM024`. With `--precise-reads` it also trims a whole-file Read of a large memory file to the sections the prompt needs. |
| `bench` | Shows what the compiled shape costs over a whole session: the best case, the worst case and the break-even point. |

Run any command with `--help` for every flag, or see the [package page on npm](https://www.npmjs.com/package/minnimemory).

## What gets generated

These are the files `apply` creates in a project root, and which ones to commit.

a project root

```
your-repo/
  AGENTS.md                    AlwaysOnMemory body + the fenced OnDemandMemory list
  .claude/
    OnDemandMemory/
      <parent>__history.md        dated, volatile sections, merged
      <parent>__detail.md         task-specific sections, merged
      <parent>__detail-<section>.md  the pieces of a large task-specific part
  .minnimemory/
    .gitignore                    keeps the backups out of git
    manifest.json                 token counts, hashes, triggers, provenance
    graph.json                    bookkeeping, committed with the manifest
    original/
      AGENTS.md.bak            verbatim copy of what was there before
```

`manifest.json` records what came from where: per-file token counts, content hashes for drift detection, the keyword triggers, and the source line range of each routed piece.

- Commit `manifest.json` and `graph.json`, so a teammate’s `doctor` sees the same drift.
- Keep the backups local. `.minnimemory/.gitignore` already keeps `original/`, `previous/`, the drift stamp and `hosts.json` (the reported set for a memory folder) out of git.

Three things live outside your project, in your Claude config folder, and stay on your machine: `~/.claude/minnimemory/discovery.json`, which is `init`’s record of where Claude Code loads from, the load log and the usage log that `install` turns on.

## Security and privacy

Your files stay on your machine, and the server cannot change your memory files.

Your agent

MCP server

read-only

Your memory files

1 Your agent calls apply

2 The server reads your files

3 It returns the command to run and the list of operations

4 You approve the command in your own prompt

you approve

5 The command writes the files, originals backed up first

In the terminal there is no server: you run the command and it writes directly.

- Read-only
- A write

In the terminal the command writes. In Claude Code the server only reads, and your own approval prompt gates every write.

- Every command reads only the folder you name and the folders below it. A file outside it is read only when it is reported as loaded. Nothing is searched for.
- The MCP server’s one write is `init`’s record of where Claude Code loads from, in your Claude config folder. It never writes a memory file.
- `doctor`, `init`, `apply`, `undo` and `mcp` make no network calls and never run a subprocess.
- `apply` and `undo` refuse a symlinked source and refuse to write or delete through a symlink, so a cloned repo cannot point a memory file at a file outside the workspace.
- `apply` refuses to write when the source holds a credential-shaped string, unless you pass `--allow-secrets`.
- `apply` refuses a source that is not valid UTF-8, and keeps a CRLF file’s line endings.
- `undo` refuses, unless you pass `--force`, when edits would be lost. It says what it would discard, and a forced `undo` copies those files to `~/.claude/minnimemory/undo-backups/` first.
- The MCP server only serves files that resolve inside the OnDemandMemory folder, whatever the manifest says.
- Every reply from the server marks memory text as data, so a line in a memory file cannot pass as an instruction to your agent.

Read `doctor --json` before you share it

`doctor --json` includes your absolute workspace path and the headings of your auto-memory files. Read it before pasting it somewhere public.

## What it does not do

Knowing the limits tells you when this is the wrong tool.

- It is not a conversation compressor. It touches only your memory files, never the conversation.
- It is not a search tool over your code. It compiles the memory file you already wrote, nothing else.
- It is not a proxy. No model is called by any of the four commands.
- It is not a summariser. Every source line lands somewhere word for word, with a stated reason.
- It does not compile a routing list. `apply` refuses `MEMORY.md` as a single file, or any file that is mostly links to topic files beside it. Point it at the folder instead: the folder compile leaves the main file’s own lines alone and appends its list.

## Questions

Short answers to the questions people ask first.

### Does it send my code or memory files anywhere?

No. No command makes a network call. There is no telemetry and no API key.

### Will it destroy my AGENTS.md?

No. `init` and `doctor` only preview. `apply` copies your original to `.minnimemory/original/` before it changes anything, and `undo` restores it byte for byte.

### Does this fight with prompt caching?

The opposite. Moving changing content out of the always-on part is what keeps the cache valid across sessions.

### Does it work with Cursor or Codex?

Codex: yes. See Install in Codex. Cursor is not supported yet; `install --host cursor` only prints a config snippet to paste.

### Do I need to keep it installed after apply?

No. The result is plain Markdown: your agent reads the list in your memory file and opens the files with its normal tools. Keep it installed if you want the drift notice and `doctor`.

### Can we use it at work?

Yes. It is free to use, including at work. See Version and licence.

### It says no memory files found.

Run it in a folder that has a memory file, or pass a path: `init path/to/folder`. What you need lists the file names it looks for.

### `doctor` says to run init first.

`init` is always the first step on a project. Run `npx -y minnimemory init .`, then `apply`. `doctor` is for later runs. See init.

### `apply` refuses my memory folder.

Nothing was reported about what loads it. Run `init` on the folder with `--from-log` or `--loaded`, or pass `--only-this-folder` if nothing outside loads it. See Your Claude Code memory folder.

### I am upgrading. What changes?

Run `install` again (`minnimemory install --force`) so the server and the hooks point at the new copy; a hook added in a newer version, such as the usage log, is registered then. A workspace an older version compiled keeps working. On anything new, start with `init`.

### `apply` says the plan on disk no longer matches. What now?

A file changed after the preview, so the hash is out of date. Run `doctor` again, read the new preview, and use the new hash.

### `undo` refuses. Why?

A compiled file was edited since the last `apply`, or the workspace was re-applied since the first. `undo` restores the originals from before the first `apply`, so it names what would be lost. Pass `--force` if you accept that: it copies the current files to `~/.claude/minnimemory/undo-backups/` first. See undo.

### `doctor` says there is nothing to apply.

The workspace is already compiled and no file has drifted since the last `apply`. To see the re-apply plan anyway, run `doctor --force`.

### It says to run undo, then apply. Why?

The workspace was compiled by an older layout of the tool. Run `undo` to get your originals back, then `apply` to compile again.

### `apply` refuses because of a credential-shaped string.

A source file holds something that looks like a key. Remove it from the memory file. If it is a false alarm, pass `--allow-secrets`. See Security and privacy.

## Version and licence

These docs describe `minnimemory` 1.5.0. Get it from the [package page on npm](https://www.npmjs.com/package/minnimemory).

The package is proprietary and free to use. You may install and run it unmodified for your own use, including at work, but you may not redistribute, modify or reverse engineer it. The files it reads and writes on your machine stay yours. The full terms are in the `LICENSE` file shipped with the package.

---

Index for agents: https://minniai.com/llms.txt. Doing a task: https://minniai.com/agents.md
