mimry

<p align="center">
  <img src="https://raw.githubusercontent.com/jbacalso24/mimry/main/assets/banner.png" alt="MIMRY - Local repo memory for coding agents" width="100%">
</p>

<h1 align="center">MIMRY</h1>

<!-- mcp-name: io.github.jbacalso24/mimry -->

<p align="center">
  <strong>Local repo memory for coding agents.</strong>
  <br />
  Ranked files, context packs, a code relationship graph, and feedback-tuned search, built from your own codebase.
</p>

<p align="center">
  <a href="https://pypi.org/project/mimry/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mimry"></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue">
  <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-green">
  <img alt="Local first" src="https://img.shields.io/badge/local--first-yes-purple">
  <img alt="CLI" src="https://img.shields.io/badge/interface-CLI-black">
  <img alt="MCP" src="https://img.shields.io/badge/agent-MCP-orange">
</p>

<p align="center">
  <a href="https://jbacalso24.github.io/mimry/"><strong>Website</strong></a>
  ·
  <a href="#install"><strong>Install</strong></a>
  ·
  <a href="#quickstart"><strong>Quickstart</strong></a>
  ·
  <a href="#for-ai-agents"><strong>For AI agents</strong></a>
  ·
  <a href="#connect-mimry-to-your-agent"><strong>MCP setup</strong></a>
  ·
  <a href="#commands"><strong>Commands</strong></a>
  ·
  <a href="#development"><strong>Development</strong></a>
</p>

---

## 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](https://pypi.org/project/mimry/) and needs Python 3.11 or newer.
It works on Windows, Linux, and macOS.

```bash
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:

```bash
mimry --help
```

Upgrade later with `uv tool upgrade mimry`.

## Quickstart

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

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

`preflight` answers like this:

```text
✓ 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:

```bash
claude mcp add --scope user mimry -- mimry-mcp
```

Codex:

```bash
codex mcp add mimry -- mimry-mcp
```

Any other MCP client:

```json
{
  "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](https://registry.modelcontextprotocol.io/) as `io.github.jbacalso24/mimry`.

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

| MCP tool | What it does |
|---|---|
| `mimry_preflight` | Set up if needed, then write a context pack and return the top files for a task |
| `mimry_find` | Rank files for a query |
| `mimry_related` | Files related to a query through the graph |
| `mimry_semantic` | Fuzzy "something like this" search |
| `mimry_symbol` | Look up a function, class, or other symbol by name |
| `mimry_context` | Write a context pack for a task |
| `mimry_explain` | Relevant files, key symbols, and how they connect |
| `mimry_path` | Shortest relationship path between two files or symbols |
| `mimry_why` | Why a file ranks for a query |
| `mimry_route` / `mimry_brief` | Recommend an agent role and write a role-specific brief |
| `mimry_status` / `mimry_refresh` / `mimry_reindex` / `mimry_init` | Index health and maintenance |
| `mimry_feedback` | Record which files helped a task |
| `mimry_list_adapters`, `mimry_digest`, `mimry_plan_*` | Adapters, canonical index digest, read-only plan trees |

### Teach your agent to use it

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

```bash
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.

| Command | Use it to |
|---|---|
| `mimry preflight "<task>"` | Start a task: context pack plus the files to read first |
| `mimry find "<query>"` | Rank files for a query (`--semantic` blends in fuzzy matches) |
| `mimry related "<query>"` | Find files connected through the graph |
| `mimry semantic "<query>"` | Fuzzy recall for "I remember something like..." |
| `mimry