A local-first, Markdown-first memory harness for projects where humans and coding agents work from the same context. It gives agents a controlled path to ingest notes, reconcile them, maintain canonical project knowledge, plan and track work, log verification evidence, and pull focused context without relying on chat history.

Creation should be cheap. Promotion should be deliberate. Verification should be expensive.

The memory/ directory is the durable source of truth: knowledge, work items, raw intake, generated indexes, and agent role instructions. The CLI is the interface agents use to search, resolve, read, mutate, and verify that memory.

The basic flow:

capture cheaply -> reconcile deliberately -> promote to canonical memory -> execute with evidence -> verify before closure

Agent workflows tend to fail in predictable ways: context gets trapped in chats and screenshots, agents duplicate work because they can't tell what already exists, "done" gets declared without tests or evidence, raw notes get rewritten before anyone decides what they mean, and generated context drifts from canonical truth. MemoryMagico's structure — separate raw intake, canonical wiki pages, structured work records, generated indexes, and agent instructions — is aimed at those specific failure modes.

Git as the memory log

Project memory lives as plain files in the repo, not in a database or hidden agent state. That means every memory change is diffable, reviewable as a PR, revertible, branchable, and blameable — you can see when a claim, task, or decision entered the project, and roll it back if it's wrong.

git status --short
mm lint --json
mm index rebuild
git diff -- memory/
git add memory/
git commit -m "memory: record hardening audit findings"

For agent-heavy work this matters more, not less. Agents can write useful memory, but only if a human can inspect the diff, reject a bad change, or require evidence before merging. Rule of thumb: no memory mutation is trusted until it shows up in git diff and passes the standard checks.

Core concepts

The agent-facing rules are short: raw sources are immutable, wiki pages are canonical, generated indexes are disposable, agents resolve before they mutate, and verification evidence is required before anything is marked done.

Architecture

flowchart TD
  A[Raw intake] --> B[Reconciliation]
  B --> C[Canonical wiki]
  B --> D[Structured work records]
  C --> E[Generated search index]
  D --> E
  C --> F[Dashboard snapshot]
  D --> F
  E --> G["resolve / search / context"]
  G --> J[Agents and humans]
  H[Agent roles] --> I[Claude / Codex surfaces]
  I --> J
  J --> K[CLI mutations]
  K --> C
  K --> D
  C --> L[Git history]
  D --> L
  L --> M[diff / review / rollback]

memory/            durable source of truth — wiki, work records, raw intake, agent roles
src/, bin/         the mm CLI
schemas/           JSON schema guardrails
templates/         bundled default agent role definitions

Full repository layout, path resolution (toolRoot/repoRoot/memoryRoot), and dev setup live in CONTRIBUTING.md.

Installation

Prerequisites

Node.js 18 or newer. A Git repo is strongly recommended — Git is the audit log, review surface, and rollback mechanism for memory changes.

Local install

npm link
mm init
mm doctor
mm index rebuild

mm init is interactive when run from a terminal: it asks where to create the workspace, whether it's a standalone memory repo (git init + package.json) or being added to an existing project, whether to detect/overwrite an existing memory/, and which agent integration to install. Press enter to accept the recommended defaults, or skip the prompts entirely:

mm init --yes                          # accept defaults, non-interactive
mm init --root ~/projects/my-memory --standalone
mm init --existing --skip-agent-install --skip-npm-install

Run non-interactively (e.g. from CI or a script) and mm init skips the wizard automatically — it defaults to a standalone repo in the current directory with Claude Code agent integration installed, unless --skip-agent-install is passed.

package.json needs to declare the CLI entrypoint before npm link will work:

{
  "type": "module",
  "bin": {
    "mm": "./bin/mm.mjs",
    "memorymagico": "./bin/mm.mjs"
  }
}

Direct source usage

node bin/mm.mjs init
node bin/mm.mjs doctor
node bin/mm.mjs index rebuild

Or alias it:

alias mm="node $(pwd)/bin/mm.mjs"

Quick start

mm init
mm doctor
mm index rebuild

Create a canonical wiki page:

mm wiki create "Delivery Check" --kind concept
mm search "delivery check"
mm resolve "delivery check"
mm context "delivery check" --deep

Add a raw note and inspect it:

mm raw add --text "Need to document how sprint launch agents should verify task evidence."
mm raw list
mm raw show raw_...

Promote or reconcile it:

mm ingest raw_...
mm index rebuild
mm raw process raw_... wiki_page wiki_delivery_check memory/wiki/concepts/delivery-check.md

Health checks:

mm doctor
mm lint
mm index status

CLI overview

mm <command> [subcommand] [...args]

mm help
mm help search
mm commands
mm commands --json
mm info

Most read commands support --json; agents should use it when parsing results programmatically.

Safety model

Raw intake is immutable: source material is captured before interpretation and isn't rewritten in place. Promotion is deliberate: raw items get reconciled against existing records and checked for duplicates or staleness before being promoted. Reads are bounded: agents use mm read instead of unbounded file reads. Output is machine-readable where it matters, via --json. Writes are lock-protected and atomic to avoid partial artifacts. Tasks and issues require real verification evidence before they can be closed. The dashboard binds to 127.0.0.1 by default. Generated artifacts (search index, dashboard data) are disposable and get rebuilt from canonical memory, not hand-edited. And every meaningful mutation should be visible in git diff -- memory/ before it's trusted or merged — for large reconciliations, sprint launches, or refactors, do that work on a dedicated branch or worktree.

Learn more

Roadmap

• mm status — one-screen workspace health summary.
• mm safe — doctor + lint + index status + graph validation in one command.
• mm audit — hardening probes and command contract checks.
• mm snapshot, mm restore, mm rollback — safer agentic mutation.
• Stricter JSONL parsing in lint paths.
• Uniform path containment checks at every command boundary.
• Prompt-injection rules in every generated agent surface.
• Append-only mutation log for every state transition.
• Optional SQLite backend for high-concurrency agent runs.
• Shell completions generated from the command registry.

License

TBD.