MIMRY

Local repo memory for coding agents.
Ranked files, context packs, a code relationship graph, and feedback-tuned search, built from your own codebase.

Website · Install · Quickstart · For AI agents · MCP setup · Commands · Development

What is MIMRY?

MIMRY is a local command-line tool and MCP server that gives AI coding agents a memory of a code repository. It indexes a repo once, keeps the index fresh incrementally, and answers "which files matter for this task?" with a ranked, evidence-backed list and a written context pack.

• Who it is for: anyone using an AI coding agent (Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor-style tools, and others) on a real codebase.
• The problem it solves: agents start every task cold. They grep blindly, reread the same files, miss the file that actually matters, and burn tokens and time doing it.
• What it does instead: one command, mimry preflight "<task>", returns the files to read first, how they connect, what to verify with, and a context pack the agent reads before touching code.
• How it works: it parses source files into symbols and a relationship graph (imports, calls, definitions, inheritance, references), combines that with full-text and local semantic search, and learns from feedback about which files agents actually used.
• Where it runs: entirely on your machine. No code is uploaded, there are no remote embeddings, and there is no telemetry.
• What it is not: it is not a source of truth, a code generator, or an LLM. It narrows where to look; source files, tests, and build output remain the final truth.

Install

MIMRY is a Python package on PyPI and needs Python 3.11 or newer. It works on Windows, Linux, and macOS.

uv tool install mimry

pipx install mimry and pip install mimry also work. The install provides two commands: mimry (the CLI) and mimry-mcp (the MCP server for agents).

Check it:

mimry --help

Upgrade later with uv tool upgrade mimry.

Quickstart

Run these inside the project you want an agent to work on:

cd /path/to/your/project
mimry init
mimry index
mimry preflight "fix the login redirect bug"

preflight answers like this:

✓ Context ready for "fix the login redirect bug"
  Index is up to date (3,105 files, indexed just now)
  Context pack: .mimry/mimry-out/context/latest.md

Start with
   1  src/auth/session.py
      name matches · path matches
   2  src/app/login/page.tsx
      name matches
   3  tests/test_auth.py
      path matches

Next: read .mimry/mimry-out/context/latest.md before opening files.

preflight also sets MIMRY up and builds the index on first use, so in practice it is the only command an agent needs to start a task.

For AI agents

This section is written for an AI coding agent working in a repository where MIMRY is installed.

When to use MIMRY

Use MIMRY before broad search. Run it first whenever you need to find where something lives, what a task touches, or how two parts of the code connect. Fall back to grep, rg, or reading files only to verify MIMRY's answer or when it cannot answer.

The workflow

1. Start the task: mimry preflight "<task in plain words>".
2. Read the context pack: .mimry/mimry-out/context/latest.md. It lists ranked files with reasons, key symbols, relationships, risky paths, and verification commands.
3. Navigate with focused queries instead of scanning the tree: mimry find "<query>", mimry symbol <name>, mimry related "<query>", mimry explain "<task>", mimry path <a> <b>, mimry why <file> --query "<task>".
4. Verify against the source. MIMRY output is navigation, not proof. Open the files, run the tests, and trust the build output over any ranking.
5. Record what helped: mimry feedback --query "<task>" --opened <files> --changed <files> --verification "<command and result>" --outcome passed. Future searches for similar tasks rank those files higher.

Rules

• If MIMRY says the index is out of date, run mimry reindex (fast: it only re-reads changed files).
• Treat .mimry/, caches, and generated files as support artifacts, never as the place to fix a bug.
• Never paste secret values into context or reports; MIMRY skips secret-looking files and redacts feedback.
• Output is plain ASCII when piped (OK, !, x marks), and exit codes are meaningful: 0 ok, 1 not set up, 2 stale or an error. mimry route "<task>" --json returns structured data.

Connect MIMRY to your agent

Agents can call MIMRY directly as an MCP server (stdio transport, command mimry-mcp).

Claude Code:

claude mcp add --scope user mimry -- mimry-mcp

Codex:

codex mcp add mimry -- mimry-mcp

Any other MCP client:

{
  "mcpServers": {
    "mimry": { "command": "mimry-mcp" }
  }
}

Without installing anything first, uvx mimry mcp runs the same server straight from PyPI ("command": "uvx", "args": ["mimry", "mcp"]). MIMRY is listed in the official MCP Registry as io.github.jbacalso24/mimry.

The server works on its current directory by default, and every tool accepts a root argument for another repo.

Teach your agent to use it

MIMRY can install a skill (instruction bundle) that teaches an agent the workflow above:

mimry install --project --platform claude-code --always-on --hooks

• --project installs into this repo only; omit it to install for every project.
• --always-on adds a short rules block to the agent's always-read file, such as AGENTS.md.
• --hooks adds a hook that nudges the agent to use MIMRY before broad searches.

