Hindsight memory

Hindsight Memory

Hindsight is a semantic long-term memory system. This plugin wires Claude Code to a Hindsight server (external API) so that relevant memories are recalled before every prompt and the conversation is retained after every turn — and gives you a vocabulary for driving that memory by hand when you want to.

The transport is the installed hindsight CLI (verify with hindsight version). It already knows the API endpoint from HINDSIGHT_API_URL / HINDSIGHT_API_KEY or a named profile, so every command below "just works" against your server.

How the automatic memory works

Three hooks (in hooks/hooks.json) run with no action from you:

Hook	Event	Script	What it does
Recall	UserPromptSubmit	scripts/recall.py	Queries the bank for memories relevant to your prompt and injects them as an invisible <hindsight_memories> block — Claude sees them, the chat does not.
Retain	Stop (async)	scripts/retain.py	Reads the transcript, strips any injected <hindsight_memories> block, and stores it under a deterministic per-session document id.
Health	SessionStart	scripts/session_start.py	Silent reachability check; logs only with debug on.

Every hook fails open: if the server is slow or unreachable, the turn is never blocked and no error reaches you. The recall budget defaults to mid and the query is capped, so latency stays bounded.

The single most important invariant: retain strips the recalled-memory block before storing. Without it the bank would ingest its own prior recalls as new memories — a compounding feedback loop. See references/memory-model.md.

Manual interaction (the common moves)

Default bank is claude_code (override with HINDSIGHT_CC_BANK_ID).

# Recall — semantic search over memories (what the prompt hook calls)
hindsight memory recall claude_code "decisions about the retain doc-id" --budget mid

# Reflect — a synthesized ANSWER in the bank's voice, not just a list of hits
hindsight memory reflect claude_code "what have I decided about plugin versioning?"

# Retain — store a single fact/decision deliberately
hindsight memory retain claude_code "Chose lean CLI-backed port over full Python port for the skillstack hindsight plugin" -c claude-code

# List / inspect
hindsight bank stats claude_code
hindsight memory list claude_code
hindsight entity list claude_code

recall returns ranked hits (text, type, mentioned_at); reflect reasons over them and answers. Use reflect when you want a conclusion, recall when you want the raw evidence. Full command surface: references/cli-reference.md.

When to reach for this skill

✅ Use for:

• "What do I remember / what did I decide about X" → recall or reflect
• Deliberately saving a durable fact or decision → retain
• Checking memory is healthy or seeing what a bank holds → health, bank stats
• Curating memory: entities, mental-models, directives, missions
• Explaining or tuning the auto-recall / auto-retain hooks

❌ NOT for:

• Recalling something said earlier this session — it's already in context
• Finding code, symbols, or callers → use CodeGraph / Semble / grep
• Designing a memory architecture or comparing frameworks → use memory-systems
• Generic web/doc lookup → use the research/docs skills

Configuration (environment variables)

All knobs are namespaced HINDSIGHT_CC_* so they never clash with the CLI's own HINDSIGHT_* variables. Defaults are production-sane; change nothing to start.

Var	Default	Purpose
HINDSIGHT_CC_BANK_ID	claude_code	Bank to recall from / retain to
HINDSIGHT_CC_AUTO_RECALL	true	Master switch for the recall hook
HINDSIGHT_CC_AUTO_RETAIN	true	Master switch for the retain hook
HINDSIGHT_CC_RECALL_BUDGET	mid	low / mid / high — latency vs thoroughness
HINDSIGHT_CC_RECALL_MAX_TOKENS	1024	Cap on the injected memory block
HINDSIGHT_CC_RECALL_TYPES	world,experience	Fact types to recall
HINDSIGHT_CC_RETAIN_TOOL_CALLS	true	Include tool calls in retained transcript
HINDSIGHT_CC_PROFILE	(none)	Named CLI profile to pass as -p
HINDSIGHT_CC_CLI_BIN	(PATH)	Explicit path to the hindsight binary
HINDSIGHT_CC_DEBUG	false	Log [Hindsight] lines to stderr

The plugin assumes an external Hindsight API (the CLI's configured endpoint). It does not start a local daemon or manage an LLM provider — the server handles fact extraction.

Anti-pattern: retaining the recalled-memory block

Symptom: the bank fills with near-duplicate memories that echo earlier recalls; recall quality degrades over sessions as the same facts pile up.

Problem: the recall hook injects a <hindsight_memories> block into the prompt. If a retain step stores the raw transcript, that block is ingested as brand-new content. Next session it is recalled and re-injected, then re-stored — a feedback loop that poisons the bank with its own output.

Solution: always strip <hindsight_memories> / <relevant_memories> blocks before retaining (this plugin does it in scripts/lib/transcript.py:strip_memory_tags, exercised by tests/test_transcript.py). If you write your own retain path, strip first — it is non-negotiable, not an optimization.

Anti-pattern: blocking the turn on a slow server

Symptom: prompts hang for seconds; sessions stall when the network is poor.

Problem: a recall hook that raises or waits indefinitely makes Hindsight a hard dependency of every keystroke.

Solution: the recall hook is fail-open with a tight timeout and a bounded budget — any error or timeout yields zero injected context and exit 0. Keep it that way; never make memory a blocking dependency of the prompt.

References

• references/cli-reference.md — full hindsight command surface used here
• references/memory-model.md — banks, fact types, entities, observations, mental models, directives