From bbcfe2f5abb7b9d4379e4fb7c8c553ffff3c7761 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Mon, 16 Mar 2026 18:37:12 +0100 Subject: [PATCH] docs(skills): encourage rich context over pre-summarized strings in retain (#594) * docs: add config vars for local reranker FP16 and bucket batching (#588) * fix: add missing reranker local fields to CLI config override and fix ty type error - Add reranker_local_fp16, reranker_local_bucket_batching, reranker_local_batch_size to the manual HindsightConfig() constructor call in main.py (CLI override block) - Replace direct module attribute assignment with setattr() in the transformers 5.x monkey-patch so ty can resolve it without raising unresolved-attribute * docs(skills): encourage rich context over pre-summarized strings in retain The previous guidance told agents to distill content before calling retain (e.g. "Be specific: store X not Y"). This misrepresents the actual architecture: the server runs a full extraction pipeline (fact extraction, entity linking, embeddings) on whatever is passed in. - Add "How Hindsight Works" section explaining the server-side pipeline - Update retain examples to pass full-context observations - Replace "Be specific" with "Pass rich context" - Clarify that --context is metadata labeling, not a content filter Closes #592 * docs(skills): add raw conversation transcript example for retain --- skills/hindsight-cloud/SKILL.md | 37 +++++++++++++++++++++------ skills/hindsight-local/SKILL.md | 33 +++++++++++++++++++----- skills/hindsight-self-hosted/SKILL.md | 37 +++++++++++++++++++++------ 3 files changed, 85 insertions(+), 22 deletions(-) diff --git a/skills/hindsight-cloud/SKILL.md b/skills/hindsight-cloud/SKILL.md index e15de6d9..91852810 100644 --- a/skills/hindsight-cloud/SKILL.md +++ b/skills/hindsight-cloud/SKILL.md @@ -38,19 +38,39 @@ cat ~/.hindsight/config After setup, use the bank ID in all commands below. +## How Hindsight Works + +When you call `retain`, Hindsight does **not** store the string as-is. The server runs an internal pipeline that: + +1. **Extracts structured facts** from the content using an LLM +2. **Identifies entities** (people, tools, concepts) and links related facts +3. **Builds temporal and causal relationships** between facts +4. **Generates embeddings** for semantic search + +This means you should pass **rich, full-context content** — the server is better at extracting what matters than a pre-summarized string. Your job is to decide **when** to store, not **what** to extract. + ## Commands Replace `` with the user's actual bank ID (e.g., `team-frontend`). ### Store a memory -Use `memory retain` to store what you learn: +Use `memory retain` to store what you learn. Pass full context — raw observations, session notes, or detailed descriptions: ```bash -hindsight memory retain "Project uses ESLint with Airbnb config and Prettier for formatting" -hindsight memory retain "Running tests requires NODE_ENV=test" --context procedures -hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings -hindsight memory retain "Alice prefers verbose commit messages with context" --context preferences +hindsight memory retain "The project uses ESLint configured with the Airbnb rule set and Prettier for formatting. Auto-fix on save is enabled in the editor config." +hindsight memory retain "Ran the test suite with NODE_ENV=test. Tests pass. Without NODE_ENV=test, the suite fails with a missing config error." --context procedures +hindsight memory retain "Build failed on Node 18 with error 'ERR_UNSUPPORTED_ESM_URL_SCHEME'. Switched to Node 20 and build succeeded." --context learnings +hindsight memory retain "Alice reviewed the PR and asked for verbose commit messages that explain the motivation, not just what changed." --context preferences +``` + +You can also pass a raw conversation transcript with timestamps: + +```bash +hindsight memory retain "[2026-03-16T10:12:03] User: The auth tests keep failing on CI but pass locally. Any idea? +[2026-03-16T10:12:45] Assistant: Let me check the CI logs. Looks like the tests are running without the TEST_DATABASE_URL env var set — they fall back to the production DB URL and hit a connection timeout. +[2026-03-16T10:13:20] User: Ah right, I never added that to the CI secrets. Adding it now. +[2026-03-16T10:15:02] User: That fixed it. All green now." --context learnings ``` ### Recall memories @@ -120,9 +140,10 @@ This is a **shared team bank**. Store knowledge that benefits the team. For indi ## Best Practices 1. **Store immediately**: When you discover something, store it right away -2. **Be specific**: Store "npm test requires --experimental-vm-modules flag" not "tests need a flag" -3. **Include outcomes**: Store what worked AND what did not work +2. **Pass rich context**: Include full observations, not pre-summarized strings — the server extracts facts automatically +3. **Include outcomes**: Store what happened AND why, including failures and workarounds 4. **Recall first**: Always check for relevant context before starting work 5. **Think team-first**: Store knowledge that would help other team members -6. **Attribute individual preferences**: Store "Alice prefers X" not just "User prefers X" +6. **Attribute individual preferences**: Store "Alice reviewed the PR and asked for X" not just "User prefers X" 7. **Distinguish project vs personal**: Project conventions apply to everyone; personal preferences are per-person +8. **Use `--context` for metadata**: The `--context` flag labels the type of memory (e.g., `procedures`, `learnings`, `preferences`), not a replacement for full content diff --git a/skills/hindsight-local/SKILL.md b/skills/hindsight-local/SKILL.md index ddfc25ba..fa1a3f45 100644 --- a/skills/hindsight-local/SKILL.md +++ b/skills/hindsight-local/SKILL.md @@ -23,16 +23,36 @@ uvx hindsight-embed configure This will prompt for an LLM provider and API key. After setup, the commands below will work. +## How Hindsight Works + +When you call `retain`, Hindsight does **not** store the string as-is. The server runs an internal pipeline that: + +1. **Extracts structured facts** from the content using an LLM +2. **Identifies entities** (people, tools, concepts) and links related facts +3. **Builds temporal and causal relationships** between facts +4. **Generates embeddings** for semantic search + +This means you should pass **rich, full-context content** — the server is better at extracting what matters than a pre-summarized string. Your job is to decide **when** to store, not **what** to extract. + ## Commands ### Store a memory -Use `memory retain` to store what you learn: +Use `memory retain` to store what you learn. Pass the full context — raw observations, session notes, conversation excerpts, or detailed descriptions: ```bash -uvx hindsight-embed memory retain default "User prefers TypeScript with strict mode" -uvx hindsight-embed memory retain default "Running tests requires NODE_ENV=test" --context procedures -uvx hindsight-embed memory retain default "Build failed when using Node 18, works with Node 20" --context learnings +uvx hindsight-embed memory retain default "User is working on a TypeScript project. They enabled strict mode and prefer explicit type annotations over inference." +uvx hindsight-embed memory retain default "Ran the test suite with NODE_ENV=test. Tests pass. Without NODE_ENV=test, the suite fails with a missing config error." --context procedures +uvx hindsight-embed memory retain default "Build failed on Node 18 with error 'ERR_UNSUPPORTED_ESM_URL_SCHEME'. Switched to Node 20 and build succeeded." --context learnings +``` + +You can also pass a raw conversation transcript with timestamps: + +```bash +uvx hindsight-embed memory retain default "[2026-03-16T10:12:03] User: The auth tests keep failing on CI but pass locally. Any idea? +[2026-03-16T10:12:45] Assistant: Let me check the CI logs. Looks like the tests are running without the TEST_DATABASE_URL env var set — they fall back to the production DB URL and hit a connection timeout. +[2026-03-16T10:13:20] User: Ah right, I never added that to the CI secrets. Adding it now. +[2026-03-16T10:15:02] User: That fixed it. All green now." --context learnings ``` ### Recall memories @@ -85,6 +105,7 @@ uvx hindsight-embed memory reflect default "How should I approach this task base ## Best Practices 1. **Store immediately**: When you discover something, store it right away -2. **Be specific**: Store "npm test requires --experimental-vm-modules flag" not "tests need a flag" -3. **Include outcomes**: Store what worked AND what did not work +2. **Pass rich context**: Include full observations, not pre-summarized strings — the server extracts facts automatically +3. **Include outcomes**: Store what happened AND why, including failures and workarounds 4. **Recall first**: Always check for relevant context before starting work +5. **Use `--context` for metadata**: The `--context` flag labels the type of memory (e.g., `procedures`, `learnings`, `preferences`), not a replacement for full content diff --git a/skills/hindsight-self-hosted/SKILL.md b/skills/hindsight-self-hosted/SKILL.md index 91f15cd2..dd7d1c4a 100644 --- a/skills/hindsight-self-hosted/SKILL.md +++ b/skills/hindsight-self-hosted/SKILL.md @@ -41,19 +41,39 @@ cat ~/.hindsight/config After setup, use the bank ID in all commands below. +## How Hindsight Works + +When you call `retain`, Hindsight does **not** store the string as-is. The server runs an internal pipeline that: + +1. **Extracts structured facts** from the content using an LLM +2. **Identifies entities** (people, tools, concepts) and links related facts +3. **Builds temporal and causal relationships** between facts +4. **Generates embeddings** for semantic search + +This means you should pass **rich, full-context content** — the server is better at extracting what matters than a pre-summarized string. Your job is to decide **when** to store, not **what** to extract. + ## Commands Replace `` with the user's actual bank ID (e.g., `team-frontend`). ### Store a memory -Use `memory retain` to store what you learn: +Use `memory retain` to store what you learn. Pass full context — raw observations, session notes, or detailed descriptions: ```bash -hindsight memory retain "Project uses ESLint with Airbnb config and Prettier for formatting" -hindsight memory retain "Running tests requires NODE_ENV=test" --context procedures -hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings -hindsight memory retain "Alice prefers verbose commit messages with context" --context preferences +hindsight memory retain "The project uses ESLint configured with the Airbnb rule set and Prettier for formatting. Auto-fix on save is enabled in the editor config." +hindsight memory retain "Ran the test suite with NODE_ENV=test. Tests pass. Without NODE_ENV=test, the suite fails with a missing config error." --context procedures +hindsight memory retain "Build failed on Node 18 with error 'ERR_UNSUPPORTED_ESM_URL_SCHEME'. Switched to Node 20 and build succeeded." --context learnings +hindsight memory retain "Alice reviewed the PR and asked for verbose commit messages that explain the motivation, not just what changed." --context preferences +``` + +You can also pass a raw conversation transcript with timestamps: + +```bash +hindsight memory retain "[2026-03-16T10:12:03] User: The auth tests keep failing on CI but pass locally. Any idea? +[2026-03-16T10:12:45] Assistant: Let me check the CI logs. Looks like the tests are running without the TEST_DATABASE_URL env var set — they fall back to the production DB URL and hit a connection timeout. +[2026-03-16T10:13:20] User: Ah right, I never added that to the CI secrets. Adding it now. +[2026-03-16T10:15:02] User: That fixed it. All green now." --context learnings ``` ### Recall memories @@ -123,9 +143,10 @@ This is a **shared team bank**. Store knowledge that benefits the team. For indi ## Best Practices 1. **Store immediately**: When you discover something, store it right away -2. **Be specific**: Store "npm test requires --experimental-vm-modules flag" not "tests need a flag" -3. **Include outcomes**: Store what worked AND what did not work +2. **Pass rich context**: Include full observations, not pre-summarized strings — the server extracts facts automatically +3. **Include outcomes**: Store what happened AND why, including failures and workarounds 4. **Recall first**: Always check for relevant context before starting work 5. **Think team-first**: Store knowledge that would help other team members -6. **Attribute individual preferences**: Store "Alice prefers X" not just "User prefers X" +6. **Attribute individual preferences**: Store "Alice reviewed the PR and asked for X" not just "User prefers X" 7. **Distinguish project vs personal**: Project conventions apply to everyone; personal preferences are per-person +8. **Use `--context` for metadata**: The `--context` flag labels the type of memory (e.g., `procedures`, `learnings`, `preferences`), not a replacement for full content