Supported platforms: claude-code, codex, opencode, kilo, aider, copilot, claw, droid, trae, trae-cn, hermes, kiro, gemini, agents, amp, devin, antigravity, kimi, pi, codebuddy. Run mimry install --list-platforms for aliases, mimry install --project --platform <name> --status to check an install, and mimry uninstall --project --platform <name> --always-on --hooks to remove it.

Why MIMRY?

• Agents find the right file first. On MIMRY's frozen retrieval benchmark, 94% of the files a task needs appear in its top 5 results (recall@5 0.94, nDCG@5 0.70).
• It stays fast on large repos. Like git, it trusts unchanged file metadata, so a reindex with no changes takes about three seconds on a 3,000-file repo, and a real reindex re-parses only what changed.
• Answers carry evidence. Every result says why it ranked, and mimry why and mimry path show the actual relationships behind it. Unresolvable imports are dropped rather than guessed.
• It learns from use. Feedback about files agents opened, changed, missed, or ignored becomes an explainable ranking signal.
• It is private by default. Everything stays local, semantic search uses a deterministic local method (local-hash-v1), and credential files are skipped.
• Small outputs save tokens. Results are compact summaries and relative paths, never full source dumps.

Commands

Every command answers the same way: one line that says what happened, a few indented details, and a next step only when something needs doing. Add --verbose (-v) to any command for paths, scores, and raw ranking reasons.

Use mimry --root /path/to/repo <command> to target another repo.

Keeping an index current:

$ mimry status
! my-app is out of date - 1 file changed, 1 new since the last index
    changed  src/auth/session.py
    new      src/auth/magic_link.py
  Indexed 5 minutes ago · at commit d7bf046
  3,105 files · 6,859 symbols · 10,749 links
  Run `mimry reindex` to update it.

$ mimry reindex
✓ Updated the index for my-app in 2.2s
  1 file changed, 1 added
    changed  src/auth/session.py
    added    src/auth/magic_link.py
  3,106 files · 6,871 symbols · 10,762 links

Colour is used only on an interactive terminal, and NO_COLOR=1 turns it off. Piped and captured output always uses plain ASCII marks, so scripts and agents see the same text on every platform.

What it builds

project-root/
├─ .mimry/                  # local settings, gitignored
│  └─ mimry-out/            # generated output for agents and humans
│     ├─ context/latest.md  # latest context pack
│     └─ graph/             # relationship graph artifacts
└─ source files...

The index itself lives in your user cache directory, outside the repo. It is a generated artifact, not a source of truth.

A context pack contains the query and index freshness, ranked files with reasons, symbol hints, relationships, a suggested reading order, likely edit surfaces versus support files, risk notes for generated or sensitive paths, verification commands from the project's manifests and docs, and a final-report checklist. It uses relative paths and never includes full source or secret values. See docs/context-packs.md for the contract.

Graph engine

MIMRY builds its own relationship graph in src/mimry/core/. Indexing parses each file once and derives these edges from what it read:

Languages parsed: Python, JavaScript, JSX, TypeScript, TSX, Go, Rust, and C#. Markdown, text, .docx, and .xlsx are indexed for content and can carry references edges.

Resolution never guesses. A target that is ambiguous, or defined outside the repo, produces no edge rather than a plausible one. inherits additionally resolves a base type by name across the repo when exactly one file defines that name, because C# reaches base types through using <namespace> rather than a path import. Nodes are grouped into communities by deterministic label propagation, and graph.json is byte-identical across rebuilds of unchanged sources. Adding a language is a table entry in core/languages.py, since every grammar ships in the pinned tree-sitter-language-pack.

Artifacts land in .mimry/mimry-out/graph/ (graph.json, GRAPH_REPORT.md, manifest.json) during mimry index; there is no separate build step.

Freshness and incremental indexing

Like git, MIMRY treats a file as unchanged while its size, inode, and nanosecond mtime still match the snapshot it was indexed from, so status checks and reindexes do not re-read unchanged files. A reindex re-parses only new and changed files, and its output is identical to a full rebuild. Files modified within two seconds of the previous index scan are always re-read, which covers edits that land inside one timestamp tick. The one edit this cannot see is a rewrite that deliberately keeps size, inode, and mtime. Run mimry status --verify to re-hash every file, and mimry index --full to re-parse every file.

Feedback learning

mimry feedback records which files an agent actually used after a task. It is stored in the repo's local cache, is not telemetry, and becomes a modest, explainable ranking signal for similar future queries.

mimry feedback --query "fix board card click" \
  --context .mimry/mimry-out/context/latest.md \
  --opened src/features/boards/api.ts \
  --changed src/app/api/bridge/route.ts \
  --missed bridge/fastapi_app.py \
  --ignored README.md \
  --verification "npm run build passed" \
  --outcome passed

