MIMRY

Local repo memory for coding agents.
Build context packs, graph maps, semantic recall, and feedback-ranked search from your own codebase.

Quickstart · Why MIMRY? · What it builds · MCP · Good roots · Development

MIMRY gives agents a focused memory layer for a repo or project folder. Instead of opening random files, rereading the same tree, or guessing where logic lives, an agent can ask MIMRY for a compact evidence-backed handoff before it edits anything.

cd /path/to/your/project
mimry preflight "fix auth bug"

MIMRY checks freshness, refreshes when needed, ranks likely files, and writes a context pack for the agent:

Context: .mimry/mimry-out/context/latest.md
Top files:
1. src/auth/session.py
2. src/app/login/page.tsx
3. tests/test_auth.py

MIMRY is local-first. Source files, tests, and real build output remain the final truth.

Why MIMRY?

Coding agents usually start cold. They need to discover project structure, find the right files, understand relationships, and avoid touching generated or risky paths. That wastes time and creates bad edits.

MIMRY turns a local repo into a small intelligence layer:

• Context packs for agent handoffs
• Task routing and role-aware briefs for agent orchestration
• File and symbol indexes for quick navigation
• Relationship maps for code/document relationships
• Local semantic recall for fuzzy “I remember something like…” queries
• Feedback ranking from what agents actually opened, changed, missed, or ignored
• MCP tools so coding agents can query MIMRY directly
• Privacy-first behavior: no remote embeddings by default, no source dumps in context packs, and secret-looking feedback values are redacted before persistence
• Cooperative test isolation: tester-owned acceptance_tests/ trees stay outside ordinary index surfaces by default; this is not secrecy, because repository users can still open those files directly

Use it when you want agents to answer:

• “What files matter for this task?”
• “Where is this flow probably implemented?”
• “What should I read first?”
• “What changed last time a similar task was done?”
• “What verification commands are likely relevant?”

Quickstart

MIMRY is a Python package with two CLI entrypoints:

• mimry — main CLI
• mimry-mcp — MCP server for agent integrations

Requirements:

• Python >=3.11 (required CI currently covers 3.11, 3.12, and 3.13)
• uv
• Git (for repo analysis)

Supported platforms

MIMRY targets Windows, Linux, and macOS. Paths are handled POSIX-style internally regardless of host, and platform-specific syscalls are capability-guarded rather than assumed.

CI runs the full suite on ubuntu-latest, macos-latest, and windows-latest across Python 3.11–3.13, so a regression on any of the three fails the build.

Specific things that are handled rather than assumed, because each one was a real bug:

• Path.home() resolves from USERPROFILE on Windows, not HOME
• fsync needs a writable descriptor on Windows; st_ctime there is creation time and differs between os.fstat and Path.lstat for the same file
• os.utime(follow_symlinks=False) and byte-range lock semantics are capability-guarded
• human CLI streams use backslashreplace, so Unicode paths degrade safely on strict cp1252 consoles while JSON, Markdown, and index artifacts remain UTF-8
• subprocesses never inherit stdin, which under the MCP stdio server is the JSON-RPC channel
• paths are POSIX-normalized internally; only display strings use native separators

MIMRY 0.1.x is distributed internally from an authorized checkout or as a direct wheel artifact. See RELEASING.md for the supported channel and exact commands.

Install from a checkout:

git clone <mimry-repo-url>
cd mimry
uv sync
uv run pytest -q
uv tool install --editable . --force

Verify the install:

mimry --help
mimry status
uv tool list

Expected uv tool list output includes:

mimry v0.1.0
- mimry
- mimry-mcp

First run in a project

Use MIMRY inside a local repo or meaningful project folder:

cd /path/to/your/project
mimry init
mimry refresh
mimry status
mimry context "understand auth flow"

For agents, prefer the one-command preflight workflow:

mimry preflight "fix auth bug"

preflight initializes the root if needed, checks index freshness, builds the index only when there is none yet (a stale index still answers, with a warning; pass --force-refresh to reindex first), generates .mimry/mimry-out/context/latest.md, prints top files, and reminds the agent to read the context pack before opening source files.

What it builds

After mimry init and mimry refresh, a project gets this shape:

