0.21.0: recall meta-skill — cross-session memory via sessions.jsonl index

[Nowhitestar]

Why

Telegram bot sessions die on quota cuts / daily restart / MCP disconnect, and the next session has zero memory of what was discussed. The transcript is on disk at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl — we just need an index and a retrieval protocol to make it usable as memory.

What

New meta-skill recall with four operations, wired into the existing heartbeat/sleep/Session-Start mechanism. Pure markdown, no new code.

Op	Trigger	Job
Begin	CLAUDE.md Session Start step 3	Register session_id in memory/sessions.jsonl (idempotent, fast, silent)
Update	HEARTBEAT.md hourly	Refresh topic + summary for the live session
Backfill	SLEEP.md nightly	Pass 1 — index every unindexed JSONL (catch-up); pass 2 — refresh sessions ≤48h old whose summary/ended is null (crash safety net); aging — rows with ended >90 days move to memory/sessions.archive.jsonl
Search	User references past chat / /zero-claw:recall <query>	grep index → grep inside JSONL → read ±20-line windows around anchors → surface as prose. Default = relevant slice, not full transcript

Index row

{"session_id":"abc-123","started":"2026-05-06T14:30Z","ended":"2026-05-06T15:45Z","topic":"session 恢复设计","summary":"用户提出 session 中断失忆问题；定了用 recall meta-skill 索引 sessions.jsonl。"}

topic / summary are free-form, user's language, no length policing.

Search example

User: "我们之前聊过 telegram session 中断的问题"

1. Keywords → grep sessions.jsonl → 1 hit (session abc-123).
2. grep inside ~/.claude/projects/.../abc-123.jsonl for keywords → anchor lines [12, 47, 93].
3. Read ±20 window around each, dedupe overlaps → ~100 lines pulled (vs full transcript at 5k+).
4. Surface as prose: "在 5/6 那次 session 你说 telegram 经常被中断，我们定了用 recall meta-skill 加索引……要从这里继续吗？"

Multiple candidates → ask which one. No specific keyword → fall back to last 100 lines + first 30. Full transcript only on explicit "把整段拉出来".

Files changed

New

• skills/recall/SKILL.md — full Begin/Update/Backfill/Search protocol + JSONL atomic-write pattern + failure modes
• commands/recall.md — /zero-claw:recall <query>|backfill|list

Modified

• template/CLAUDE.md — Session Start step 3 (Begin) + new "Session Recall" section
• template/HEARTBEAT.md — hourly recall Update
• template/SLEEP.md — nightly recall Backfill + aging
• skills/upgrade-meta-skill/SKILL.md — recall added to meta-skill list (so existing bots get it via /zero-claw:upgrade-meta-skill)
• package.json / .claude-plugin/plugin.json / .claude-plugin/marketplace.json — 0.20.7 → 0.21.0

Test plan

• Fresh bot install: Session Start writes a row to memory/sessions.jsonl; heartbeat fills topic/summary; manual /zero-claw:recall list shows it
• Existing bot upgrade path: /zero-claw:upgrade (template files) + /zero-claw:upgrade-meta-skill (recall skill) → first sleep runs Backfill catch-up across historical JSONL files
• Search: in a new session, reference an old topic by keyword → relevant slice surfaces, full transcript NOT pulled
• Multi-candidate Search: keyword that hits 3+ sessions → bot lists them and waits for user to pick
• Aging: row with ended >90 days → next sleep moves it to memory/sessions.archive.jsonl; archive falls through on Search miss
• Crash safety: kill bot mid-session before any heartbeat → next sleep's Backfill writes the missing summary by reading the orphan JSONL

🤖 Generated with Claude Code

[Nowhitestar]

Heads-up: I've merged this branch into my fork's main so I can keep iterating on the recall skill locally without blocking on review here. The PR stays open as an upstream contribution offer — no urgency on your side.

If you'd like to take it, the diff is unchanged and ready to merge as-is. If you'd prefer changes (naming, scope, or splitting it up), happy to revise. If it's not the direction you want for zero-claw, feel free to close — I'll continue in my fork.