convez.ai
Skill
rocketmandrey

claude-recall

rocketmandrey/claude-recall

Ver no GitHub
InicialPluginScore · de 0 a 100

Session memory & orchestration for Claude Code: one index of all your sessions, three modes — finish / handoff / spawn

Instalação

$npx convez-ai rocketmandrey/claude-recall

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.5.3
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

claude-recall

Russian / Русский | Chinese / 中文

Claude Code License: MIT Version Zero deps macOS

Your hundreds of past Claude Code sessions stop being a graveyard: say "find the session where I exported that client's deals" — and in a second you have the project, the method, the link to the finished artifact, and three ways to act on it.

How it works: every finished session is distilled by a small LLM (haiku) into a recap card; all cards roll up into one greppable INDEX.md — the single touchpoint for you and your agents. A bundled skill teaches any Claude Code session to search it and resume past work.

Zero dependencies — one Python file, no API keys (uses your existing claude auth).

SESSION ENDS        → SessionEnd hook        → recap card (+ handoff if enabled)
RECAPPER (haiku)    → distills into a card   → ~/.claude/session-recaps/<id>.md
INDEX               → one line per session   → INDEX.md  ← the single touchpoint
ORCHESTRATOR (skill)→ find → show → finish | handoff | spawn

OPT-IN: CONTINUITY  → PreCompact hook writes a fresh HANDOFF (task / done /
LOOP                  in flight / next / gotchas) → SessionStart re-injects it —
                      the session wakes up knowing exactly where it left off

A recap card is ten lines of YAML:

