Hindsight Memory

Persistent personal memory layer via Hindsight — semantic search, mental models, retention

Entry points

• work_buddy.memory

Details

Persistent personal memory layer for building a digital twin. Captures soft personal context (preferences, habits, emotional state, recurring patterns) that artifacts systematically miss.

Two integration paths share one local Hindsight server: 1. Claude Code plugin (hooks) — ambient auto-recall before every prompt, auto-retain after responses. 2. Python adapter (work_buddy/memory/) — programmatic retain/recall/reflect for context collection, workflows, and MCP gateway capabilities.

Cost: Every retain call costs LLM tokens (Anthropic API key required). recall is cheap (embedding search). reflect also costs tokens.

Bank: One personal bank (user by default, configurable via hindsight.bank_id in config). Tag taxonomy: user:default, source:, kind:, domain:, workflow:, session:*. Observations (automatic pattern consolidation) and mental models (pre-computed reflect summaries) build up the digital twin.

Server requirements: hindsight-api-slim (server, Poetry), hindsight-client (SDK, Poetry), external PostgreSQL with pgvector. Env vars: HINDSIGHT_API_LLM_PROVIDER, HINDSIGHT_API_LLM_API_KEY, HINDSIGHT_API_LLM_MODEL.

Starting: HINDSIGHT_API_LLM_PROVIDER=anthropic HINDSIGHT_API_LLM_API_KEY=$ANTHROPIC_API_KEY HINDSIGHT_API_LLM_MODEL=claude-haiku-4-5-20251001 hindsight-api

MCP capabilities: memory_read (semantic + keyword search), memory_write (store a fact/preference/constraint), memory_reflect (LLM-powered reasoning over memories, consent-gated), memory_prune (delete memories, consent-gated, irreversible).

Bank bootstrap: Call ensure_bank() from work_buddy.memory.setup to create the bank with missions, directives, and mental models. Idempotent.