Hindsight without a plugin: retain, recall and reflect with curl
Not every tool has a Hindsight plugin. A script, a cron job or a CI step talks to the HTTP API directly. Three calls, and the places where they behave differently than expected.
Two earlier posts were about why I keep my agents' memory in Hindsight and how the whole thing runs on Coolify. For Claude Code there is a plugin, for Grok and Cursor a small wrapper around the same MCP server. That takes care of the agents.
What is still missing then are the things without a plugin: a shell script, a cron job, a step in the pipeline. They talk to the HTTP API directly. At the core these are three calls: retain writes, recall searches, reflect answers. Each of them has a quirk you should know before you run it in a loop.
Preparation
Two variables are enough:
export HINDSIGHT_URL="https://memory.example.com"
export HINDSIGHT_TOKEN="…"
If the server runs with the API-key tenant extension, the key goes into the Authorization header as a bearer token. Without it a 401 comes back. /health stays open.
All paths for a bank start with /v1/default/banks/<bank>. A bare /banks returns 404. If you are looking for a path, look in /openapi.json, that is faster than guessing.
In the examples the bank is called my_websites, like the repo. In my setup every repo gets its own bank.
Writing with retain
curl -s -X POST "$HINDSIGHT_URL/v1/default/banks/my_websites/memories" \
-H "Authorization: Bearer $HINDSIGHT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": [{
"content": "Die Portfolio-Seite wird aus apps/portfolio gebaut, nicht mehr aus dem alten Repo.",
"context": "deploy notes",
"document_id": "deploy-notes-portfolio",
"timestamp": "2026-10-01T10:00:00Z"
}]
}'
Hindsight does not search the original text later. When writing, an LLM pulls out facts, entities and points in time, and recall works with these facts. context goes straight into the extraction prompt and changes what comes out. The docs call a consistently set context one of the most effective levers for the quality of the memories.
timestamp is the point in time at which the thing described happened, not the time of the import. If you leave the field out, Hindsight takes the current time. For material without a real date, such as reference documentation, there is the value "unset".
Without document_id everything ends up twice
For a script that runs regularly, document_id is the most important field. With an ID, Hindsight replaces the existing document along with all memories extracted from it and processes the new content from scratch. Without an ID, Hindsight assigns a random UUID. If you run the same content through twice, there are duplicate memories in the bank afterwards.
So a cron job without document_id fills the bank with the same facts on every run, without an error message. Give every logical document a fixed ID, for example the file path or changelog-2026-10, and the job can run as often as you like.
For content that only grows, like a log or a journal, there is "update_mode": "append". Then you only send the new part, Hindsight appends it and skips unchanged sections during extraction.
Asynchronous when it gets bigger
For larger volumes, "async": true belongs in the request. The call returns immediately with an operation_id, and the worker does the work in the background. You see the status under /v1/default/banks/<bank>/operations.
If the response gets lost on the way, you do not know whether the operation was created. A blind retry might then extract everything twice and pay twice. If you generate the operation_id yourself as a UUID beforehand and send it along with every attempt, the retry is harmless. The same ID returns the original operation and creates no new work.
Searching with recall
curl -s -X POST "$HINDSIGHT_URL/v1/default/banks/my_websites/memories/recall" \
-H "Authorization: Bearer $HINDSIGHT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "Aus welchem Ordner wird die Portfolio-Seite gebaut?",
"max_tokens": 1000
}'
The response is a list of facts, not documents. Each entry has a text field with the extracted fact, a type (world, experience or observation), the document_id it comes from, and a few time fields. With jq '.results[].text' you quickly have what you need in a script.
max_tokens does not limit the number of results, but how much space they may take up together. The default is 4096. Hindsight fills this budget in order of relevance. For a script that copies the results into a prompt, that is more practical than a top-k, because you calculate directly in the unit the model counts too.
budget (low, mid, high, default mid), on the other hand, controls how broad and deep the search goes. For a quick lookup query, low is enough.
A recall does not call an LLM. The search runs in parallel across vectors, full text, the entity graph and time information, and after that a reranker sorts the candidates.
The server rejects queries with more than 500 tokens. So sending a whole document as the search text does not work.
When recall is slow
If you add "trace": true to the request, the response includes a breakdown by phase. That is how I saw back then that out of 9.82 seconds of recall, 8.87 seconds went to reranking. Before you start turning knobs on the server, look here first.
Tags within a bank
Banks are the hard boundary between projects. Within a bank you can filter with tags. When writing you attach them to an item ("tags": ["topic:deploy"]), when searching you pass them along:
{
"query": "Wie wird deployt?",
"tags": ["topic:deploy"],
"tags_match": "any_strict"
}
tags_match is what matters. The default is any, and any additionally returns all memories without tags. If you expect a tag filter to really return only tagged results, you need any_strict or all_strict.
Answering with reflect
curl -s -X POST "$HINDSIGHT_URL/v1/default/banks/my_websites/reflect" \
-H "Authorization: Bearer $HINDSIGHT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "Was muss ich beachten, bevor ich die Portfolio-Seite neu deploye?",
"budget": "mid",
"include": { "facts": {} }
}'
recall returns raw material, reflect returns a finished answer as Markdown in the text field. Behind it runs an agent loop: the model decides for itself what to look up, searches in several rounds and only writes after that. With "include": { "facts": {} } the response contains a based_on with the memories it relies on. Only what was really retrieved in the loop can be cited.
In operation, reflect behaves noticeably differently from recall. The call needs an LLM, so it costs tokens every time and takes longer. The default timeout for reflect's LLM calls is 30 seconds, as long as you do not set a global HINDSIGHT_API_LLM_TIMEOUT. And budget defaults to low here, not to mid as with recall.
If a tool fails in the loop, for example the database or the reranker, reflect answers with a 500 instead of building an answer out of nothing. For a script that is pleasant. An error arrives as an error, and a 200 with "I know nothing about that" means that the bank really has nothing on it.
Which call for what
If your code or your agent decides for itself what to do with the facts, use recall. It is fast, needs no LLM, and max_tokens fits the amount to the prompt. reflect is worth it when a human is supposed to read an answer at the end, for instance as a summary before a deploy, and a few seconds and a few tokens are fine for that.
Checking what arrived
The fastest way to see whether a script really writes is the document list:
curl -s "$HINDSIGHT_URL/v1/default/banks/my_websites/documents?q=deploy-notes" \
-H "Authorization: Bearer $HINDSIGHT_TOKEN"
q filters on a part of the document_id here. If the same ID shows up exactly once after several runs, your job replaces cleanly. Leave the filter out and you see all documents of the bank. If there are lots of random UUIDs with similar content there after a few runs, the document_id is missing somewhere.
Common questions
- How do I talk to Hindsight without a plugin?
- Through the Hindsight HTTP API, for example with curl. All paths for a bank start with /v1/default/banks/ and the name of the bank. If the server runs with the API-key tenant extension, the key goes into the Authorization header as a bearer token.
- Why are there duplicate memories in my Hindsight bank?
- Without a document_id, Hindsight assigns a random UUID when writing with retain. If the same content goes through twice, there are duplicate memories in the bank afterwards, without an error message. With a fixed document_id, Hindsight replaces the existing document along with all memories extracted from it.
- What is the difference between recall and reflect in Hindsight?
- recall returns a list of facts and does not call an LLM. reflect returns a finished answer as Markdown, needs an LLM for that, costs tokens and takes longer. recall fits when your code or your agent decides for itself what to do with the facts, reflect when a human is supposed to read an answer at the end.
- Why does a tag filter on recall in Hindsight also return memories without tags?
- The default for tags_match in Hindsight is any, and any additionally returns all memories without tags. If you expect only tagged results, you need any_strict or all_strict.