project-root/
├─ .mimry/                  # hidden local control/config
│  └─ mimry-out/            # generated MIMRY output for agents/humans
│     ├─ context/latest.md  # latest context pack
│     └─ graph/             # native relationship graph artifacts
└─ source files...

MIMRY also stores local indexes in the user cache directory. Those indexes are generated artifacts, not source of truth.

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.

Graph relationships

The engine emits five edge types:

Languages parsed: Python, JavaScript, JSX, TypeScript, TSX, Go, Rust, 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.

A context pack includes:

• query and status summary
• index and graph freshness
• ranked relevant files with reason labels
• symbol/entity hints when indexed
• graph relationship and community signals when available
• suggested reading order
• likely edit surfaces vs support files
• risk notes for generated/cache/privacy-sensitive paths
• suggested verification commands from project manifests and docs
• final report checklist for agents

Context packs remain relative-path-first and never dump full source or secret values. See docs/context-packs.md for the section contract.

CLI examples

Every command answers in the same shape: one line that says what happened, a few indented details, and a next step only when something needs doing.

$ mimry reindex
✓ Updated the index for my-app in 2.2s
  2 files changed, 1 added
    changed  src/auth/session.py
    changed  src/auth/middleware.py
    added    src/auth/magic_link.py
  3,105 files · 6,859 symbols · 10,749 links

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

Add --verbose (-v) to any command for paths, scores, raw ranking reasons and other internals. Colour is used only on an interactive terminal, and NO_COLOR=1 turns it off. Piped and captured output always uses plain ASCII marks (OK, !, x), so scripts and agents see the same text everywhere. mimry roots lists every indexed folder on this machine, and mimry roots --prune forgets folders that no longer exist.

Find likely files:

mimry find "auth login token"

Generate an agent handoff:

mimry context "debug checkout redirect"

Route a task to an agent role and write a focused brief:

mimry route "fix FastAPI auth migration bug"
mimry route "fix FastAPI auth migration bug" --json
mimry brief "fix FastAPI auth migration bug" --agent backend

route recommends one of backend, frontend, mobile, reviewer, qa, docs, tooly, or general, with confidence, why, suggested context-pack labels, likely files, risk level/severity, risk/approval gates, verification hints, and a pasteable next command. --json prints the same structured payload for agents/tools. brief writes .mimry/mimry-out/context/brief-<agent>.md without dumping source contents.

Explain why something ranked:

mimry why src/auth/session.py --query "login auth bug"

Find a graph relationship path:

mimry path "ui hook" "sqlite cache"

Explain a task/debug area:

mimry explain "login route bug"

Use local semantic recall:

mimry semantic "vague thing I remember"
mimry find "auth redirect weirdness" --semantic
mimry context "payment flow bug" --semantic

Target another root explicitly:

mimry --root /path/to/repo status

Recursive plan trees

mimry plan is a narrow deterministic decomposer for explicit, user-authored plan structure. A plan has one root and ordered children; every child can be split again to arbitrary depth. It stores and renders the tree only. It does not generate plans with an LLM, execute work, schedule it, track evidence, or act as a board, goal, or todo system.

Initialize MIMRY in the repository, then create and decompose a tree:

mimry plan new "Ship feature" --name ship-feature
# prints Plan ID and Root node ID

mimry plan split <plan-id> <root-node-id> \
  --child "Design" \
  --child "Implement"
mimry plan split <plan-id> <design-node-id> \
  --child "Data shape" \
  --child "User flow"

mimry plan tree <plan-id>
mimry plan tree <plan-id> --json
mimry plan tree <plan-id> --md
mimry plan check <plan-id>
mimry plan digest <plan-id>
mimry plan list

Example default projection:

Ship feature [node-...]
|-- Design [node-...]
|   |-- Data shape [node-...]
|   `-- User flow [node-...]
`-- Implement [node-...]

split is intentionally leaf-only. Repeated --child arguments define sibling order, and splitting a non-leaf is rejected rather than ambiguously replacing or appending children. Trees are stored as canonical versioned JSON under .mimry/plans/ with atomic writes and a bounded local lock. Text is normalized to UTF-8/LF/NFC. Stable IDs, projections, validation errors, inventory, and the semantic SHA-256 exclude checkout paths, timestamps, locale, timezone, runtime state, and formatting-only metadata. Stored plans reject duplicate JSON keys, unknown fields, or IDs that no longer derive from their canonical plan/root/ parent data. Redirected default, JSON, and Markdown projections are canonical UTF-8 bytes; interactive terminals retain code-page-safe human output.

