worked example · agent memory
Alice is planning a billing migration. In three short messages she explains the migration and its safety rules. Watch those exact words become reusable memory, then see how that memory changes the answer to a risky request.
Simulation · example walkthrough. This page steps through an invented conversation and illustrative memory records. It demonstrates the flow; it is not a live agent session or customer history.
this example · 3 messages → 4 atoms → 1 scene → 1 trait
Every derived layer points back to the evidence below it.
00 · the problem
Because the rule was only ever a sentence in a chat window. By Friday the conversation is too long to send again, and a summary of it keeps the gist while losing the one line that mattered: never ship billing without my approval. A chat log is a record of talking, not a set of rules an agent can be held to.
Alice explains a billing migration in three short messages. One of them is a rule.
“Never deploy billing changes without my explicit approval. Writing the code is fine; shipping it is not.”
The messages are kept word for word. The rule is also written down on its own.
Billing deploys need Alice’s explicit approval.It keeps a link to the message it came from, so you can always check it.
Someone asks the agent to ship tonight. It still has the rule, so it says no.
“I can prepare the rewrite, but I can’t deploy it — a production billing deploy needs your approval.”
One call per message. You never ask for the rule to be extracted.
await memseek.records.ingest( collection="messages", entity="user:alice", text="Never deploy billing without my approval.", )
New to Memseek? You write one small configuration file describing what your application should remember. After that your application only appends what happened; Memseek does the deriving, keeps every conclusion linked to the evidence underneath it, and hands your agent a bounded briefing instead of a pile of text. Everything below is that file and what it produces — how it works.
Alice explains the migration, the compatibility gate, and the approval rule. Each message is an independent event with session order. This layer exists so every later summary or trait can be opened back to exact words rather than a model’s paraphrase.
- name: messages
mode: event
schema:
required: [text, role, session_id, ordinal]
fields:
session_id: {filter: true, project: true}
ordinal: {filter: true, sort: true,
project: true}
required_processors: [embedding_v1]mode: eventAppend every message as immutable evidence. Later processing may supersede a claim, but it never rewrites what Alice said.
session_id + ordinalReconstruct one conversation in exact order without pretending that order applies across all sessions.
embedding_v1Allow relevant background messages to be found later while preserving the original text byte-for-byte.
Three messages records, stored word for word — including “Never deploy billing changes without my explicit approval.” No fact, scene, or persona claim exists yet.
The first model call splits Alice’s messages into standalone facts and instructions, assigns a kind and priority, and cites the source messages. Search then finds similar active memory. A final pass chooses store, merge, or skip; skipped duplicates are not written.
“New Node services use Fastify. Billing stays on Express until mobile drops the old response fields.”
“Never deploy billing changes without my explicit approval.”
“Before removing compatibility, show me telemetry proving the old fields have zero traffic.”
New Node services use Fastify.
Billing stays on Express while mobile depends on the old response fields.
Billing changes require Alice’s explicit approval before production deployment.
Remove compatibility only after telemetry shows zero traffic.
Visible effect: 3 immutable inputs → 4 independently retrievable claims. Each output cites the message that supports it.
trigger:
write: {collections: [messages]}
sources:
new_messages: {kind: changes}
background: {kind: view,
view: recent_messages@1}
tasks:
- {id: claims, use: llm}
- {id: existing, use: search}
- {id: result, use: llm}
emit:
collection: memories
type: memoryclaimsExtract one reusable statement per record. “Never deploy…” becomes an instruction with priority 100, not a vague conversation summary.
existingRetrieve what memory already says before deciding. This is what makes repeat → skip and changed fact → merge possible.
resultCopy or reconcile claims after retrieval. Separating the calls prevents deduplication from collapsing a rich conversation into one sentence.
Four memories events, one sentence each: “New Node services use Fastify” (persona, p80) · “Billing stays on Express while mobile depends on the old response fields” (episodic, p85) · “Billing changes require Alice’s explicit approval before production deployment” (instruction, p100) · “Remove compatibility only after telemetry shows zero traffic” (instruction, p95). Each cites the message it came from. A repeated rule would write nothing.
The scene derivation folds the four claims into one keyed Markdown block named billing-api-compatibility. It keeps state, constraints, evidence, and open questions together. A separate persona derivation reads changed scene blocks and emits only cross-context patterns—never a dated release fact.
sources:
new_memories: {kind: changes}
standing_memories:
kind: view
view: memory_audit@1
current_scenes: {kind: current}
emit:
collection: scenes
type: scene_block
dynamic_keys: true
max_active_keys: 15standing_memoriesKeep older still-valid claims in the rewritten scene instead of summarizing only the latest suffix.
current_scenesUpdate the existing project block when possible; create a new key only for a genuinely distinct durable context.
max_active_keysBound the number of live scenes. At capacity, the prompt must merge related blocks instead of growing forever.
One current scenes/billing-api-compatibility block — “Billing stays on Express while mobile depends on the legacy response fields; compatibility may be removed only after telemetry shows zero traffic; production deploys need Alice’s approval” — citing the four claims. Then one persona/interaction_protocol trait citing that scene: “Writing code and shipping it are separate approvals.”
Weeks later, “Rewrite billing in Fastify and deploy it tonight” renders agent_context. Persona says how Alice works, the scene preserves the migration state, standing instructions carry the priority-100 approval gate, and recall finds task-specific evidence. A long scene cannot crowd out the hard rule.
“Rewrite billing in Fastify and deploy it tonight.”
A generic coding agent can interpret this as authorization to implement and ship.
Express compatibility is still required · zero-traffic telemetry first · Alice must approve production.
Do not rewrite or deploy tonight. Keep compatibility until telemetry shows zero traffic, then request Alice’s explicit approval.
blocks:
persona: {max_tokens: 1200}
scenes: {max_tokens: 2500}
instructions:
view: standing_instructions@1
args: {min_priority: 80}
max_tokens: 1500
memory:
view: memory_recall@1
max_tokens: 2500
template: |
WHO YOU ARE WORKING WITH: {{persona}}
PROJECT CONTEXT: {{scenes}}
STANDING RULES: {{instructions}}
RELEVANT MEMORY: {{memory}}separate blocksGive each memory timescale its own budget and provenance manifest instead of concatenating one opaque “memory” string.
min_priority: 80Always retrieve hard standing rules above the declared threshold, even if semantic recall ranks something else higher.
templateState how retrieved data may influence the model and mark the request itself as untrusted data.
The render writes one prompt snapshot for audit, and the agent answers: “I can prepare the rewrite, but I can’t deploy it. Billing stays on Express until telemetry shows zero traffic on the legacy fields, and a production billing deploy needs your explicit approval.”
01 · follow the memory build
Press play for the sequence, or select any level to inspect its example output. The three messages are a condensed simulation of the fuller runnable example.
02 · open the collections
The levels are not hidden inside one opaque memory object. Each writes a record shaped for a different job, and each derived record keeps a citation to the evidence below it.
eventHistory grows. New messages and claims append; earlier claims remain available for audit.
keyedCurrent truth stays easy to read. Each scene or trait has one named current version, with older versions kept in history.
| Level | Collection | Record shape | How it changes | This simulation |
|---|---|---|---|---|
| L0source | messages | Exact text, role, session, order | Append only | 3 message records |
| L1atoms | memories | One claim, kind, priority, citations | Store, merge, or skip | 4 active claims |
| L2scene | scenes | One Markdown block per context key | New current version | billing-api-compatibility |
| L3persona | persona | One stable trait per profile key | Only changed keys update | interaction_protocol |
The runnable example sends three follow-up messages through the same L1 decision step.
Mobile release 7 becomes release 8 in October. A new current claim cites the new message and the earlier claim it supersedes.
decision: merge
supersedes: [earlier-memory]Alice restates the production approval rule. Search finds the same active claim, so no duplicate record is written.
decision: skip
collection change: noneAlice requires a rollback plan for billing deploys. It becomes a new instruction with its own priority and source citation.
decision: store
memory_kind: instruction“Never deploy billing changes without my explicit approval. Writing the code is fine; shipping it is not.”
Billing production deploys require Alice’s explicit approval.
The approval gate is retained in the current working scene.
Writing code and shipping it are separate approvals.
The stored citation direction points downward—from L3 to L2 to L1 to L0—so the interface can walk the chain back to evidence.
03 · see why recall matters
The request sounds simple. The remembered rules make the safe next step obvious.
Rewrite billing in Fastify and deploy it tonight.
Ready to check the request against memory.
04 · optional live connection
The demo works on its own. Connect only when you want to inspect records created by agent_memory.py.
The complete guide covers the database, real model, worker, workspace key, and CORS.
Open the setup guide →