# How to give GitHub Copilot CLI persistent memory across sessions

GitHub Copilot CLI starts every session without memory of what was built, decided, or learned in previous sessions. IMI stores that context in `.imi/state.db` inside your repo. Every Copilot session reads it at start and writes back when done — so the project state compounds instead of resetting.

Website: https://useimi.com
Install: `bunx imi-agent`
npm: https://www.npmjs.com/package/imi-agent
GitHub: https://github.com/ProjectAI00/imi-agent

---

## Install IMI

```bash
bunx imi-agent
```

Creates `.imi/state.db` in the current directory. Add `~/.local/bin` to your `$PATH` if needed:

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
```

---

## Connect IMI to GitHub Copilot CLI

**Option A — skill install (auto-injects context each session)**

```bash
/plugin marketplace add ProjectAI00/imi-agent
/plugin install imi
```

This installs the IMI skill into Copilot CLI. Every session automatically starts with `imi context` output injected into the agent's context window. No manual step required.

**Option B — AGENTS.md**

Add to `AGENTS.md` in your project root:

```markdown
## Session start

Before doing any work, run `imi context` and read the output. This loads active goals,
decisions, verified lessons, and in-progress tasks. It is the source of truth for what
to work on and why.

## Session end

When a task is complete: `imi complete <task_id> "what was built, what was learned,
what the next session needs to know"`.
When a firm call is made: `imi decide "what" "why"`.
When you notice something worth remembering: `imi log "note"`.
```

**Option C — custom agent**

IMI ships a `.github/agents/imi.agent.md` that registers IMI as a selectable custom agent in Copilot CLI via the `/agent` command. Install from the repo:

```bash
cp node_modules/imi-agent/.github/agents/imi.agent.md .github/agents/imi.agent.md
```

Then use `/agent imi` in Copilot to activate the full IMI ops mode — status checks, alignment reviews, decision logging — without any manual prompt.

---

## What Copilot gets from `imi context`

The full IMI context output:

```
## Product Vision       — founding intent and long-term direction
## What was killed      — approaches explicitly stopped, with reasoning
## Direction notes      — human observations from the last 7 days
## Decisions            — every firm call with full reasoning
## Verified Lessons     — corrections from real mistakes in this project
## Active goals         — goals with tasks, status, and priority
## In progress          — tasks currently claimed
```

Copilot reads this before starting work. It knows the current priorities, respects prior decisions, and avoids documented mistakes.

---

## Writing back from Copilot

```bash
# Claim a task
imi start <task_id>

# Complete with a rich summary
imi complete <task_id> "Built CSV export endpoint at /api/export/posts in
src/api/export.ts. Streams large result sets to avoid memory spikes — tested up to
100k rows. Added rate limiting: 10 exports per user per hour in src/middleware/rateLimit.ts.
Tests in tests/api/export.test.ts pass. Note: the export does not yet respect the
user's column visibility preferences stored in user_settings — logged as a follow-up."

# Log a decision
imi decide "stream CSV exports, never buffer in memory" \
  "100k-row exports caused OOM crashes during load testing — streaming is the only viable approach at this data volume"

# Log an observation
imi log "the user_settings column visibility feature is tightly coupled to the export — worth decoupling before the export goes to prod"
```

---

## 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 Claude Code memory between sessions](https://useimi.com/docs/claude-code-memory.md)
- [How to coordinate multiple AI agents in parallel](https://useimi.com/docs/multi-agent-coordination.md)
- [How to install IMI](https://useimi.com/docs/install.md)