Agent memory

Agents keep two kinds of memory. Short-term memory is working context for a ticket or a follow-up question and expires on its own (72 hours by default). Long-term memory is what an agent has learnt: facts about a person, its own procedures, notes for the whole workspace. Long-term memory is distilled from finished conversations or written through the memory API, held for review until approved, and recalled into an agent's prompt when it is relevant.

Provenance: what a memory rests on#

Every long-term memory records the sources it was learnt from, with a fingerprint of each as it was when the memory was written:

Name sources when you write a memory by hand:

POST /api/memory
{"agent": "copilot", "scope": "agent", "text": "VPN-4012 is fixed by client 5.2.1",
 "sources": [{"kind": "kb", "ref": "KB-7"}]}

GET /api/memory-provenance/{id} shows what a memory rests on and each source's state at its last check.

When a source changes#

Every 15 minutes (and on demand with POST /api/memory-provenance/check) each tracked source is checked again. A memory whose source changed or disappeared is stale, and what happens next is the TICKETIQ_MEMORY_INVALIDATION setting:

Memories written before provenance existed have no recorded sources and are never touched. A contradiction is handled when it is found: approving a memory that contradicts or supersedes another retires the older one, and any memory derived from the retired one becomes stale here.

Every finding and every action is audited (memory.stale, memory.requeued, memory.invalidated, memory.provenance.check), by memory id and reason, never the memory's text.

Consolidation#

The distiller writes one memory per thing it learns from one conversation, so the same fact told ten times becomes ten rows. Every 6 hours (and on demand with POST /api/memory-consolidations/run) each scope's active long-term memories of one category are tidied:

Each run writes a consolidation plan naming every memory before and after. Nothing is deleted: memories folded away are kept as superseded, and a merged memory records the ids it replaced. What a run does with its plan is the TICKETIQ_MEMORY_CONSOLIDATION setting:

GET /api/memory-consolidations lists the plans. POST /api/memory-consolidations/{id}/apply puts a plan in force, and POST /api/memory-consolidations/{id}/revert puts the before back exactly: the originals in use again and the merged memories retired. Runs, applies and reverts are audited (memory.consolidation.proposed, .run, .applied, .apply, .reverted, .revert) by ids and counts, never by what a memory says.

Eval gate#

A memory recalled into an agent's prompt changes what the agent says, so a wrong one costs answers until someone notices. The eval gate catches it. It asks the agent's gate cases twice, once as the agent answers now and once with the new memory in its prompt the way recall adds it, and scores both answers against each case's expectations (expect.contains, expect.regex, expect.excludes). A case that passed without the memory and fails with it is a regression. Procedures are the rules an agent gives itself, so they are gated the same way.

Gate cases are an agent_turn eval dataset named memory-gate-<agent>, or memory-gate for every agent. Cases without expectations are skipped. An agent with no gate dataset is untested: nothing is called and nothing is spent. Each case costs two governed calls of the agent, so keep the dataset to the answers that matter (at most 20 cases are used).

What a verdict does is the TICKETIQ_MEMORY_ACTIVATION_GATE setting:

POST /api/memory-gate/{id}/check runs the gate on one memory now. It records the verdict and changes nothing else. Every verdict is audited (memory.gate.pass, .regressed, .untested, .error) by memory id and case ids, never by what the memory or the answers say.