Prerequisites
- A recent Node.js release (Node 24 recommended), pnpm and Git.
- Codex CLI or Claude Code installed and signed in. Automatic mode uses whichever authenticated agents are available.
- A Metatheory account for hosted CLM sign-in.
- Optional: tmux for the split chat, status and activity layout.
Your installed Codex or Claude CLI handles agent turns. After you sign in, MipMap uses CLM for summaries and model routing. You do not need to create or store a provider API key locally.
Clone and install
git clone https://github.com/metatheoryinc/mem-mipmap.git
cd mem-mipmap
pnpm installCommands in this guide run from the cloned mem-mipmap repository.
Start your ongoing chat
Choose the repository where the agent should work:
pnpm mipmap chat -C /path/to/your/projectFor chat, status and activity in one tmux session:
pnpm mipmap tmux -C /path/to/your/projectMipMap records the conversation in its local memory directory. Relaunching the same command returns to that memory rather than beginning with an empty thread.
Connect MipMap
In the MipMap chat, enter:
/loginMipMap opens the hosted CLM device flow. Sign in with your Metatheory Google account and approve the code. The resulting session credential is saved only for MipMap in ~/.mipmap/clm.json.
Once connected, CLM handles summaries and chooses the provider, model and effort for each turn from MipMap's currently permitted menu. The routing request includes the current task, brief context, permitted model options and available quota estimates. It never includes the complete memory view. The raw quota cache stays local.
MipMap does not install CLM's Claude Code or Codex behavior hooks. Follow the separate Claude Code or Codex guide if you also want those checks.
Import old memories
Bring local Claude Code or Codex sessions into the same durable memory before starting a new long-running chat. Stop any MipMap chat using that memory directory first: imports and chat take the same write lock.
Start with a no-cost import, which stores the source messages without creating summaries:
pnpm mipmap import claude-code ~/.claude/projects --no-summaries
pnpm mipmap import codex ~/.codex/sessions --no-summaries
pnpm mipmap estimateReview the estimate, then rerun the import without --no-summaries when you are ready for CLM to summarize pending history. Imports are safe to rerun: messages are deduplicated and existing summaries are reused.
MipMap imports local JSONL sessions, retaining conversational text while filtering tool traffic and injected context. Codex imports keep user messages and final replies, and skip internal and subagent sessions. ChatGPT website exports are not supported.
Verify and inspect
pnpm mipmap status
pnpm mipmap usage
pnpm mipmap estimate- status shows the current agent, summarizer, memory and routing state.
- usage summarizes recorded agent-turn and summarizer usage.
- estimate estimates pending summarization work without making model calls. It is not a spending cap.
Use pnpm mipmap browse --open to inspect local conversation history, or pnpm mipmap activity to follow the activity log.
Update MipMap
git pull
pnpm installRun the commands in your mem-mipmap clone, then restart the chat or tmux session. Your memory directory is separate from the application clone.
What leaves your machine
The append-only message log, summary tree, usage records and local Git history live in your MipMap memory directory. Treat that directory as private conversation data. Secret redaction runs before message text is stored, but it cannot guarantee that every sensitive value is removed.
Memory is local, but selected conversation content leaves the machine: agent context goes to the chosen Codex or Claude provider, and source material for summaries goes through the hosted CLM service to its configured model provider. The picker receives the current task, brief context, permitted model options and available quota estimates. It does not receive the complete MipMap memory or the raw local quota cache.
Billing
Agent turns use the authentication and billing of the selected installed CLI. Hosted summaries and routing use your CLM account; no separate provider API key is required on your machine. Choosing a model does not reserve provider quota or guarantee availability.
Get help
Run pnpm mipmap status first. The project README covers terminal controls, imports, configuration variables and local memory inspection. No model call is needed to inspect status or run an estimate.