MIMRY README

The local context engine for AI coding agents.

If MIMRY saves your agent tokens, please star it.

MIMRY is a command-line tool that tells AI coding agents which files, and which lines in them, to read for a task. It parses a repository into symbols and a dependency graph, keeps the index on your machine, and ranks the files that matter for a task described in plain words. The index is deterministic: the same code gives the same graph, rankings and context pack on Windows, Linux and macOS, and no LLM is involved in building it. Agents call it from the shell or through its MCP server.

Installation

uv tool install mimry

Requires Python 3.11 or newer on Windows, Linux or macOS. pipx install mimry and pip install mimry also work.

The first index downloads the tree-sitter grammars it needs, once per user, and keeps them in a cache.

[!NOTE] To upgrade, run mimry upgrade. On Windows, mimry upgrade refuses while MIMRY servers run, and mimry upgrade --stop-servers stops them first.

Claude Code plugin

In Claude Code, the plugin gives the agent the MIMRY skill, the hooks and the MCP server in one step. It needs uv on your PATH and nothing else.

/plugin marketplace add jbacalso24/mimry
/plugin install mimry@mimry

It replaces mimry install --platform claude-code, so use one or the other.

Other agents: npx skills

It installs the skill only; for the MCP server and hooks, run mimry install --platform <name> (see Supported agents).

npx skills add jbacalso24/mimry

Quick start

Run mimry preflight in your repository with a task description. The first run builds the index.

mimry preflight "Fix session cookie not refreshed when SESSION_REFRESH_EACH_REQUEST is set"

Output on the Flask repository:

Start with
   1  src/flask/sessions.py
      name matches · path matches · connected to other matches
      read first: lines 202-206 (get_cookie_secure), 233-247 (should_set_cookie)
   2  src/flask/ctx.py
      name matches · connected to other matches
      read first: lines 154-206 (copy_current_request_context), 395-403 (session)
   3  src/flask/testing.py
      name matches · connected to other matches
      read first: lines 135-183 (session_transaction), 193-202 (_request_from_builder_args)

The same result is written to .mimry/mimry-out/context/latest.md as a context pack for the agent, with the matched symbols, related files and the project's test commands.

To have your agent use MIMRY on its own, install it for that agent:

mimry install --platform claude-code

[!TIP] Add --always-on --hooks so the agent reaches for MIMRY without being told: --always-on adds the rules to its always-read file, and --hooks suggests mimry find whenever it starts a broad grep, and answers a grep for a known symbol with its definition and callers. The hooks also refresh the index in the background when a session starts and after each file edit.

Features

Supported languages

MIMRY parses these languages with tree-sitter for symbols, imports, calls and inheritance.

MIMRY also indexes Markdown (headings, links, frontmatter), plain text, PDF, Word and Excel files.

Other extensions can be mapped to a supported language in mimry.toml, see Configuration.

Planned

We're adding these next; progress is tracked in #47, where you can ask for yours.

• Web and markup: HTML, CSS, SCSS, Vue, Svelte
• Data and config: SQL, JSON, YAML, TOML, XML, Terraform (HCL)
• Apps and systems: Groovy
• Functional and scientific: Elixir, Haskell, OCaml, R, Julia
• Other: Solidity, Fortran, Pascal

Supported agents

mimry install --platform <name> installs a skill that teaches the agent when to use MIMRY, and registers the MCP server where the agent supports it.

✅ means mimry install sets it up, manual means you add the MCP server by hand, and 🚧 means support is in progress. none means the agent has no MCP support, so the skill alone covers it.

See docs/agents.md for where each agent's files go and how its MCP server is registered.

claude mcp add --scope user mimry -- mimry-mcp   # Claude Code
codex mcp add mimry -- mimry-mcp                 # Codex

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

Usage

mimry preflight "<task>"            # list the files and lines to read first, and write a context pack
mimry find "<query>"                # rank files for a query
mimry symbol <name>                 # find where a function, class or heading is defined
mimry callers <name>                # list the functions that call a function, from the graph
mimry callees <name>                # list the functions a function calls, from the graph
mimry related "<query>"             # list files connected through imports and calls
mimry explain "<task>"              # show the key files and symbols, and how they connect
mimry why <file> --query "<task>"   # explain why a file ranked
mimry feedback ...                  # record which files helped
mimry status                        # check whether the index is current
mimry doctor                        # diagnose the install and the index

See docs/commands.md for every command and option. When something misbehaves, see docs/troubleshooting.md.

Configuration

A mimry.toml at the repository root controls which files are indexed. Commit it so everyone on the team gets the same index.

[index]
include = ["src/**", "docs/**"]            # index only these paths
exclude = ["**/fixtures/**", "legacy/**"]  # never index these paths
max_file_bytes = 2_000_000                 # size limit per file (default 1 MB)

[index.languages]
".inc" = "php"                             # parse .inc files as PHP
".h" = "cpp"                               # parse .h headers as C++ instead of C

Benchmarks

Tokens an agent read before it found the code each pull request changed, measured on 92 merged pull requests from 12 open-source projects.

See benchmarks/tokens for the method, per-project results and how to reproduce them.

On the 500 issues of SWE-bench Verified, one mimry find with the issue text puts every file the fix changes in the top 10 for 74.6% of issues, in the top 5 for 63.8%, and first for 34.8%. See benchmarks/localization for the protocol and per-repository results.

To measure MIMRY on your own repository's merged pull requests, run mimry bench; see Benchmark your repository.

How it works

1. Index. MIMRY parses each file into symbols and edges for imports, calls and inheritance, and stores the index in your user cache directory, outside the repository.
2. Rank. MIMRY matches a task against file names, paths, content, symbols and the graph, and drops imports it cannot resolve rather than guessing.
3. Refresh. Like Git, MIMRY compares file metadata and re-reads only the files that changed.

See docs/how-it-works.md for details.

Privacy

Indexing and search run locally. Credential files are skipped, secret-looking values are redacted from feedback, and untracked files named in .gitignore are not indexed.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for setup and checks. MIMRY is in public alpha, and its interfaces may change before 1.0.

Thanks to everyone who has contributed:

License

MIT