What it does
The memory API stores episodes, facts, graph edges and procedures as ordinary entities in the same log as everything else, and answers recall requests by fusing BM25, vector and graph-hop results. A consolidation run can ask a language model to turn earlier agent runs into facts and procedures. Each recall issues a verifiable receipt.
How it works
An episode is what happened: an agent id, an optional run id, a text summary, free-form detail and a time. The summary is indexed for keyword search and embedded on write through the Ollama-compatible embedding endpoint (KYNETRA_EMBED_URL). A fact is a subject, predicate and object with a confidence, source run ids and a validity window. An edge links two things with a named relation and its own validity window. A procedure is a named, learned sequence of steps with a trigger and a success count.
POST /v1/memory/recall takes a query, top_k (1 to 100, default 5), an optional agent id, graph_hops (0 to 6) and an as_of time. It fuses three ranked lists with reciprocal-rank fusion: BM25 over episodes and facts, vector similarity, and a graph arm that seeds from the top 25 fused fact hits and walks edges that were valid at as_of. Each hit reports the rank and score from every arm that contributed. If the embedding endpoint is unreachable, the vector arm is skipped and the response is flagged degraded and answered from BM25 and the graph.
POST /v1/memory/consolidate runs the configured language model over unprocessed agent runs, in batches of 1 to 100 (default 20), to propose facts and procedures. It is watermarked and idempotent, and it returns a clear error when no model provider is configured.
Recall also checks a freshness watermark and a reindex fence before it searches, and it stores a receipt afterwards; see the recall receipts entry. The same recall is available to agents as the recall_memory action.
Where you reach it
- HTTP
POST /v1/memory/episodes, /facts, /edges, /procedures, /recall, /consolidate; GET /v1/memory/procedures/{name}, GET /v1/memory/stats - Config
KYNETRA_EMBED_URL, KYNETRA_EMBED_MODEL
Example
curl -s "$KYNETRA_URL/v1/memory/episodes" \
-H "Authorization: Bearer $EDITOR_TOKEN" -H "Content-Type: application/json" \
-d '{ "agent_id": "sre", "summary": "Raised log retention after disk alert", "detail": { "ticket": "OPS-142" } }'
curl -s "$KYNETRA_URL/v1/memory/recall" \
-H "Authorization: Bearer $VIEWER_TOKEN" -H "Content-Type: application/json" \
-d '{ "query": "disk alert", "top_k": 5, "graph_hops": 1, "allow_stale": true }'Limits
- By default a recall is refused with a freshness conflict, because the freshness gate requires the embedding index to be marked fresh and nothing in the stock server marks it. Send allow_stale: true; the response then reports the observed freshness state honestly, which is unknown.
- The memory API is an operator facility in this release and is not yet project-scoped: all memory shares one namespace per deployment. Grant access to it only to operators.
- A write or recall is refused while a vector reindex is in flight for the memory index. No route starts a reindex, so this fence is exercised by tests.
- The vector arm needs an Ollama-compatible embedding endpoint; without one, recall uses BM25 and the graph alone.
- Consolidation quality is whatever the configured model returns. There is no automated evaluation of extracted facts.
- Graph traversal builds an adjacency view of the edges in memory and refreshes it when the log advances; very large graphs will cost memory.
Evidence
- On this siteAI features catalogue
- Tests27 module tests cover episodes, facts, edges, procedures, consolidation and fused recall; 11 mounted-route tests cover freshness refusal, receipts, the reindex fence, wrong-width embeddings and store faults; 3 tests cover the in-run recall action
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.