# Hindsight Memory

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-viktorbezdek-skillstack-hindsight-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [viktorbezdek](https://agentstack.voostack.com/s/viktorbezdek)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [viktorbezdek](https://github.com/viktorbezdek)
- **Source:** https://github.com/viktorbezdek/skillstack/tree/main/hindsight/skills/hindsight-memory

## Install

```sh
agentstack add skill-viktorbezdek-skillstack-hindsight-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `` block — Claude sees them, the chat does not. |
| Retain | `Stop` (async) | `scripts/retain.py` | Reads the transcript, **strips any injected `` 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`).

```bash
# 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 `` 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 `` / `` 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [viktorbezdek](https://github.com/viktorbezdek)
- **Source:** [viktorbezdek/skillstack](https://github.com/viktorbezdek/skillstack)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-viktorbezdek-skillstack-hindsight-memory
- Seller: https://agentstack.voostack.com/s/viktorbezdek
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.