MinniMemoryMCP docs

What it is#

A memory file is the instruction file your coding agent loads on every turn, such as CLAUDE.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.

On a full-size test memory (CLAUDE.md, MEMORY.md and 14 linked files), the part loaded every turn drops from 12,511 to 6,699 tokens. That counts what loads each turn.

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#

$ npx -y minnimemory init .

1. 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.
2. Read the preview: the map of what Claude Code loads, the findings, the files it would write, and a diff of each one.
3. 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.
4. Keep working as usual. After you edit a memory file by hand, run doctor, then apply again.
5. 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.

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

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

  MM003  "Current status" (lines 28-33) holds a status heading and  high
         status language in the always-loaded prefix
         at CLAUDE.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/ (CLAUDE.md -> CLAUDE.md.bak)
    write     .claude/OnDemandMemory/CLAUDE__history.md  +53 -0
    write     CLAUDE.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#

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.

What moves out is the dated, often-changing or task-specific sections. They are merged into <parent>__history.md and <parent>__detail.md.

<!-- 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/CLAUDE__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.

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.

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

your-repo/
  CLAUDE.md                       AlwaysOnMemory body + the OnDemandMemory list
  .claude/
    OnDemandMemory/
      CLAUDE__history.md          dated, volatile sections, merged
      CLAUDE__detail.md           task-specific sections, merged
  .minnimemory/                   backups and bookkeeping

~/.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

~/.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.

$ 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.

Words used here#

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, the drift notice and the load log, in one folder that Claude Code manages and updates.

/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.

With npx#

$ npx -y minnimemory install

• It registers the server for every project on this machine.
• It turns on the drift notice by default.
• It adds a load log: a hook that records which memory files Claude Code loads, on this machine only. init --from-log reads it.
• 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. npx -y minnimemory uninstall removes an npx registration.

The registration points at the copy that install ran from. Under npx that is the npx cache, and npm cache clean or a newer version can remove it. For a durable install, run npm i -g minnimemory once, then minnimemory install --force.

$ npm i -g minnimemory
$ minnimemory install --force

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.

The four commands#

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

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#

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.

$ npx -y minnimemory init [path]

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.

$ npx -y minnimemory doctor [path]

The rule set#

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

MM017, MM018 and MM019 are new in 1.2. MM020 and MM021 are new in 1.3 and run only with --policy. 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".

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

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

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

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 a CLAUDE.md or 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.

$ npx -y minnimemory undo [path]

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.

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 CLAUDE.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.

1. Edit a memory file by hand.
2. Run doctor. It shows what drifted and the re-apply plan.
3. 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.

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

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.

Run any command with --help for every flag, or see the package page on npm.

What gets generated#

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

your-repo/
  CLAUDE.md                       AlwaysOnMemory body + the fenced OnDemandMemory list
  .claude/
    OnDemandMemory/
      <parent>__history.md        dated, volatile sections, merged
      <parent>__detail.md         task-specific sections, merged
  .minnimemory/
    .gitignore                    keeps the backups out of git
    manifest.json                 token counts, hashes, triggers, provenance
    graph.json                    bookkeeping, committed with the manifest
    original/
      CLAUDE.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.

Two 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, and the load log that install turns on.

Security and privacy#

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

• 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.

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.

Version and licence#

These docs describe minnimemory 1.3.6. Get it from the package page on npm.

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.