Start here.
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?
Install via marketplace
In any Claude Code session, paste this:
/plugin marketplace add ashrocket/recall
Claude Code will prompt you to grant permissions:
┌─ Permission Request ──────────────────────────────┐ │ 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 /recall:recall. Want the shorter /recall? Run this once:
/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 /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 │ │ │ └───────────────────────────────────────────────────┘ 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 — 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 → you@example.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 there yet — clone the repo and add one snippet to your project's AGENTS.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/recall ~/.recall
2. Append this to your project's AGENTS.md (or copy the repo's version):
## Session memory (recall) At session start: ```bash ~/.recall/hooks/scripts/session-start \ "$PWD" 2>/dev/null ``` At session end: ```bash python3 ~/.recall/hooks/scripts/codex_session_end.py \ --latest "$PWD" 2>/dev/null ```
Then open Codex in your project. Update later with cd ~/.recall && git pull.
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 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)
recall ◐ partial
├─ Hooks ○ not firing
└─ Restarts ○ 0 saved
Check /config → hooks lists 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 ~/.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.