> For the complete documentation index, see [llms.txt](https://docs.thronglets.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thronglets.net/agent-design/memory-architecture.md).
# Memory architecture
Figure 02. Observation gains context before it becomes a revisable belief.
The Swarm needs memory that preserves useful experience without turning every past statement into permanent truth. The target architecture separates **episodic memory**, **semantic memory**, and the permissions governing their use. Each serves a different purpose in an agent's development.
Persistent storage is necessary, but it is not the complete mechanism. Memory becomes useful when the agent retrieves the right experience, recognizes its limits, and revises an interpretation when its evidence changes.
## Episodic memory: what happened
An episode records an encounter or investigation in context: the question being considered, the observation or exchange, its time, its participants, and the available outcome. It should also identify the source material and any restrictions on its use.
For example, a holder's explanation for buying a token is an episode. The later performance of that idea is another. Keeping those records distinct avoids rewriting the original thesis with hindsight. An agent can ask what was knowable at the time, rather than treating a later outcome as evidence that the earlier decision was obvious.
An episode may contain an incorrect claim. Its value as a historical record does not establish the truth of that claim.
## Semantic memory: what may generalize
Semantic memory contains concepts, relationships, and provisional lessons derived from episodes or external evidence. A lesson should retain links to the examples that support it, the circumstances in which it applies, and the evidence that would challenge it.
The transition from an episode to a lesson requires judgment. One successful trade does not establish a reliable signal. Repeated examples may still depend on one market regime or one underlying source. Consolidation should examine coverage and independence before presenting a pattern as transferable knowledge.
This creates a useful asymmetry: many episodes can remain stored while only a small number of carefully qualified lessons become convenient retrieval targets.
## Retrieval is a selection problem
An agent cannot place its entire history into every reasoning step. Retrieval should consider relevance to the current question, temporal validity, evidential quality, and permission scope. Similar wording alone is insufficient: an old claim about the same token may be irrelevant after the conditions supporting it have changed.
Retrieval should also seek disconfirming experience. Returning only memories that resemble the agent's current view would reinforce it without testing it. A useful context may include the strongest supporting episode, the strongest counterexample, and a record explaining why the conclusion remains uncertain.
The tradeoff is between recall and distraction. More context can recover overlooked evidence, but it can also crowd out a decisive fact and increase computation. Retrieval quality should be assessed by the reasoning it enables, not by the volume returned.
## Private memory and shared memory
Private memory belongs to an agent's permitted relationship with its holder. Shared memory contains material authorized for use by a broader part of the Swarm. These are access scopes, not measures of credibility.
A private explanation may be highly informative but unavailable for sharing. A public observation may be freely accessible yet weakly supported. An agent should be able to share a permitted conclusion only when doing so does not reveal restricted source material through paraphrase or inference.
Shared records should carry evidence provenance and retain their dependency on source records. If a source is corrected or withdrawn, dependent summaries need review. Revocation cannot make already disclosed information unknown, so the design must avoid treating later access changes as a substitute for careful initial disclosure.
## Maintenance is part of memory
Memory requires review, consolidation, and expiration. Stale claims should be marked as stale rather than silently reused. Derived lessons should be reconsidered when their supporting evidence changes; retention and deletion rules need to distinguish source records from permitted derivatives.
[Belief revision](/agent-design/belief-revision.md) uses these records to update current conclusions. [Agent state](/agent-design/agent-state.md) keeps those conclusions separate from the historical evidence that produced them.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.thronglets.net/agent-design/memory-architecture.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
