AI & agents

Recall receipts

Gives each retrieval a tamper-evident record of what was returned and under which index state, so an audit can verify it later without the raw query.

BetaEngine edition 5f8ea3af

What it does

Every successful memory recall issues and stores a receipt: an HMAC-SHA256 digest that binds the project, the principal, a salted and keyed digest of the query (never the query text), the retrieval configuration, the freshness watermark and the ordered result ids and scores. Two admin routes verify a receipt by digest and export a project receipts for offline verification.

How it works

A receipt binds the project, the principal and purpose when known, a keyed digest of the query with its salt, the policy version, the model id, the index name and schema version, top_k, a digest of the filters, the freshness state with its source sequence and watermark, the ordered result ids with their scores, and the issue time. It states that these exact results were produced for this project and principal from an index with this schema and declared freshness, under this retrieval configuration. It does not state that the retrieved content is true. Changing a result, its order, a version or the project changes the digest.

The digest is keyed. The key is KYNETRA_RAG_RECEIPT_HMAC_KEY (hex, at least 16 bytes) when set, and otherwise a key derived from the audit key, so receipts verify after a restart and on any node that holds the same key. The query digest adds a fresh random salt per receipt, so two receipts for the same query text cannot be linked by comparing digests.

Receipts are stored under a reserved, project-scoped kind. Loading one re-verifies its kind, project binding and signature, and a row that was edited in storage verifies false. POST /admin/v1/rag-receipt/verify takes a digest and answers verified true or false with a reason, or 404 when none exists. GET /admin/v1/rag-receipt/export returns the receipts in a time range together with whether the whole batch verifies; mismatched or corrupt rows are listed by id instead of being dropped, so the batch can be checked offline with the key.

Where you reach it

  • HTTPPOST /admin/v1/rag-receipt/verify { digest, project }; GET /admin/v1/rag-receipt/export?project=&from_ms=&to_ms=
  • ConfigKYNETRA_RAG_RECEIPT_HMAC_KEY

Limits

  • Receipts are issued by memory recall and by nothing else. The search, vector, hybrid and KynQL routes do not issue them.
  • The receipt key follows the audit key unless you set the override. Rotating the audit key does not rotate the receipt key, and receipt key rotation is not wired.
  • A per-result source sequence is not bound into the receipt.
  • Receipts are kept until an explicit purge; no retention policy runs.
  • Both routes need an admin role and default to the shared memory project.

Evidence

  • On this siteAI features catalogue
  • Tests23 receipt tests cover keyed digests, unlinkable query digests, JSON round trips, project binding, corrupt rows and store faults; mounted-route tests check a verifiable receipt with no raw query, a tampered receipt failing verification and survival across a restart

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.