hindsight

Files (1)

• SKILL.md

SKILL.md (first lines)

# Hindsight Memory

Use the Hindsight tools to persist what matters across sessions and retrieve it when it changes behavior. Memory that is never recalled is wasted. Memory that is never corrected goes stale and corrupts reasoning.

## When to Retain

Call `retain` when the user shares any of the following:

- A preference, correction, or stated goal.
- A technical decision, architectural choice, or trade-off.
- A fact about their environment or project.
- An error and its resolution.

Do not retain greetings, small talk, or reasoning that does not affect future behavior.

Always use `retain`, not `sync_retain`, as retaining can take several minutes to complete.

## How to Retain

Set these fields on every `retain`/`sync_retain` call:

- `content`: The raw/verbatim conversation text of the session. Do not summarize first. Redact any sensitive information. Favor verboseness over conciseness. The more context you provide, the better the memory extraction will be.
- `context`: A short label describing the source or situation. This label provides meaningful context for memory extraction. Keep it short, under 5 words. Examples: "architecture review for the payments service", "user preference for error handling".
- `document_id`: A slug identifying the session (e.g., `session-payments-refactor`, `ticket-1234`). Pick this slug once within a session and reuse it on every retain in that session to prevent creating duplicate memories.
- `update_mode`: Set to `replace` to overwrite any previous memory with the same `document_id`. Set to `append` to add to the existing memory with the same `document_id`. When updating a previously retained memory, use `replace` if the new content is a correction or replacement, and use `append` if the new content is an addition. When appending, only send the new content. The new content will be appended to existing memories.
- `tags`: See Tag Conventions below.
- `timestamp`: Omit or set to `null`. Hindsight will use the current time automatically.

## Tag Conventions

Tags filter which memories `recall` and `reflect` return. Pass `tags` with a filter to scope results - omit `tags` to search all memories.

Allowed tags:

- `repo:<git repo name>`: The repo name of the current git repo (or the base git repo name if in a working tree). Use a command like `basename "$(dirname "$(cd "$(git rev-parse --git-common-dir)" && pwd)")"` to determine the repo folder name at the start of a session and reuse this tag on every retain. Note that when working within a working tree, the base repo name should be used. When recalling, decide whether the query is specific to the current repo or general. Pass `tags=["repo:<name>"]` to filter to the current repo. Omit `tags` to search across all repos.

The `repo:` tag is required on every `retain`/`sync_retain` call. Do not skip it by defaulting to "no evidence of a git repo" - run `git rev-parse --show-toplevel` to check. If the command fails (no git repo), omit the tag.

Tags not in the allowed tags list are not allowed. Do not use tags for metadata, only for filtering.

## When to Recall

Call `recall` at the start of a session or when a task would benefit from past context. Pass a query describing what is needed. Set `budget` to `mid`.

Call `reflect` instead of `recall` when the question requires synthesizing across multiple memories into a single answer. Pass `response_schema` when structured output is needed.

Favor `reflect` unless looking for a simple fact.

## How to Recall

- Call `recall` or `reflect` once for a given topic. Read the result. If it answers the question, stop.
- If the result is insufficient, change the query or tags and call once more. Do not call a third time for the same topic.
- Set `budget` to `low` for simple fact lookups. Set `budget` to `mid` for everything else.

## Correcting Memories

In some cases, an old memory was incorrectly retained or has become stale. When the user corrects or contradicts something previously stated, you must update/retire the memory to reflect the new information.

When correcting, decide whether the memory should be retired/deleted or updated with correct information.

1. The memory should be retired/deleted: use `invalidate_memory` on the old memory ID to retire it. If the wrong memory was retired by mistake, use `invalidate_memory` with `restore=true` to restore it.
2. The memory should be updated with correct information: use `update_memory` to fix a detail in a memory without retiring it.

## Session Continuity

Call `recall` or `reflect` at the start of a turn when a task would benefit from past context.

## Gotchas

- Do not retain then recall in the same turn. Retained memories are not indexed yet. The recall will not find them.
- Do not use random UUIDs for `document_id`. Reuse the same slug when re-retaining the same conversation. Random IDs create duplicate documents.
- Always set the `context` field. Without it, extraction quality drops significantly.
- Use tags for filtering, not metadata. Metadata is not filterable at recall time.
- Do not pre-summarize `content` before retaining. Pass the raw conversation text. Summaries lose entity relationships and temporal markers.
- Do not use `budget="high"` by default. Use `mid`. Use `low` for simple lookups.
- Invalidate stale memories when they change. A corrected fact and its old version rank equally in retrieval. Retire the old one.

From Silvenga/agent-skills, MIT.

More from Silvenga/agent-skills