Lifecycle: latest wins, supersession and decay

Memories change. A preference is updated, a decision is reversed, a fact stops being true. agentics.you keeps the history and answers with what holds now. This page covers the MCP memory tools, where an agent records with record_action and recalls with get_context, and then the REST API, which has simpler rules.

Latest wins

When an agent records a memory, the server compares it with what the workspace already holds and picks one of four actions:

• Add. Nothing close exists, or the new memory is a repeated event, such as a second deploy. Both are kept.
• Update. The new memory corrects or fills in the same fact. The old one was incomplete or wrong.
• Supersede. The state changed. The old memory was true until the new one became true.
• Reject. It is a near-duplicate with nothing new, so no second copy is stored.

Only a decision, a preference or an explicitly stated fact can be replaced. An event never replaces another event.

Supersession keeps the history

Update and supersede never delete the old memory. They mark it with superseded_by, the receipt hash of the memory that replaced it. A supersede also sets the old memory's valid_to to the time the new one became true. An update leaves the old validity window alone, because the old memory was never right.

An agent can state the window itself. record_action takes valid_from and valid_to as ISO times. Leave valid_to out while the memory still holds.

What recall returns

• By default, get_context answers with the current state: memories that are not superseded and whose valid_to has not passed.
• With as_of set to an ISO time, it answers as of that moment, including memories that were superseded later.
• With traverse on, it also follows parent_hash links to causes and effects. Those keep their place in the history even when they were superseded.

{"name":"record_action","arguments":{"action":"decide","summary":"Billing runs on Neon.","category":"decision"}}
{"name":"get_context","arguments":{"query":"which database runs billing?"}}
{"name":"get_context","arguments":{"query":"which database runs billing?","as_of":"2026-09-01T00:00:00Z"}}

Decay

Every memory has a decay score from 0 to 1. It combines three things:

• Recency. Age is counted from valid_from, or else from when the memory was written. The curve depends on the memory's tier: core, working or peripheral.
• Use. Each read reinforces a memory, up to three times its natural life. Repeated reads stop counting after ten, so a loop of reads cannot keep a memory alive on its own.
• Importance. The category and the confidence the agent gave it. An unknown confidence counts as 0.5.

The score is floored by tier (core 0.9, working 0.5, peripheral 0.2), so a memory that ranks low is never zeroed out of recall. Recall uses the score to rank results when ranked recall is on for your workspace.

agentics.you does not delete memories for age. A memory leaves recall only when it is superseded, its valid_to passes, or it is deleted. Any future pruning writes a tombstone receipt and keeps the original receipt and its hash.

On the REST API

The REST store keeps one copy of each piece of content per namespace.

• POST /v1/memories with content that already exists in that namespace returns the existing memory with duplicate true. No second job is queued.
• A new memory starts pending while it is processed, then becomes ready. Poll its job at GET /v1/ingest/{job_id}. Lists and search show only ready memories.
• REST memories are not superseded or decayed. They stay until you delete them. DELETE /v1/memories/{id} writes a receipt for the delete.
• Deleting many at once with POST /v1/memories/bulk-delete first asks a person. The call answers approval_required with an approval_id. Once a person approves it in Needs you, repeat the call with approval_receipt_id, the receipt id of that approval. Each memory deleted gets its own receipt.