Skills appear to mislead agents into doing work the server already handles

[soichisumi]

Opinion

I believe the current Skill definitions (skills/hindsight-local/SKILL.md, skills/hindsight-self-hosted/SKILL.md) are misleading agents in a way that works against Hindsight's core design.

The Skills instruct agents to distill and summarize knowledge themselves before calling retain:

"Be specific: Store 'npm test requires --experimental-vm-modules flag' not 'tests need a flag'"

"Store immediately: When you discover something, store it right away"

And the example commands reinforce this:

uvx hindsight-embed memory retain default "User prefers TypeScript with strict mode"
uvx hindsight-embed memory retain default "Build failed when using Node 18, works with Node 20"

This pattern implies the agent is responsible for knowledge extraction — deciding what matters, summarizing it, and passing a polished string to retain.

My Understanding of How Hindsight Actually Works

From what I understand, when retain is called, Hindsight does not simply store the string as-is. Instead, the server runs an internal pipeline that:

1. Extracts structured facts from the raw input using an LLM — breaking content into dimensions like what happened, when, where, who was involved, and why it matters
2. Identifies entities (people, tools, concepts) and links related facts together
3. Builds temporal and causal relationships between facts automatically
4. Generates embeddings for semantic search

If this understanding is correct, the server is fully capable of accepting raw, unstructured content — such as a session log or conversation transcript — and extracting structured knowledge from it automatically.

Why the Current Skills May Be Counterproductive

If the server handles knowledge extraction, then instructing agents to pre-summarize before calling retain would:

• Waste agent context/tokens on a step the server already performs
• Discard rich context that the server's LLM could use to extract better facts,
  entities, and causal links
• Give agents a false mental model of Hindsight as a simple string store,
  rather than a knowledge extraction pipeline

Proposed Direction

If my understanding is correct, the Skills should be updated to reflect the actual architecture:

• Agents should be encouraged to pass raw or full-context content to retain (e.g., session logs, conversation excerpts, documents)
• Agent-side responsibility should be limited to deciding when to call retain, not what to extract from it
• The --context flag should be highlighted as the way to provide metadata, rather than having agents pre-process the content itself

Happy to be corrected.
But if it is accurate, I think aligning the Skills with the actual behavior would significantly improve how agents interact with Hindsight.

[nicoloboschi]

thanks you're totally right - I've put up a fix for it #594