Read-only MCP parity is available as mimry_plan_tree, mimry_plan_check, mimry_plan_digest, and mimry_plan_list. Plan mutation remains CLI-only.

Feedback learning

mimry feedback records local operational metadata about what an agent actually used after a task. It is not telemetry and is not durable user memory. It is stored in the current root's local SQLite cache and used as a modest explainable ranking signal for future similar queries.

Example:

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

Read feedback later:

mimry feedback stats
mimry feedback list --limit 10
mimry feedback show <feedback_id>

Feedback can add labels such as:

• feedback changed-file boost
• feedback opened-file boost
• feedback missed-file recovery boost
• feedback ignored suggestion downrank

Exact filename, symbol, graph, framework, and source evidence remain primary. Feedback helps break ties and recover previously missed files; it should not override source-truth signals.

MCP for agents

Expose MIMRY to coding agents through MCP:

mimry-mcp

Available MCP-style workflows include:

• status checks
• index refresh
• file search
• related file discovery
• symbol search
• context-pack generation
• adapter listing
• task routing (mimry_route)
• role-aware brief generation (mimry_brief)

This lets agents ask the local project memory for focused context instead of scraping the whole repo from scratch.

For a real stdio protocol round trip plus isolated Claude Code and Codex MCP registration checks, run:

uv run mimry-integration-smoke

The smoke is included in installed wheels as well as source artifacts. It creates a temporary repo/cache and temporary client config homes, passes clients a credential-free allowlisted environment, calls MIMRY tools through an actual FastMCP stdio client, asks Claude Code to health-check the server, and reads Codex's registered transport back as JSON. It never edits the operator's normal Claude/Codex configuration. Missing clients are reported as UNVERIFIED, not silently treated as passes; Herdr remains pane-only and is never simulated by this harness.

Agent skill install

MIMRY can also install a MIMRY-owned skill/instruction bundle for coding agents. It installs MIMRY workflow rules only.

List supported platforms:

mimry install --list-platforms

Install globally for an agent profile:

mimry install --platform claude-code
mimry install --platform codex
mimry install --platform hermes
mimry install --platform agents
mimry install --platform opencode
mimry install --platform kilo
mimry install --platform aider
mimry install --platform copilot
mimry install --platform claw
mimry install --platform droid
mimry install --platform trae
mimry install --platform trae-cn
mimry install --platform kiro
mimry install --platform gemini
mimry install --platform amp
mimry install --platform devin
mimry install --platform antigravity
mimry install --platform kimi
mimry install --platform pi
mimry install --platform codebuddy

Install into the current project instead:

mimry install --project --platform codex

Project installs write skill files and focused references, for example:

.codex/skills/mimry/SKILL.md
.codex/skills/mimry/references/workflow.md
.codex/skills/mimry/references/commands.md
.codex/skills/mimry/references/mcp.md
.codex/skills/mimry/references/feedback.md
.codex/skills/mimry/references/safety.md

For project-scoped installs, add always-on instructions so the agent is reminded to use MIMRY before broad search:

mimry install --project --platform codex --always-on

For supported platforms, also add PreToolUse hooks that nudge the agent before broad search/file exploration:

mimry install --project --platform codex --hooks
mimry install --project --platform claude-code --hooks

Check install health and repair by rerunning install with the same options:

mimry install --project --platform codex --status
mimry install --project --platform codex --always-on --hooks

Remove an install:

mimry uninstall --project --platform codex --always-on --hooks

claude is accepted as an alias for claude-code, skills for agents, openclaw for claw, and factory for droid. The Claude target means Claude Code, not the Claude web app.

The installed skill tells agents to run mimry preflight, read .mimry/mimry-out/context/latest.md, use focused MIMRY queries before broad search, verify against real source/tests/build output, and record mimry feedback after work.

Good roots vs bad roots

MIMRY works best when one root equals one meaningful working context.

Good roots:

/home/you/Documents/project-a
/home/you/Documents/product-workspace
/home/you/.hermes/hermes-agent
/Users/you/Documents/project-a
C:\Users\you\Documents\project-a
D:\Work\active-product

Bad roots:

