| name | hindsight |
| description | Persistent agent memory via self-hosted Hindsight. Retain knowledge, recall context, reflect on patterns. Includes multi-bank routing architecture for agent orgs. |
| pipeline-status | ["new"] |
Hindsight Memory (Self-Hosted)
Persistent, structured memory via the official Hindsight CLI (v0.4.14). Store knowledge during tasks, recall context before starting new ones, reflect to synthesize patterns.
Bank Detection
Auto-detect bank from git repo name:
BANK=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "general")
Or use the helper: BANK=$(./scripts/hs-bank-id.sh)
CLI Config
- Binary:
hindsight at ~/.local/bin/hindsight (official v0.4.14)
- Config:
~/.hindsight/config (TOML: api_url, api_key)
- Endpoint:
https://api.hs.delo.sh (resolves to localhost via /etc/hosts)
- Reconfigure:
hindsight configure --api-url <url> --api-key <key>
Core Operations
Retain (store knowledge)
hindsight memory retain $BANK "npm test requires --experimental-vm-modules" \
--context "debugging"
Context categories: architecture, conventions, debugging, deployment, dependencies, preferences, session-summary, code-edit
With document tracking (same doc-id = upsert, replacing old facts):
hindsight memory retain $BANK "Project deadline extended to April 15" \
--context "conventions" --doc-id "sprint-notes-2026-03"
Recall (retrieve context)
hindsight memory recall $BANK "What testing patterns does this project use?"
With options:
hindsight memory recall $BANK "How are auth and session management connected?" \
--budget high --max-tokens 8192 --fact-type world,observation
Budget levels: low (fast, shallow), mid (balanced, default), high (deep graph traversal)
JSON output for programmatic use:
hindsight memory recall $BANK "query" -o json | jq '.results[].text'
Reflect (synthesize with agentic reasoning)
Reflect runs an agentic loop: autonomously searches memories, applies bank disposition, generates grounded response with citations.
hindsight memory reflect $BANK "What architectural decisions have shaped this project?"
With context and higher budget:
hindsight memory reflect $BANK "Should we migrate to event sourcing?" \
--context "architecture review" --budget high
Response includes based_on.memories, based_on.mental_models, based_on.directives for citation traceability.
Mental Models (pre-computed reflect responses)
Mental models are curated summaries checked first during reflect. Faster, more consistent answers for recurring topics. Top of the retrieval hierarchy.
Name and source-query are positional, not flags (--name / --source-query
do not exist and error out):
hindsight mental-model create $BANK "Project Architecture" \
"What is the overall system architecture?" --id project-architecture
hindsight mental-model list $BANK
hindsight mental-model get $BANK <id>
hindsight mental-model refresh $BANK <id>
hindsight mental-model history $BANK <id>
hindsight mental-model delete $BANK <id>
Content generates asynchronously — a fresh model shows Generating content...
for a few seconds. Pass --id so the model has a stable, memorable handle.
When to create one. A mental model earns its place when a question recurs
and its answer is assembled from many scattered facts — "how does X work
here", "where do I add Y", "what fails silently". Retain the underlying facts
first; the model is computed from the bank, so an empty bank yields an empty
model. refresh after retaining new facts on that topic, or the model quietly
serves a stale answer with full confidence — the one real failure mode here.
Directives (hard rules for reflect)
Always-enforced rules during reflect. Unlike disposition (soft personality influence), directives are strict behavioral constraints.
hindsight directive create $BANK \
--name "Code Style" \
--content "Always recommend Python type hints and strict typing"
hindsight directive list $BANK
hindsight directive update $BANK <directive_id> --active false
hindsight directive delete $BANK <directive_id>
Documents (source tracking)
Documents track where memories came from. Re-retaining with the same doc-id replaces old facts (upsert). Deleting a document removes all its extracted memories.
hindsight document list $BANK
hindsight document get $BANK <document_id>
hindsight document delete $BANK <document_id>
Bank Management
hindsight bank list
hindsight bank stats $BANK
hindsight bank disposition $BANK
hindsight bank disposition $BANK --skepticism 4 --literalism 3 --empathy 2
hindsight bank mission $BANK "Extract technical facts, conventions, and decisions."
Disposition (Personality Traits)
Three traits (1-5 scale) that influence reflect behavior:
| Trait | Low (1) | High (5) |
|---|
| Skepticism | Trusting, accepts claims | Questions and doubts claims |
| Literalism | Flexible interpretation | Exact, literal interpretation |
| Empathy | Detached, fact-focused | Considers emotional context |
Retrieval Hierarchy (during reflect)
- Mental Models - User-curated summaries (highest priority)
- Observations - Consolidated knowledge (auto-generated from retained facts)
- Raw Facts - Ground truth memories (world, experience, observation types)
Fact Types
- world - Objective facts ("Alice works at Google")
- experience - Conversational events ("User asked about deployment")
- observation - Consolidated patterns (auto-synthesized from multiple facts)
Multi-Bank Routing Architecture
For multi-agent or multi-project setups, use domain-first routing to prevent cross-project pollution and recall noise.
Strategy
- Primary bank = domain/product (source of truth). Example:
wean, chorescore, 33GOD
(exact case — 33god/33god-core/33god-infra were consolidated into 33GOD
and deleted 2026-08-17; naming one silently creates a NEW empty bank)
- Secondary bank(s) = role/hierarchy overlay. Example:
exec-office for leadership decisions
- Global fallback bank. Example:
33GOD for org-wide context
Never make an agent-named bank the canonical store for project facts — a
repo's truth must stay readable by every agent that works it, and an agent bank
would hide it. That is a rule about canonical project memory, and it is not a
ban on agent banks.
The two namespaces (identity vs. project)
Agent banks have their own distinct job, and the two namespaces are disjoint by
design — they answer opposite questions and must not be collapsed:
| agent-<profile> | <repo> |
|---|
| Anchored to | agent identity | repository |
| Path-dependent | no — follows the agent everywhere | yes |
| Written | automatically, by the Hermes memory provider | explicitly, via this CLI |
| Audience | that agent alone | every agent on the repo |
| Answers | "which projects has this agent worked on?" | "which agent experienced this fact?" |
Hermes wires the identity bank through memory.bank_id_template: agent-{profile} in ~/.hermes/config.yaml; {profile} resolves to the agent's
identity, never to cwd. Project banks are resolved per-repo by Bank
Detection above.
Routing test when retaining: would another agent on this repo need this?
Yes → repo bank (and name yourself in the content, so provenance survives).
Only true of you → identity bank.
Routing Pattern
For each agent/session:
- Resolve writeBank (where new memories are retained)
- Resolve recallBanks[] (ordered primary -> secondary -> fallback)
- On prompt build, recall from each bank and merge results
- On run end/reset/tool-error, retain high-signal facts into writeBank
Capture Policy (high signal only)
Retain automatically for:
- Explicit memory intent ("remember", "don't forget", preferences)
- Post-run user facts/decisions
- High-level architectural patterns
- Pre-reset session summaries
- Non-standard system paths/configs
- Tool errors (debugging context)
Do NOT retain:
- Cron/noise/system spam
- Tiny one-word messages
- Slash commands
Failure Modes
| Symptom | Cause | Fix |
|---|
| Cross-project pollution | writeBank too broad | Tighten routing to domain bank |
| Recall noise | Too many recallBanks or topK too high | Cap at 3-4 banks |
| Missed intent | Memory-intent regex too strict | Expand capture triggers |
| Latency spike | Recalling too many banks per prompt | Reduce recallBanks count |
When to Retain
- Discovered a bug fix or workaround
- Found a project convention or pattern
- Learned a user preference
- Completed a significant task (summarize what was done)
- Found something that didn't work (negative knowledge is valuable)
When to Recall
- Before starting any non-trivial task
- When working in an unfamiliar area of the codebase
- When making architectural or tooling decisions
- When the user asks about past work or patterns
Best Practices
- Be specific: "npm test requires --experimental-vm-modules" not "tests need a flag"
- Include outcomes: Store what worked AND what didn't
- Use context categories: Tag with the right context for better retrieval
- Recall first: Check for relevant context before starting work
- Don't duplicate: Check if knowledge already exists before retaining
- Use document_id: Group related session facts so they compound, not duplicate
- Create mental models: For topics you reflect on repeatedly
- Use directives: For hard rules that must always be enforced during reflect
OpenClaw Plugin Integration
The local OpenClaw plugin (workspace/.openclaw/extensions/hindsight-memory/) automates capture and recall so agents don't need to manually call hindsight. Config lives in openclaw.json under plugins.entries.hindsight-memory.
What the plugin automates
| Hook | Behavior |
|---|
before_prompt_build | Auto-recall from resolved banks, inject as context |
message_received | Capture explicit memory intent ("remember", "prefer", "always", "never") |
agent_end | Capture high-signal user messages from the run |
before_reset | Summarize last 16 messages before /new clears context |
before_compaction | Snapshot first 20 messages (initial requirements, arch decisions) before compression |
session_end | Capture session summary with git diff stats |
after_tool_call | Capture tool errors as debugging context |
Routing resolution order
The plugin resolves writeBank and recallBanks per-request through layered routing:
- Start with
defaultBank + globalRecallBanks
- Apply
agentRoutes[agentId] override
- Apply
sessionPrefixRoutes (longest-prefix match on session key)
- Apply
workspaceRoutes (substring match on workspace dir)
- Apply
channelRoutes (exact match on channel ID)
- Dedupe and cap at
maxRecallBanks (default: 4)
Noise filtering
The plugin skips: messages < 24 chars, slash commands, system messages, heartbeat pings, cron hooks, and upstream errors. The MEMORY_INTENT_RE pattern triggers immediate capture for explicit memory phrases.
Key config knobs
| Setting | Default | Purpose |
|---|
recallTopK | 4 | Max memories per bank per recall |
maxPromptChars | 1200 | Truncation limit for recall queries |
maxCaptureChars | 1200 | Truncation limit for retained content |
maxItemsPerRun | 3 | Max user messages captured per agent run |
includeWriteBankInRecall | true | Auto-include writeBank in recall list |
Claude Code Hook Integration
The Claude Code analog of the OpenClaw plugin. Three hooks under ~/.claude/hooks/ auto-recall on every user prompt, auto-retain on every file edit, and emit a per-session journal at ~/.claude/.hindsight-journal/YYYY-mm-dd-h-m-s.md that explains in plain English what was searched, what bank was resolved, how effective the recall was, and what was retained (with LLM-synthesized rationale for the subjective parts).
| Hook (settings.json event) | Script | Behavior |
|---|
UserPromptSubmit | hindsight-recall.sh | Resolve bank, recall context, inject into prompt, log recall/recall_skipped event |
PostToolUse (Write|Edit|MultiEdit) | hindsight-retain.sh | Retain edited file context, log retain event |
Stop | hindsight-session-end.sh | Daemonize journal writer (setsid nohup), legacy session-summary retain |
The Stop hook must detach the journal writer with setsid nohup … </dev/null >/dev/null 2>&1 & — Claude Code reaps the hook's process group on return, killing any plain & background that's still waiting on the 30-second hindsight memory reflect call.
Full reference (event schema, env knobs, manual ops, failure modes): references/claude-code-journal.md.
Deterministic Governance (Single-Skill Canonical)
This hindsight skill is the single canonical memory package. Keep governance here (do not split into a second memory-governance skill).
Required invariants
hindsight-memory plugin enabledautoRecall=trueautoCapture=truecaptureDirectIntent=truecaptureToolErrors=true- Explicit
defaultBank and agentRoutes
Deterministic audit
Run:
python3 /home/delorenj/.agents/skills/hindsight/scripts/audit_hindsight_memory.py
Expect PASS. Non-zero exit means policy drift.
Governance Principles
Clock independence
Three independent clocks operate in the OpenClaw runtime. They must not be conflated:
- Heartbeat (agent runtime): Owns triage/dispatch loops and proactive checks
- Cron (scheduler): Owns exact-time reminders and isolated scheduled tasks
- Hindsight (memory backend): Owns memory extraction, indexing, and consolidation independently
If cron jobs duplicate heartbeat behavior, remove the cron jobs. If heartbeat tries to manage memory refresh timing, stop it.
Automated curation replaces manual promotion
The old pattern of writing daily logs to memory/YYYY-MM-DD.md and manually promoting to MEMORY.md is replaced by Hindsight's hierarchy:
| Old (file-based) | New (Hindsight) |
|---|
| Daily log entries | Raw facts (auto-captured by plugin) |
| Manual promotion review | Observations (auto-consolidated from facts) |
| Curated MEMORY.md | Mental models (user-created summaries) |
The plugin's before_compaction and session_end hooks ensure context survives session boundaries without manual intervention.
