Hindsight explained: what an agent can keep between sessions
Hindsight architecture: a bank through ingestion, retrieval and synthesis
Map the documented memory path before judging relevance, freshness or isolation.
What you will learn
- Retain does more than append text
- Recall combines several candidate sets
- Reflect has a different contract
Before you start
- Python client basics
- A synthetic memory test case and a deployment boundary
Create a small, auditable fixture that records corrections, retrieval misses and costs.
Key takeaways
- Writes can create derived representations.
- Ranking depends on several retrieval paths.
- A reflected answer is an interpretation.
Retain does more than append text
The README says retain extracts facts, dates, entities and relationships with an LLM, then normalizes them into search representations. That means an apparently simple write has model cost and can encode an interpretation of the input. Keep the original statement available when reviewing a surprising memory.
World facts and agent experiences travel through different conceptual pathways. Observations consolidate multiple memories, while mental models refresh a standing answer. Measure how quickly each derived form becomes available before relying on it in a time-sensitive agent.
Recall combines several candidate sets
The project describes semantic, BM25 keyword, graph and temporal retrieval. Results are fused, reranked and trimmed to a token budget. A top answer can therefore depend on retrieval settings as well as the content stored; preserve the query and limits in a test record.
A date question and a named-entity question exercise different paths. Evaluate both, including a deliberately conflicting update. When the retrieved item is wrong, inspect its source and timestamp before tuning the final prompt.
Reflect has a different contract
Reflect asks for a synthesized answer based on bank content and disposition. It may be useful for project risk summaries, yet a synthesis needs an evidence trail if it influences a decision. Treat it as an interpretation until a human verifies the cited records.
The inspected source includes a memory engine and a Python client, but this article does not trace every internal parser, background job or database query. The architecture diagram marks those areas as documented behavior rather than a complete code audit.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Trace one retain request from input to stored evidence.
- 2
Test semantic and temporal questions separately.
- 3
Require evidence for any reflected conclusion.
Copy-ready example
retain -> fact extraction -> bank storage
recall -> semantic | keyword | graph | temporal -> rerank
reflect -> retrieved evidence -> synthesized answerFrequently asked questions
Why can an updated fact take time to appear?
Derived observations and mental models may refresh in the background; verify the operation status and chosen read path.
Does a bank guarantee tenant security?
The repository describes isolation; verify authorization and deployment controls for your own threat model.
Sources
- Hindsight / README.mdSource checked 2026-09-26
- Hindsight / hindsight-api-slim/hindsight_api/engine/memory_engine.pySource checked 2026-09-26