Exact filename, symbol, graph, and source evidence stay primary. Feedback breaks ties and recovers previously missed files; it does not override source-truth signals.

Recursive plan trees

mimry plan stores explicit, user-authored plan trees: one root with ordered children, each of which can be split again. It stores and renders the tree only; it does not generate plans, execute work, or track progress.

mimry plan new "Ship feature" --name ship-feature
mimry plan split <plan-id> <root-node-id> --child "Design" --child "Implement"
mimry plan tree <plan-id>          # also --json or --md
mimry plan check <plan-id>
mimry plan list

Ship feature [node-...]
|-- Design [node-...]
`-- Implement [node-...]

split works on leaves only, and repeated --child arguments set sibling order. Trees are canonical versioned JSON under .mimry/plans/, written atomically. IDs, projections, and the semantic SHA-256 from mimry plan digest exclude paths, timestamps, locale, and formatting. MCP exposes read-only parity (mimry_plan_tree, mimry_plan_check, mimry_plan_digest, mimry_plan_list); changing a plan is CLI-only.

Good roots vs bad roots

MIMRY works best when one root is one meaningful working context: a repo or a project folder.

Good roots: ~/Documents/project-a, C:\Users\you\Documents\project-a, D:\Work\active-product.

Bad roots: /, ~, ~/.config, ~/.cache, C:\, C:\Users\you, AppData, node_modules.

Whole-drive or whole-home indexing is noisy, slow, and likely to include secrets, caches, and unrelated projects. For a personal "global" memory, make a curated folder such as ~/Workspace and put only useful projects and docs in it.

Local-first safety

• Source files remain the final truth.
• Context packs use relative paths and summaries, not full source.
• Semantic search defaults to the deterministic local local-hash-v1; nothing is sent to a remote embedding service.
• Feedback is local metadata, not telemetry, and secret-looking values are redacted before they are stored.
• Scanner rules skip common credential files.
• Tester-owned acceptance_tests/ trees stay out of ordinary index surfaces by default. This is cooperative isolation, not secrecy: anyone with the repo can still open those files.

Cache generation and lock safety

Index publication, feedback writes, readers, generation cleanup, and mimry cache wipe --current share one per-root operation lock. POSIX readers share it; Windows readers take it exclusively because msvcrt.locking has no shared mode. Lock waits are bounded to 10 seconds by default; set MIMRY_LOCK_TIMEOUT_SECONDS to raise the bound. Timeout errors include the lock path and holder metadata, so a stuck process can be diagnosed without deleting lock files blindly.

Published indexes are immutable generations. Startup and successful publication remove abandoned staging trees and keep only the current and last-known-good generations. Generation manifests checksum immutable sidecars, and SQLite semantic rows carry the same generation identity plus a content checksum. mimry cache wipe --all is disabled until MIMRY has a proven cache-global writer protocol; use --current instead.

Structured adapters

Adapters teach MIMRY about common project surfaces: python-ast, typescript-ast, config-manifest, nextjs-app-router, fastapi, react-native-expo, sql-schema, markdown-docs, and generic-text. Run mimry adapters --verbose to see what each extracts.

Supported platforms

MIMRY targets Windows, Linux, and macOS on Python 3.11 to 3.13, and CI runs the full suite on all nine combinations. Paths are handled POSIX-style internally, and platform-specific system calls are capability-guarded rather than assumed. Handled explicitly, because each was a real bug:

• Path.home() resolves from USERPROFILE on Windows, not HOME.
• fsync needs a writable descriptor on Windows, and st_ctime there is creation time.
• os.utime(follow_symlinks=False) and byte-range lock semantics are capability-guarded.
• Human CLI output degrades Unicode safely on strict cp1252 consoles, while JSON, Markdown, and index artifacts stay UTF-8.
• Subprocesses never inherit stdin, which under the MCP stdio server is the JSON-RPC channel.

Support and releases

CI runs on every push and pull request: lint, tests, an end-to-end determinism matrix, an unlocked extracted-sdist parser suite, and a clean-wheel smoke test on each platform, plus jobs that compare determinism evidence across platforms and gate the retrieval benchmark. Releases are cut by pushing a vX.Y.Z tag, which builds reproducible artifacts and publishes them to PyPI and GitHub Releases. See CHANGELOG.md for release notes and RELEASING.md for the release checks.

Development

git clone https://github.com/jbacalso24/mimry.git
cd mimry
uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -q

Install the CLI from your checkout, so edits take effect immediately:

uv tool install --editable . --force

Install the Git hooks with uv run pre-commit install. Run uv run mimry-integration-smoke for a real MCP stdio round trip plus isolated Claude Code and Codex registration checks; it never touches your normal agent configuration.

Status

MIMRY is early but usable for local, per-project agent memory. It is not a whole-computer brain and should not be pointed at entire drives or home directories.