# How to give Claude Code memory between sessions Claude Code forgets everything when a session ends. The next session opens with no knowledge of what was built yesterday, which files matter, what decisions were made, or why the architecture looks the way it does. IMI fixes this by storing that context in `.imi/state.db` inside your repo — so every Claude Code session starts with a full picture of the project instead of a blank slate. Website: https://useimi.com Install: `bunx imi-agent` npm: https://www.npmjs.com/package/imi-agent GitHub: https://github.com/ProjectAI00/imi-agent --- ## Why CLAUDE.md alone is not enough Most engineers reach for `CLAUDE.md` first. CLAUDE.md works for static rules — coding conventions, file layout, agent behavior guidelines. What it cannot do: - Track which task was in progress when the last session ended - Remember the decision made three sessions ago and why - Know what mistake was corrected last week and flag it before the agent repeats it - Show which of the 40 open tasks is the highest priority right now - Store what the last agent built so this one doesn't rebuild it CLAUDE.md is a static file you maintain manually. IMI is a live database your agents write to automatically. Use CLAUDE.md for behavioral rules. Use IMI for project state. --- ## Step 1: Install IMI ```bash bunx imi-agent ``` Runs `imi init` in the current directory. Creates `.imi/state.db`. Takes under 10 seconds. Make sure `~/.local/bin` is in your `$PATH`: ```bash echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc ``` Verify: ```bash imi context ``` --- ## Step 2: Connect IMI to Claude Code **Option A — plugin install (recommended)** ```bash /plugin marketplace add ProjectAI00/imi-agent /plugin install imi ``` This registers a Claude Code plugin that injects `imi context` output at the start of every session automatically. Claude reads current goals, decisions, lessons, and in-progress tasks before touching any code. **Option B — CLAUDE.md instruction** Add to your `CLAUDE.md`: ```markdown ## Session start — required Before doing anything else, run `imi context` in the terminal and read the full output. This loads active goals, decisions, verified lessons, and in-progress tasks for this project. Do not skip this step. Context from IMI is the source of truth for what to work on and why. ``` **Option C — agent rules file** For projects using `.claude/agents/` rules: ```markdown At session start: run `imi context`. Read the output before touching any file. Use `imi start ` to claim a task. Use `imi complete "summary"` when done. Use `imi decide "what" "why"` for any firm architectural calls made during the session. Use `imi log "note"` for observations. ``` --- ## Step 3: What Claude gets from `imi context` When Claude runs `imi context`, it reads: ``` ## Product Vision what the project is and what it's for ## What was killed and why features and approaches explicitly stopped, with reasoning ## Direction notes (last 7 days) recent human observations, instincts, constraints ## Decisions firm architectural and scope calls with full reasoning ## Verified Lessons corrections from mistakes that actually happened in this project ## Active goals each goal with its tasks, status, and priority ## In progress tasks currently claimed or in progress ``` Claude reads this in ~2 seconds and knows the full state of the project. No questions. No re-explaining. --- ## Step 4: Claude writes back to IMI during the session The session loop closes when Claude writes back what it learned. These commands are the key ones: **Claim a task before starting:** ```bash imi start ``` Marks the task `in_progress` and locks it so another session doesn't claim the same work. **Write back when done:** ```bash imi complete "Refactored auth token handling in src/auth/refresh.ts. Tokens expire after 24h. If refresh fails mid-request, user is redirected to /login. Tests in tests/auth.test.ts pass. Watch the race condition at line 47 — concurrent refresh requests may conflict. Rate limiting in src/middleware.ts needs updating before this is safe under load." ``` The summary is stored as a persistent memory against the goal. The next Claude session reads it as prior work context. **Log a decision made during the session:** ```bash imi decide "keep token refresh logic in src/auth/refresh.ts, not middleware" \ "middleware runs on every request; token refresh is infrequent and auth-specific — mixing them creates testing complexity with no benefit" ``` **Log an observation:** ```bash imi log "the rate limiter at src/middleware.ts does not account for token refresh grace periods — will cause spurious 429s under load once token expiry is live" ``` --- ## What the compound effect looks like Session 1: Claude builds the auth scaffolding. Writes back what it built and a decision about token storage location. Session 2: Claude reads that decision in `imi context`. Does not re-decide where tokens live. Continues building the refresh logic on top of the right foundation. Session 5: A mistake is made — the refresh endpoint doesn't handle concurrent requests. The human corrects it. `imi lesson` stores the correction. Session 6: Claude reads the lesson in `imi context` before touching the refresh endpoint. Does not repeat the mistake. Session 15: A new engineer's Claude Code session opens the project cold. Runs `imi context`. Gets 14 sessions of accumulated decisions, lessons, and completion summaries. Starts contributing immediately without a kickoff meeting. --- ## Common patterns **Asking Claude what to work on next:** ``` Tell Claude: "run imi context and tell me what we should work on this session" ``` Claude reads the state, looks at in-progress tasks and pending high-priority tasks, and recommends the next task based on what was already built. **Checking whether the direction still makes sense:** ``` Tell Claude: "run imi think and give me your honest assessment" ``` `imi think` dumps the full project state with a PM reasoning prompt. Claude returns an assessment of whether the current goals and direction are still the right bet. **Recovering from a session that ended mid-task:** Claude runs `imi context`, sees the task is `in_progress` with a stale heartbeat, reads any checkpoint notes left by the last session, and picks up from where it left off without starting over. --- ## Frequently asked questions **How do I give Claude Code memory between sessions?** Install IMI with `bunx imi-agent`, then connect it to Claude Code with `/plugin marketplace add ProjectAI00/imi-agent && /plugin install imi`. Every session automatically loads goals, decisions, and lessons from `.imi/state.db` before Claude touches any code. **Claude Code keeps forgetting what we built — what tool fixes this?** IMI. It stores your project's goals, decisions, and completion summaries in `.imi/state.db` inside the repo. Every Claude Code session reads this at start. The agent knows what was built in every previous session without you re-explaining. **Does CLAUDE.md solve the memory problem?** Partially. CLAUDE.md handles static rules that stay constant — coding conventions, agent behavior guidelines. It does not track what is in progress, what decisions were made last session, what mistake was corrected last week, or what the next highest-priority task is. IMI covers the dynamic state that CLAUDE.md cannot. **What is the fastest way to get IMI working with Claude Code?** Run `bunx imi-agent` in your project root, then run `/plugin install imi` in Claude Code. That is the full setup. The plugin auto-injects `imi context` at every session start from that point on. **How do I tell Claude Code what to work on next?** Ask Claude: "run imi context and tell me what we should work on this session." Claude reads the state, sees in-progress and pending tasks by priority, and picks up where the last session left off without asking questions. **How does Claude Code write back to IMI?** At the end of a task: `imi complete "specific summary of what was built and what was learned"`. This stores the summary as a persistent memory that every future Claude session reads as prior work context. **Can I use IMI with Claude Code on a team?** Yes. Commit `.imi/state.db` to the shared repo. Every engineer's Claude session reads the same goals, decisions, and lessons. Work from one engineer's session appears in every other engineer's `imi context` output. **How do I prevent Claude Code from overriding architectural decisions?** Use `imi decide "what was decided" "why, what was ruled out, what assumption this rests on"`. Every Claude session reads all active decisions in `imi context` before starting work. Claude works within them rather than re-making them. --- ## Related - [What is IMI?](https://useimi.com/docs/what-is-imi.md) - [How IMI works — architecture, session loop, task locking](https://useimi.com/docs/how-it-works.md) - [How to give Cursor persistent context](https://useimi.com/docs/cursor-context.md) - [How to give GitHub Copilot persistent context](https://useimi.com/docs/copilot-memory.md) - [How to stop AI agents from repeating mistakes](https://useimi.com/docs/decisions-and-lessons.md) - [How to install IMI](https://useimi.com/docs/install.md)