id: c2631a96-...
project: ~/Documents/Cursor/my-crm
task: Export deals of dismissed logist Ivanova to a Google Sheet for the sales lead
status: done
method: skill export-dismissed + Sheets API
entities: [Ivanova, Bitrix]
artifacts: [https://docs.google.com/spreadsheets/d/...]
next: null

Three interaction modes

modeyou saywhat happens
finish"do that export again, for client X"Claude finds the past session, extracts project + method, redoes the task right here
handoff"give me the command"recall cmd <id> → cd "<project>" && claude --resume <id>
spawn"open that session"recall open <id> — a new terminal window opens with the session restored

When several sessions match, the orchestrator doesn't guess — it shows a selector (project folder + date + task context per candidate, plus a "dig deeper" option).

Sessions name themselves

Every recap (and every handoff, if the loop is on) also titles the session folder/project · task — via the exact mechanism /rename uses — so the claude --resume picker stops being a wall of "no name". The title refreshes as the task evolves. Names you set by hand are never overwritten; set one explicitly with recall rename <id8> <title>; disable with RECALL_AUTONAME=0.

Installation

Paste this into Claude Code:

Clone github.com/rocketmandrey/claude-recall and run ./install.sh. Ask me whether to enable the optional handoff loop, show me what it changed, then ask me whether to run recall backfill (one small-LLM call per past session, ~20–40 min for a few hundred).

Or manually:

git clone https://github.com/rocketmandrey/claude-recall.git && cd claude-recall
./install.sh              # CLI + skill + SessionEnd hook + permissions
recall backfill           # optional: index your past sessions

install.sh merges into ~/.claude/settings.json (never overwrites): the SessionEnd hook and Bash(recall *) permissions, so agents can call recall in any new session without prompts. From then on every finished session (≥15 events) is indexed automatically.

The handoff continuity loop is opt-in — the installer offers it (and never forces it): before every context compaction a small LLM writes a state card, re-injected after compact/resume, so the session wakes up knowing where it left off. Cost: one haiku call per compaction. Flags: ./install.sh --with-handoff / --no-handoff (no flag → the installer asks; a previous choice is kept on reinstall). Verify anytime with recall doctor.

Usage

Just say in Claude Code:

English:

  • "find the session where I exported those deals"
  • "we've done this before — do it again for client X"
  • "open the session where we built the dashboard"
  • "what do I have unfinished?"

Русский:

  • «найди сессию, где я выгружал сделки»
  • «мы это уже делали — сделай ещё раз по клиенту X»
  • «открой сессию, где мы пилили дашборд»
  • «что у меня висит недоделанного?»

中文:

  • "找到我导出交易数据的那个会话"
  • "我们以前做过这个 — 再为客户X做一次"
  • "打开我们做仪表盘的那个会话"
  • "我还有哪些没做完的任务?"

Examples

EN — repeat a past task:

Do that dismissed-employees export again, but for Svetlana's regulars

RU — открыть прошлую сессию в новом окне:

Открой сессию, где мы настраивали деплой — прям окошком

ZH — 查询过去的决定:

我们当时关于部署方案是怎么决定的?

Repository structure

claude-recall/
├── bin/recall              ← the whole product: one Python file, zero deps
├── skill/SKILL.md          ← session-orchestrator skill for Claude Code
├── install.sh              ← installer: CLI + skill + hook + permissions
└── docs/                   ← README translations (RU, ZH)

CLI

commandwhat it does
recall find <query...>search the index (case-insensitive OR; search by word STEM)
recall grep <query...>full-text search across raw transcripts (fallback when the index is silent)
recall show <id8>print a session's recap card
recall cmd <id8>print the resume command (handoff)
recall open <id8> [--fast] [--tab]open the session in a new terminal window (spawn); writes its missing handoff card first unless --fast; --tab opens a tab instead
recall remove <id8>forget a session: card + index line + tombstone
recall rename <id8> <title...>set a session's display name by hand (auto-naming then leaves it alone)
recall handoff <file.jsonl>write a handoff card (in-flight state) for a session
recall handoff --allretro-sweep: handoff cards for recent sessions lacking one [--days N] [--jobs N]
recall backfillindex existing sessions [--days N] [--min-events N] [--jobs N]
recall indexindex stats
recall doctorcheck installation

Env: RECALL_DATA (default ~/.claude/session-recaps), RECALL_MODEL (default haiku), RECALL_TERMINAL (Terminal|iTerm), RECALL_MIN_EVENTS (default 15), RECALL_HANDOFF_DAYS (default 30 — handoff retention), RECALL_AUTONAME (default 1 — auto-title sessions; 0 to disable), RECALL_TAB (1 — recall open defaults to tabs; per-call override: --window).

Requirements & notes

  • macOS (recall open uses AppleScript; Linux PRs welcome), python3 ≥ 3.9, logged-in claude CLI.
  • Local-first: cards and the index never leave your machine. They do contain distilled session content — don't commit or share the data dir.
  • Recap calls go through claude -p — your existing auth, no API key. Worker sessions are marked and never index themselves.
  • recall remove tombstones a session so hook/backfill won't resurrect it (undo: recall recap <transcript> --force).
  • Handoff cards (if the loop is enabled) are a few KB each and auto-pruned after 30 days; long-term memory lives in the recap cards. A session resumed via recall open gets its handoff re-injected automatically — it wakes up knowing its next steps. Older sessions without a card get one written on open (~30s; --fast to skip), or retro-sweep them all: recall handoff --all --days 14.
  • If the index draws a blank, recall grep does full-text search over your raw transcripts in ~/.claude/projects/ — no extra tools needed.
  • Tabs: in iTerm recall open --tab is native and reliable, and each tab is colored by project (iTerm OSC-6) so a vertical tab bar groups same-project sessions by stripe — put the tab bar on the left via iTerm → Settings → Appearance → Tab bar location. Terminal.app has no tab API, so recall emulates ⌘T via System Events (best-effort: needs the Accessibility permission, and scripted ⌘T can still be dropped depending on focus) — it verifies a tab actually appeared and otherwise opens a window, so it never injects the command into a busy tab. For guaranteed, color-coded tabs, use iTerm.

Acknowledgements

recall grew out of daily use of codbash by Valerii Kovalskii — a dashboard + full-text search across AI coding sessions. recall contains none of its code and doesn't depend on it, but the idea of treating past sessions as a searchable asset comes from living with codbash, and recall grep is a deliberately minimal nod to what codbash does at full scale (web dashboard, cross-agent session sync). For the full experience, get codbash. Respect, Valera.

License

MIT

Ver o original no GitHub

Bom para

Relacionados