Start here.
agent-recall gives your AI coding agent memory across sessions. Three minutes to install and feel the aha (save → close → restart). Another four to run every /recall subcommand once so the rest never feels foreign.
What you'll have when you're done
- Plugin installed, hooks wired
- One restart prompt saved
- A fresh session restored from it
- Every core
/recallsubcommand tried once
Install → save → restart
Four steps. The aha is step 4 — a fresh Claude Code session that already knows what you were doing. Using Codex or Gemini?
Install via marketplace
In any Claude Code session, paste this:
/plugin marketplace add ashrocket/agent-recall
Claude Code will prompt you to grant permissions:
┌─ Permission Request ──────────────────────────────┐ │ agent-recall wants to: │ │ • Read session transcripts │ │ • Write to ~/.claude/projects/<proj>/ │ │ • Register SessionStart, SessionEnd, Bash │ │ hooks │ │ │ │ [ Allow once ] [ Allow always ] [ Deny ] │ └───────────────────────────────────────────────────┘
Pick Allow always so hooks stay wired across all future sessions.
About the command name. Claude Code namespaces every plugin command, so the real command is /agent-recall:recall. Want the shorter /recall? Run this once:
/agent-recall:install-alias
Writes a personal ~/.claude/commands/recall.md that dispatches to the plugin. Delete that file any time to remove the shortcut. The rest of this guide uses /recall; substitute /agent-recall:recall if you skipped this step.
Verify
Run /recall. You should see an empty session list and a connection status:
> /recall ┌─ Recent sessions — <proj> (0 total) ─────────────┐ │ │ │ no sessions yet — finish one to populate │ │ │ └───────────────────────────────────────────────────┘ agent-recall ● connected ├─ Hooks ● SessionStart, SessionEnd, Bash ├─ Index ● ~/.claude/projects/<proj>/recall-index.json └─ Restarts ○ 0 saved (run /recall save to create one)
Empty is correct — sessions index at SessionEnd, restarts on /recall save.
Save your first session
When work is in progress and your context is getting long, run:
> /recall save ● Indexing session... ● 23 messages · 8 commands · 1 failure captured ● Distilling (stripping noise, keeping decisions) ● Saved → recall-restarts/payroll-bonus-fix.prompt Restart with: /recall restart
This is not a transcript dump — agent-recall strips tangents and keeps only decisions, files touched, and what to do next.
Restart in a fresh session
Close that session. Open a new Claude Code window in the same project:
> /recall restart ┌─ Saved restarts ──────────────────────────────────┐ │ 1. payroll-bonus-fix 5 min ago │ │ 2. auth-flow-refactor 2d ago │ │ 3. jwt-migration 4d ago │ └───────────────────────────────────────────────────┘ > /recall restart 1 ● Loading payroll-bonus-fix... Branch: feature/payroll-fix (2 commits ahead) Modified: src/payroll/bonus.ts, tests/bonus.test.ts Next: Fix rounding edge case on line 247 Risks: Confirm % vs flat-rate w/ product team ● Context restored. Continuing work.
Claude now knows what branch you're on, what's modified, what's next, and what risks are still open — without a single line of re-brief from you. Restart prompts load in the current session by default; use /recall restart --launch 1 only when you want a separate window.
- ✓
/recallshows your project and a session count of 1+ - ✓
/recall restartlisted a saved prompt and/recall restart 1loaded it cleanly - ✓ The fresh session knew your branch, modified files, and next step
All three? You've got the killer feature. Next: run every other /recall subcommand once so the rest stops feeling unfamiliar.
Every /recall subcommand, once.
You've done save and restart. Run each of these once, in order — by the end nothing in the cheat sheet is unfamiliar. Skip any card where the precondition isn't met yet; the mockup tells you what you'll see when it is.
/recall / list
When: any time you want to glance at what you've worked on. Now that you've saved one session, the list isn't empty anymore.
> /recall list ┌─ Recent sessions — <proj> (1 total) ─────────────┐ │ today payroll-bonus-fix 23 msgs 8 cmds │ └───────────────────────────────────────────────────┘
/recall last
When: you want full details of your most recent session — files, decisions, failures — without scrolling back through history.
> /recall last payroll-bonus-fix · 23 msgs · 8 cmds · 1 failure Topics: payroll, rounding, tests Files: src/payroll/bonus.ts tests/bonus.test.ts Decision: Use Number.EPSILON for float compare Failure: python3 bonus.py → ImportError
/recall <term>
When: "didn't I solve this last week?" Search messages, commands, files, and failures across every indexed session. Literal fragments like '.p8' and regex patterns like /.*\.p8/ work too; arbitrary misspellings simply search and return no matches.
> /recall payroll Searching 1 session... 1 match today payroll-bonus-fix → src/payroll/bonus.ts, tests/bonus.test.ts → "use Number.EPSILON for float compare"
/recall knowledge
When: something feels off and you suspect Claude is missing project context. Dumps the CLAUDE.md it has loaded — global and project.
> /recall knowledge CLAUDE.md ● loaded ├─ Global ● ~/.claude/CLAUDE.md (38 lines) └─ Project ● ./CLAUDE.md (12 lines) Top entries: • Screenshot context → ~/.ai-context/screenshots.md • User email → ashleyraiteri@gmail.com
/recall stats
When: curiosity. Skill and learning usage rolled up across all your sessions — gets interesting after a week or two.
> /recall stats Sessions: 1 Commands: 8 Failures: 1 Learnings: 0 pending · 0 approved Top skills: recall ●●●●● (5 uses)
/recall failures
Let's trigger one. Run this safe non-destructive failure first so there's something to look at:
$ cat /tmp/recall-demo-nope cat: /tmp/recall-demo-nope: No such file or directory
Then:
> /recall failures Recent failures (1 group) not_found · 1 occurrence $ cat /tmp/recall-demo-nope Tip: check the path exists; ls -la the parent dir
SOPs also fire inline when a failure matches a known pattern — you'll see them appear right under failing commands during normal work.
/recall learn
When: review proposed learnings before they get saved as permanent SOPs. On day one you'll typically see "0 pending" — that's normal. Here's what it looks like when patterns accumulate:
> /recall learn 2 pending learnings [1] git / SSH authentication failure Pattern: same HTTPS permission error × 3 Fix: switch git remote from HTTPS to SSH approve (a) / reject (r) / skip (s): a ✓ Saved to bucket: personal
Auto-proposed when a command fails 3+ times with the same error, or when a failed command is followed by a successful variant.
/recall cleanup
When: monthly hygiene. With no flags, it's a dry run — it tells you what would be pruned, changes nothing. Safe to run any time.
> /recall cleanup Cleanup analysis (no changes made) ○ Noise sessions (<3 msgs, no failures): 0 ○ Sessions with sensitive data: 0 ○ Stale .jsonl files (>30d): 0 ○ Duplicate failure patterns: 0 Run /recall cleanup --all when you're ready to execute.
/recall help any time to see the same command surface in your agent.If something didn't behave like the mockup, jump to troubleshooting. Otherwise you're set — keep working, run /recall save when a session gets long, and /recall restart when you open a fresh one.
Using a different agent?
No marketplace yet on those — clone the repo and add one snippet to your project's AGENTS.md or GEMINI.md. Once installed, steps 2-4 of the speedrun and the tour above all apply unchanged — same /recall commands, same index.
Codex CLI
1. Clone the repo to a stable location:
git clone https://github.com/ashrocket/agent-recall ~/.agent-recall
2. Append this to your project's AGENTS.md (or copy the repo's version):
## Session memory (agent-recall) At session start: ```bash ~/.agent-recall/hooks/scripts/session-start \ "$PWD" 2>/dev/null ``` At session end: ```bash python3 ~/.agent-recall/hooks/scripts/codex_session_end.py \ --latest "$PWD" 2>/dev/null ```
Then open Codex in your project. Update later with cd ~/.agent-recall && git pull.
Gemini CLI
1. Clone the repo (same as Codex):
git clone https://github.com/ashrocket/agent-recall ~/.agent-recall
2. Append to your project's GEMINI.md:
## Session memory (agent-recall) At the start of each session, run and include the output as context: ```bash ~/.agent-recall/hooks/scripts/session-start \ "$PWD" 2>/dev/null ```
Gemini reads GEMINI.md automatically. Same shared index as Claude Code and Codex.
One index, all agents
Both Claude Code and Codex write to the same path. Save in one, restart in the other.
├─ recall-index.json ● searchable session index ├─ recall-restarts/ ● saved restart prompts └─ *.jsonl ● raw session files
Save in Claude Code →
restart in Codex. Or Gemini. Or back to Claude Code on another machine.
The same hooks
SessionStart loads prior context. SessionEnd indexes what happened. PostToolUse:Bash catches failures.
Privacy by default
Everything stays on your machine in ~/.claude/projects/. No cloud unless you opt in.
Troubleshooting
Hooks not firing (Claude Code)
agent-recall ◐ partial
├─ Hooks ○ not firing
└─ Restarts ○ 0 saved
Check /config → hooks lists agent-recall. Restart Claude Code after install.
"No sessions yet"
Sessions index at SessionEnd — close + reopen to trigger. Confirm ~/.claude/projects/<proj>/recall-index.json exists.
Codex: script not found
ls ~/.agent-recall/hooks/scripts/ to confirm path. Re-clone if missing.
Want to wipe and start over?
/recall cleanup --all prunes noise without nuking restarts. Restart prompts live in recall-restarts/ — delete by hand.
The agent-* toolkit
Three small tools, same visual language, same bias: stop dragging context around by hand.