Get started in 60 seconds

Start here.

agent-recall gives your AI coding agent memory across sessions. Install once, then /recall save at the end and /recall restart in the next session picks up right where you left off — no ten-minute re-brief.

Claude Code Codex CLI Gemini CLI

install → verify → save → restart

What you'll have when you're done

Auto-indexed sessions
Searchable failure patterns
One-shot session restore
Shared history across agents

no goldfish brain.

Path A · Claude Code

Install the plugin

One command. Hooks wire up automatically. You're done before the coffee finishes brewing.

recommended

1

Install via marketplace

In any Claude Code session, paste this:

claude code prompt

/plugin marketplace add ashrocket/agent-recall

Claude Code will prompt you to grant permissions:

permission request

┌─ 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.

2

Verify

Run /recall. You should see an empty session list and a connection status:

claude code session

> /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.

3

Save your first session

When work is in progress and your context is getting long, run:

/recall save

> /recall save

  ●  Indexing session...
  ●  23 messages · 8 commands · 1 failure captured
  ●  Distilling (stripping noise, keeping decisions)
  ●  Saved → 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.

4

Restart in a fresh session

Close that session. Open a new Claude Code window in the same project:

new claude code session

> /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.

5

Watch for failure SOPs

When a bash command fails against a known pattern, agent-recall fires the fix in-line:

post-tool-use:bash hook

$ git push origin feature/auth
  ERROR: remote: Permission to repo.git denied (HTTPS)

  ─── recall SOP · git_error ─────────────────────────
   You've hit this 3× this month.
   Fix:  git remote set-url origin git@github.com:org/repo.git
   Why:  HTTPS tokens expire; SSH keys don't.
  ────────────────────────────────────────────────────

SOPs build automatically from past failures. Review proposed learnings any time with /recall learn.

Path B · Codex CLI

Wire it through AGENTS.md

Codex doesn't have a plugin marketplace yet — instead, you clone the repo and wire two commands into your project's AGENTS.md.

also great

1

Clone the repo

Drop the agent-recall source somewhere stable — your home directory is the convention:

terminal

git clone https://github.com/ashrocket/agent-recall ~/.agent-recall

verify

agent-recall  ●  cloned
├─ Location    ●  ~/.agent-recall
└─ Hooks       ○  not wired — see step 2

2

Wire AGENTS.md

Copy the repo's AGENTS.md into your project root, or append this block to an existing one:

AGENTS.md (project root)

## Session memory (agent-recall)

At session start:
```bash
python3 ~/.agent-recall/hooks/scripts/session-start.py "$PWD" 2>/dev/null
```

At session end:
```bash
python3 ~/.agent-recall/hooks/scripts/codex_session_end.py --latest "$PWD" 2>/dev/null
```

Codex reads AGENTS.md automatically and runs these at the right moments.

3

Open a Codex session

Start Codex in your project directory. You should see the session-start hook fire:

codex session start

agent-recall  ●  connected
├─ Hooks       ●  start + end wired via AGENTS.md
├─ Index       ●  ~/.claude/projects/<proj>/recall-index.json
└─ Restarts    ○  0 saved

Note: Claude Code, Codex, and Gemini all write to the same index location — your history is unified.

4

Save + restart

Identical to Claude Code. From inside Codex:

codex session

> /recall save

  ●  Indexing session...
  ●  Saved → restarts/codex-refactor.prompt

# later, in a fresh session:
> /recall restart 1

  ●  Loading codex-refactor...
  ●  Context restored.

5

Keep it updated

Pull updates whenever you want the latest hooks and SOPs:

terminal

cd ~/.agent-recall && git pull

agent-recall  ●  up to date
└─ Last sync   ●  just now

Cross-platform sync

One index, all agents

Both Claude Code and Codex write to the same path. Save in one, restart in the other.

use whatever's open

~/.claude/projects/<project-slug>/

├─ recall-index.json    ●  searchable session index
├─ 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.

history is portable

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.

Cheat sheet

Every /recall command

All subcommands route through /recall.

Command	What it does
/recall	List recent sessions
/recall <term>	Search past sessions by keyword
/recall last	Full details of the previous session
/recall failures	Recurring error patterns and learnings
/recall learn	Review auto-proposed learnings from failures
/recall save	Distill + save current session as restart prompt
/recall restart	List saved restart prompts
/recall restart <n>	Resume from saved prompt #n
/recall restart <text>	Resume by fuzzy text match
/recall cleanup --all	Prune noise from the session index
/recall stats	Skill and learning usage stats
/recall knowledge	Show CLAUDE.md contents (global + project)

Also supported · Gemini CLI

Using Gemini CLI?

Same shape as Codex — clone the repo, add a snippet to your project's GEMINI.md, and you're done.

GEMINI.md (project root)

## Session memory (agent-recall)

At the start of each session, run and include the output as context:
```bash
python3 ~/.agent-recall/hooks/scripts/session-start.py "$PWD" 2>/dev/null
```

If something looks off

Troubleshooting

read it back

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. Restarts live in restarts/ — delete by hand.