Hindsight explained: what an agent can keep between sessions
Hindsight quickstart: retain, recall and reflect in a small test
Run the documented client path with fictional data and check each operation separately.
What you will learn
- Prepare a bounded service
- Call the three operations in sequence
- Check the failure path
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
- The README example is a starting path, not a tested result here.
- Keep the bank ID identical across the trial.
- Retain retries need an explicit duplicate policy.
Prepare a bounded service
The README documents a Docker image with an embedded data volume, a bare-metal Python package and an external PostgreSQL route. For a local trial, pick one route and pin the image or package version after checking the release. The README command uses latest; that is convenient for a demo but weak evidence for a reproducible test.
The service example exposes an API on port 8888 and a UI on 9999. Bind them to loopback or another restricted network during evaluation. Store the LLM provider credential outside shell history and code, and make the volume location explicit before stopping the container.
Call the three operations in sequence
The Python example constructs Hindsight with a base URL, then sends content to retain, a question to recall and a broader question to reflect. Keep the bank identifier constant and print the raw result for each call. A generated answer alone hides whether the service retained the expected statement.
Use synthetic text that contains one changed fact. Ask about the original fact, then the correction, and compare the result with the content you supplied. This is a learning test, not a claim about a production accuracy rate.
Check the failure path
An unavailable server, missing model credential or wrong bank ID should produce a visible failure. Record the HTTP status or exception, request ID if available, and the version used. Avoid retrying a retain call blindly because a repeat can alter the bank.
The client methods expose synchronous calls in the inspected Python wrapper. Production use may need async or batching, but first establish a small, inspectable request and response.
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
Choose one documented installation route and pin its version.
- 2
Use a fictional bank and print each operation response.
- 3
Record one expected answer and one deliberate failure.
Copy-ready example
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
bank = "fictional-project"
client.retain(bank_id=bank, content="Release review is on Friday")
print(client.recall(bank_id=bank, query="When is the review?"))
print(client.reflect(bank_id=bank, query="What should the team prepare?"))Frequently asked questions
Must I use OpenAI?
The README lists several hosted and local model providers; configure one supported provider for your test.
Was the Docker example run for this article?
No. Commands are cited from a fixed upstream revision and require local verification.
Sources
- Hindsight / README.mdSource checked 2026-09-26
- Hindsight / hindsight-clients/python/hindsight_client/hindsight_client.pySource checked 2026-09-26