/
/home/you
/home/you/.config
/home/you/.cache
/Users/you
C:\
C:\Users\you
C:\Users\you\AppData
node_modules

Avoid whole-drive or whole-home indexing. It is noisy, slower, and more likely to include secrets, caches, browser data, dependency folders, and unrelated old projects.

If you want a personal “global” memory, create a curated folder such as:

~/Workspace
~/Documents/Active
D:\Work\Active

Put only useful projects and docs there.

Local-first safety

MIMRY is designed around local project memory:

• source files remain the final truth
• context packs use relative paths and summaries, not full source dumps
• semantic search defaults to deterministic local local-hash-v1
• feedback is local metadata, not telemetry
• secret-looking feedback values are redacted before persistence
• scanner/security rules skip common credential files
• generated/cache paths are treated as support artifacts, not source fixes

MIMRY narrows context. It does not replace reading source files, running tests, or checking real build output.

Cache generation and lock safety

Index publication, feedback writes, readers, generation cleanup, and mimry cache wipe --current use one stable per-root operation lock. POSIX readers share it; Windows readers intentionally 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 a positive number when a slower operation needs a larger bound. Timeout errors include the lock path and available holder metadata so a stuck process can be diagnosed without deleting lock files blindly.

After mimry cache wipe --current, status truthfully reports a missing index and the normal mimry index / mimry refresh path rebuilds it. mimry cache wipe --all is disabled until MIMRY has a proven cache-global writer coordination protocol; use the per-root wipe instead.

Published indexes are immutable generations. Startup and successful publication remove abandoned staging/orphan trees while retaining only the pointer-current and last-known-good generations. Generation manifests checksum immutable sidecars, and SQLite semantic rows carry the same generation identity plus a deterministic content checksum.

Locking uses advisory flock on POSIX systems, including macOS. Windows uses msvcrt.locking over one byte as a best-effort advisory equivalent; Windows does not provide POSIX inode/flock semantics, so native Windows crash/rename behavior remains a platform-specific verification boundary.

Structured adapters

MIMRY includes structured adapters for common project surfaces. Check active adapters with:

mimry adapters --active-only

Current adapters include:

python-ast
typescript-ast
config-manifest
nextjs-app-router
fastapi
react-native-expo
sql-schema
markdown-docs
generic-text

Graph engine

MIMRY builds its own relationship graph in src/mimry/core/. Indexing parses each file once and derives three kinds of edge from what it already read:

• defines -- a file defines a symbol
• imports -- an import statement resolved to a real file in the repo
• calls -- a call site resolved to a symbol, in the same file or through an import

Imports that cannot be resolved unambiguously are dropped rather than guessed, so a relationship shown by mimry path or mimry why is one MIMRY can actually evidence. Nodes are grouped into communities by deterministic label propagation, and graph.json is byte-identical across rebuilds of unchanged sources.

Languages covered: Python, JavaScript, TypeScript, JSX, TSX, Go, Rust, and C#. Adding a language is a table entry in core/languages.py, not new code -- every grammar ships in the already-pinned tree-sitter-language-pack.

Artifacts land in .mimry/mimry-out/graph/: graph.json, GRAPH_REPORT.md, and manifest.json. They are written during mimry index; there is no separate build step.

Support and releases

MIMRY targets Python 3.11–3.13 on Windows, Linux, and macOS. That matrix is committed in .github/workflows/ci.yml and runs on every push and pull request: 9 matrix cells running lint, tests, the real end-to-end determinism matrix, the unlocked extracted-sdist parser suite, and a clean-wheel smoke test; a determinism-aggregate job that requires evidence from all 9 cells and compares the canonical digest, retrieval rankings, and context pack across them and against committed golden values; and a benchmark-gate job that first validates that the committed PASS still matches the fixture, cases, retrieval source, and frozen thresholds, then writes a fresh measured report only to a CI artifact.

A green CI run is required for a release but does not replace review. Releases are manual internal direct artifacts and there is no automated publishing step.

See CHANGELOG.md for release notes and RELEASING.md for the exact artifact and clean-wheel checks.

Development

Install development dependencies:

uv sync

Run checks:

uv run ruff format .
uv run ruff check .
uv run pytest -q

Install local Git hooks:

uv run pre-commit install
uv run pre-commit run --all-files

Install the CLI from your checkout:

uv tool install --editable . --force

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.