Context continuity for Claude Code and Grok across compaction — structured handoffs that keep agent memory and working state intact through every /compact, auto-compact, and resume.
Inside Claude Code, from the 88plug marketplace:
/plugin marketplace add 88plug/claude-code-plugins
/plugin install amnesia@88plug
grok plugin marketplace add 88plug/claude-code-plugins
grok plugin install amnesia@88plug --trust
Tip
That is the whole setup. After install, amnesia runs in the background — no commands, no files to manage, no visible interruptions.
- Install with the two commands above.
- Work normally. Let a
/compact(or auto-compact) fire mid-task. - On the next turn the agent still knows the working theory, next action, files in motion, and your recent constraints — not a lossy summary.
Confirm it is active:
/amnesia:status
You will see the captured handoff for the current project.
When Claude Code compacts, the model's working memory is replaced by a one-shot summary. Exact file contents, prior tool outputs, verbatim user constraints, and mid-task reasoning get paraphrased away. Long AI agent sessions drift after every compact.
amnesia is a Claude Code plugin for context engineering and agent memory. Background hooks capture a structured handoff at every compaction boundary — and proactively before the next one — then re-inject it on session start. The agent resumes knowing:
- what it was just doing (working theory plus the concrete next action)
- which files were in motion and which commands had run
- the user's most recent constraints, verbatim
- the path to the on-disk JSONL transcript (Claude Code never truncates it), so any lost detail costs one
Read
Note
Recommended install is the 88plug marketplace. Installing from this repo works but will not auto-update with curated releases. The plugin package is the repository root (standard 88plug layout).
| Feature | Detail |
|---|---|
| Invisible by default | Background hooks only; no UI, no required commands |
| Multi-layer handoff | L1 mechanical (sync), L2 Opus enrich, L3 Stop refine, preemptive snapshot |
| Continuous capture | Every tool call appends to working-state.jsonl in under 50 ms |
| Perfect-recall escape hatch | On-disk JSONL is append-only; handoff cites [L:N-M] ranges |
| Isolated summarization | claude -p runs with CLAUDE.md and auto-memory disabled |
| Subagent inject | Trimmed handoff on every SubagentStart |
| Power-user commands | Snapshot, recall, status, promote, sessions, diff, why, migrate |
| Read-only MCP server | recall and handoff_get for agent-driven retrieval |
| Continuity skill | continuity-protocol teaches silent post-compact recovery |
amnesia runs as background hooks. Each event is invisible to you.
| Event | When | Latency | What it does |
|---|---|---|---|
| Continuous capture | Every matched tool call | <50 ms sync | Appends a one-line record to working-state.jsonl |
| PreCompact sidecar | Before compaction | <100 ms sync | Tails the transcript into a sidecar for L1 |
| L1 mechanical | After every compaction | <500 ms sync | Deterministic handoff from JSONL + working-state + git state |
| L2 enrich | After every compaction | ~30–60 s asyncRewake | Opus 4.7 --effort max rewrites the handoff with narrative |
| L3 refine | First Stop after compaction | ~30–60 s asyncRewake | Opus refines the handoff using post-compact work |
| Preemptive | At ~75% of context (~2 MB since last boundary) | ~30–60 s async | Snapshots state before the next compact, while it is still in the window |
| Restore | SessionStart (compact / resume / startup) | <100 ms sync | Injects the handoff into additionalContext |
| Subagent inject | Every subagent spawn | sync | Injects a trimmed handoff (default ≤3 KB) |
| Session end | Session teardown | sync | Final archive snapshot + optional opt-in git push |
All summarization runs isolated from your CLAUDE.md, auto-memory, and auto-triggered skills (CLAUDE_CODE_DISABLE_CLAUDE_MDS=1, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, plus a strict system prompt). Without this, the summarizer hallucinates content from global context — verified empirically and fixed in v0.2.0.
L2 and L3 use asyncRewake: true. When enrichment finishes after restore, a short delta surfaces as a system reminder mid-conversation.
Every summarizer invocation is claude -p against your OAuth credentials. On a Max-style subscription this draws from plan quota, not per-token dollars.
A daily budget cap (AMNESIA_DAILY_BUDGET_TOKENS, default 5 000 000 prompt bytes) auto-downgrades effort from max to medium when exceeded.
Per-call cost detail (verified 2026-05-24)
Per L2 / L3 / preempt call:
- ~33K Opus 4.7 cache-creation, ~21K cache-read, ~3K output tokens
- ~$0.20 informational (zero actually billed on subscription)
- ~45 s wall-clock, fully async
In a heavy week (say 20 compacts, ~50 summarizer calls counting L1/L2/L3/preempt): ~1–2M plan-quota tokens. Well under Max plan limits.
You rarely need these — amnesia works on its own. Power-user escapes:
| Command | When you would use it |
|---|---|
/amnesia:snapshot [focus] [--deep] | Force a high-fidelity handoff now, at a natural pause (preempt usually catches this). --deep runs the summarizer agent; default only sets a marker for the next L2 pass. |
/amnesia:recall <topic> | The agent post-compact says it does not remember something you know happened. |
/amnesia:status | Diagnose what amnesia holds for this project: last handoff, working-state size, recent compaction events, hook health. |
/amnesia:promote <fact> | Promote a permanent fact into project CLAUDE.md or auto-memory so it survives compaction natively. |
/amnesia:sessions [query] [--all-projects] | List or search archived handoffs for this project (or all projects). |
/amnesia:diff [--from <p>] [--to <p>] | Show what changed between the previous and current handoff. |
/amnesia:why <claim> | Trace a claim in the current handoff back to the JSONL transcript line that produced it. |
/amnesia:migrate [--dry-run | --execute] | Consolidate amnesia state from orphaned data roots into the active one. Default is dry-run. |
The plugin ships a read-only stdio MCP server (amnesia) — pure Python stdlib, no pip install. Model Context Protocol tools for agent-driven retrieval:
| Tool | What it does |
|---|---|
recall | Grep handoffs and archived working-state for a past detail (query, optional scope: current_project / all_projects) |
handoff_get | Fetch the active handoff markdown, or an archived one by session_id |
Verify with /mcp after install — you should see amnesia with those two tools.
| Env var | Default | Effect |
|---|---|---|
AMNESIA_EFFORT | max | Override the --effort level for summarizer calls |
AMNESIA_MAX_AGE_SECONDS | 86400 (24h) | Reject cross-session restore if the handoff is older than this |
AMNESIA_PREEMPT_THRESHOLD_BYTES | 2000000 (~2 MB) | Bytes since the most recent compact_boundary at which preempt fires |
AMNESIA_DAILY_BUDGET_TOKENS | 5000000 | Daily prompt-byte cap; exceeding it downgrades effort to medium |
AMNESIA_SUBAGENT_CONTEXT_BYTES | 3000 | Byte cap for subagent context injection |
AMNESIA_WS_MAX_LINES | 5000 | working-state.jsonl line cap before rotation |
AMNESIA_ARCHIVE_KEEP | 50 | Maximum entries in handoff/archive/ |
AMNESIA_SYNC_REMOTE | (unset) | Git remote URL; enables opt-in cross-machine pull/push of the data root |
- No cross-machine sync by default. Files are machine-local. Set
AMNESIA_SYNC_REMOTEfor opt-in git sync, or use your own rsync. - No vector DB, no daemon, no Chroma, no Bun worker. Bash, Python, native hooks, and
claude -p. Boring on purpose. - No general knowledge store. Cross-session facts belong in project
CLAUDE.mdor auto-memory, which already survive compaction natively. amnesia owns the acute compaction-survival slice. - No
/compactinterception. Slash commands are not hookable, so amnesia makes compaction survivable rather than trying to prevent it.
See DESIGN.md for the long-form rationale, the binary investigation that informed it, the empirical tests that corrected the v0.1.0 design, and citations into the Claude Code 2.1.150 source.
Full docs: https://88plug.github.io/amnesia/
See CONTRIBUTING.md for guidelines and CHANGELOG.md for release history.
Licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2).
You may use, copy, modify, and redistribute it for any purpose except a Competing Use — offering this software (or a substantially similar substitute) as a commercial product or service. Each released version automatically converts to the Apache License 2.0 on the second anniversary of its release date.
For commercial-use inquiries outside the Permitted Purpose: andrew@88plug.com.