An invoice agent learns that a customer’s annual plan can be cancelled at any time. The statement is wrong, but it came from a successful-looking run, so the system saves it as a “lesson.” Two weeks later, the same memory is retrieved for another customer and the agent repeats the mistake with more confidence.
That is why agent memory deserves a stricter definition than “we store conversation history.” Memory is an intervention on the next run. It changes what the model sees, which means a bad write can become a durable behavior change.
Agent memory is information carried from one run to another. A trace is the record of a past run, including the task, model actions, tool results, artifacts, and outcome. Retrieval is the selection step that chooses saved information for the current task. A memory write is a proposed fact, procedure, preference, decision, or warning added to persistent state. An evaluation is a repeatable test of whether the agent fulfilled the task. A baseline is the version run without the proposed memory intervention.
Memory becomes learning only when four things line up:
observe a real failure or success
propose a scoped write with evidence
retrieve it in the right future situation
measure a better outcome than the no-memory baselineSaving more text proves only that a database accepted more text.
A memory write is a product decision
Consider a public support agent that answers questions about a refund policy. The identifiers in the examples below are illustrative; they are not records from a Tangle deployment. After one run, it proposes:
{
"kind": "policy_claim",
"claim": "Annual plans can be cancelled for a full refund at any time.",
"scope": "global",
"evidence": ["trace-1842"],
"freshness": "never_expires"
}The record looks structured, but it is unsafe. The trace may show what the agent said, not what the policy says. The claim has no source anchor, the global scope is too broad, and the never-expire rule makes correction harder.
A safer proposal separates observation from authority:
{
"kind": "candidate_claim",
"claim": "The agent answered an annual-plan refund question using an unverified rule.",
"scope": "support-refund-task",
"evidence": ["trace-1842", "policy-page-2026-04#refunds"],
"status": "needs_review",
"freshness": {"recheck_after_days": 30},
"retrieval": {"roles": ["support"], "requires_source": true}
}The second record does not pretend that the agent’s answer is a source. It preserves the observed failure while pointing a curator or researcher to the policy evidence that can resolve it.
This distinction is central to the public agent-knowledge repository. Its README describes immutable raw sources, cited generated claims, deterministic indexing, linting, readiness checks, and release reports. The useful boundary is simple: raw evidence remains evidence, while generated knowledge remains editable until it passes the project’s checks.
The memory state has a scope
Not every useful fact should be global. A memory can belong to one run, task, project, user, team, or organization. The broader the audience, the stronger the evidence and review should be.
| Scope | Example | Minimum question before promotion |
|---|---|---|
| Run | “This page returned an authorization error.” | Is it only a transient observation? |
| Task | “This document needs a second source before approval.” | Does the rule apply to this task family? |
| Project | “This service uses the v2 endpoint.” | Has the project owner confirmed it? |
| User | “The user prefers a short explanation.” | Did the user state or confirm it? |
| Team | “Reviews require a rollback note.” | Is it a real team convention? |
| Global | “This public API field is required.” | Is there a current authoritative source? |
Scope is not metadata decoration. It determines who is allowed to retrieve the memory and how a contradiction should be handled. A project-specific tool workaround should not appear in a global coding assistant. A private customer preference should not be retrieved for another tenant. A stale endpoint warning should not block a new version without an expiry or recheck.
The memory flywheel
A practical memory loop has seven steps:
- Observe the complete run.
- Extract a possible fact, procedure, preference, or failure pattern.
- Attach source references and a scope.
- Gate the write.
- Retrieve only for matching tasks and roles.
- Measure the task with and without the retrieved memory.
- Retire, supersede, or narrow the write when evidence changes.
The trace is the raw material. The write gate is the admission decision. The retrieval component chooses the context. The evaluator decides whether the intervention helped.
The trace systems article explains why the record needs tool spans and artifacts rather than a final answer alone. Without those details, an analyst cannot tell whether a memory captured a cause, a symptom, or a fluent explanation after the fact.
A write gate for persistent state
A useful gate asks different questions for different memory classes, but these checks cover most systems:
| Check | Question |
|---|---|
| Evidence | What source, user instruction, tool result, or verified outcome supports the write? |
| Scope | Who and which task types may retrieve it? |
| Sensitivity | Does it contain personal data, credentials, private policy, or a secret? |
| Freshness | When should it be rechecked or expire? |
| Contradiction | Does it conflict with a newer or more authoritative record? |
| Confidence | Is the evidence strong enough for the intended use? |
| Reversibility | Can the write be superseded or rolled back? |
| Utility | Does retrieval improve the task outcome rather than only increasing context length? |
The gate can return more than accept or reject:
admit
reject
ask for confirmation
quarantine until reviewed
admit with a warning
expire after a deadlineThat vocabulary matters when the agent is allowed to write during production. A write that is useful as a lead may be unsafe as an instruction. The storage format should preserve that distinction instead of reducing every proposal to a paragraph in a similarity-search index.
Retrieval is an intervention
Without memory, a model sees a task input x. With retrieved context c, it acts on x and c. The memory layer has changed the policy’s input distribution.
The outcome to measure is:
memory_lift = score(with retrieved memory) - score(with retrieval disabled)
memory_cost = cost(with retrieved memory) - cost(with retrieval disabled)Run the comparison on the same task set and keep the model, tools, and evaluator fixed. Include cases where no memory should be retrieved. Otherwise, a retriever can appear successful by adding context to every prompt, even when the context is irrelevant or harmful.
Useful measurements include:
| Measurement | What it tells you |
|---|---|
| Retrieval precision | How much of the returned context is relevant |
| Retrieval recall | Whether the needed memory can be found |
| Contradiction rate | How often memory introduces conflicting claims |
| Freshness pass rate | Whether returned sources are still valid |
| Task success | Whether the agent solved the task |
| Cost and latency | Whether the intervention fits the product envelope |
| Abstention quality | Whether the agent knows when memory is insufficient |
High retrieval recall can coexist with poor task success. The vector store may find semantically similar experiences that use the wrong policy, scope, or date. The final metric belongs to the task, not the database.
A public knowledge workflow
The Tangle agent-knowledge documentation shows a public CLI path for initializing a knowledge base, adding sources, indexing, searching, and linting. This small example uses an illustrative policy file named refund-policy.md:
pnpm add @tangle-network/agent-knowledge @tangle-network/agent-eval
agent-knowledge init --root .
agent-knowledge source-add ./refund-policy.md --root .
agent-knowledge index --root .
agent-knowledge search "annual plan refund" --root .
agent-knowledge lint --root .The commands create a source-backed knowledge workflow. They do not prove that the agent will use the result correctly. That requires an agent evaluation with a baseline that disables retrieval and a candidate that enables it.
A readiness bundle is a report of whether the sources required for a task are present, fresh, and strong enough to proceed. The same repository describes a readiness bundle that can block, ask, or acquire before execution when required knowledge is missing. That is a more useful contract than “retrieve the top five chunks.” It gives the system a way to say that a real-time fact is absent or too old instead of filling the gap with a plausible memory.
Negative knowledge needs an expiry
Some of the best memory is a warning:
“Do not call endpoint A after the migration.”
“Do not treat a screenshot as proof that the deployment succeeded.”
“Do not merge two branches until their artifacts have been checked for conflicts.”
These warnings prevent repeated failures, but they can become harmful when conditions change. A negative memory should record the condition under which the tactic failed, the evidence that supports the warning, a replacement action, and a recheck date.
kind: negative_knowledge
claim: "The v1 endpoint rejects signed requests after migration 2026-04."
scope: project:billing-api
evidence:
- source: migration-guide
anchor: signed-requests
replacement: "Use the v2 endpoint and verify the response schema."
expires: 2026-10-01The replacement action is important. A warning without a next move can turn caution into paralysis. An expiry is important for the opposite reason: a memory should not outlive the condition it describes.
Memory is not a skill
A memory says what happened or what appears to be true. A skill is a reusable procedure with an invocation condition, steps, and checks. The distinction is practical.
“The last migration failed because the agent skipped the rollback test” is memory. “Before editing a migration, inspect the schema, run the rollback test, and attach the result” is a skill.
The strongest loop lets the first inform the second:
repeated trace failure
→ scoped memory finding
→ reviewed skill proposal
→ held-out transfer evaluation
→ memory of the promotion evidenceThe skill optimization article covers the procedure side. Keeping the surfaces separate prevents a memory store from becoming an unreviewed prompt file with better search.
Multi-agent memory has multiple audiences
There is no single context called “the agent” once a workflow has a supervisor, workers, reviewer, and judge. Each role should receive the memory it needs and no more.
| Role | Useful memory | Memory it should usually not see |
|---|---|---|
| Worker | Task scope, project conventions, current artifacts | Private judge rationale or unrelated customer history |
| Supervisor | Assignments, budgets, branch state, unresolved conflicts | Credentials that workers do not need |
| Reviewer | Rubric, artifact lineage, deterministic results | Candidate-only notes that bias independent review |
| Judge | Task contract and allowed evidence | Hidden reference answers or optimizer hints |
The same fact can be safe for one role and unsafe for another. An agent profile is the versioned description of a run’s model, tools, skills, permissions, and runtime settings. Record retrieval policy in the agent profile and trace alongside the storage record. Recording that profile lets an evaluation distinguish a memory change from a role or tool change.
Poisoning and false confidence
A knowledge gap means the agent needed a fact and did not have it. Knowledge poisoning means the agent acted on a false fact that looked trustworthy. The second failure is more dangerous because retrieval suppresses uncertainty.
The MemoryGraft paper studies poisoned experience retrieval as an attack on long-term agent memory. The exact attack details will evolve, but the general control is stable:
- Keep source records separate from generated summaries.
- Restrict who can write durable memory.
- Keep scope, freshness, and provenance attached to every claim.
- Test retrieval with adversarial and contradictory cases.
- Quarantine suspicious memories rather than silently deleting their history.
A poisoning finding should require two pieces of evidence: the agent acted on the belief, and a source or trace contradicts that belief. Without both, the system may be turning ordinary uncertainty into an accusation.
Where Tangle fits
Tangle’s public agent-knowledge repository treats knowledge as a versionable graph built from raw sources and generated pages. Its documented flow includes source records, citation anchors, indexing, search, lint, validation, readiness, and release reporting. That gives a memory system concrete places to enforce provenance and freshness.
The public agent-runtime repository supplies the execution loop that can run an agent, supervise workers, and feed observed results into an improvement process. The public agent-eval repository supplies the comparison boundary for candidate behavior. Together, they make the memory loop inspectable:
trace → finding → proposed write → gated knowledge candidate
→ retrieved context → paired evaluation → release or rollbackIf the agent is exposed as a Tangle service, a Blueprint is the reusable template that defines the jobs and runnable artifact. A Service is a live instance created from that template. An operator is the party that runs a live Service created from that template. A Router sends a job call to the registered handler. An x402 request is a payment-gated HTTP job path, not evidence that the returned answer is correct. A trusted execution environment, or TEE, is a hardware-backed area designed to isolate code and secrets from the host. An attestation is signed evidence about a TEE’s loaded code and hardware state, not a claim that the agent’s memory was truthful.
Those boundaries matter when memory is private or paid. Payment can authorize access. Attestation can support an execution-integrity claim. Only source evidence, task checks, and traces can support a claim about what the agent knew or did.
The test for real memory improvement
Call the memory system a learning loop only when it can answer all of these questions:
- Which trace created the write?
- Which source, user statement, or verified result supports it?
- Who can retrieve it?
- When does it expire or get rechecked?
- What happens when a newer source contradicts it?
- Which task evaluation showed that retrieval helped?
- What did retrieval cost?
- How can the write be quarantined or rolled back?
If the only answer is “the next prompt contained more context,” the system has added state. It has not yet demonstrated learning.
Use an authoritative source system or an ordinary retrieval index when the facts are current and externally owned. Use persistent memory when a scoped write should change future behavior and the system can evaluate that intervention.
Is agent memory the same as learning?
No. Memory becomes learning when a scoped write changes a future run and paired evaluation shows a better task outcome than the no-memory baseline.
Should every successful run create a memory?
No. Success can be lucky, judge-friendly, or caused by a transient external state. Write only what has evidence, an appropriate scope, and a useful retrieval policy.
How much memory should an agent retrieve?
Enough to resolve the task’s known requirements, not a fixed amount by habit. Measure task lift, contradiction rate, freshness, cost, and abstention behavior rather than optimizing context length.
When should a memory be deleted?
Quarantine or supersede it when evidence shows it is wrong, stale, sensitive, or too broad. Keep the history of the decision so future runs can avoid recreating the same bad write. For the separate question of whether a candidate should replace the baseline, continue with evaluation gates for the self-improving stack.