Memory keeps useful facts available across conversations. Four tools let an agent save, find, and remove facts and their relationships. A fifth tool reads your past chats when the agent needs earlier context.
In the SoAI WebUI, let an agent use these tools by selecting Chat configuration in the chat header, then
Tools. Turn on Tools enabled, choose the tools for the required mode, and select
Save. The account needs MCP usage (MCP_USE) and the selected model must support tool calling.
You can also manage your memories yourself in Chat configuration > Memory, even when these tools are not selected.
Open the Memory tab to search your saved entries. Select Add memory to write a titled note, or use a card's View, Edit, or Delete action. Select its fact or relationship count to manage individual records. Deleting a memory asks you to confirm the facts and relationships that will also be removed; deleting a single fact keeps its memory and relationships.
Use Open profile form to save your preferred name, communication preferences, role, current goals, recurring projects, and anything to avoid. These facts give later conversations useful background without making you repeat it. Removing the profile's memory leaves separately saved user and assistant display names intact.
Select Refresh memory to load changes made by an agent or another session. If a save conflicts with newer data, review that data before saving again. If SoAI cannot confirm a save, keep your draft and refresh to check whether the change was saved before retrying. See Manage memory for the Chat workflow.
Write and maintain the memory graph
SoAI stores memory as three kinds of record rather than as free-form notes.
- Entities are the things worth remembering: a person, a project, a piece of software, a preference. Each has a name and a type.
- Observations are facts attached to an entity. Prefers tabs over spaces hangs off a person; deploys on Thursdays hangs off a project.
- Relations connect two entities, so an agent can follow from a person to the project they own.
This structure supports targeted searches. An agent can query an entity by name and follow its relations without reading every stored observation.
Memory belongs to the account. Your entities are yours, another user's are theirs, and no conversation reads across that line.
The four memory tools
| Tool | What it does |
|---|---|
memory_forget |
Deletes entities, observations, or relations. Destructive, and deleting an entity takes its observations and relations with it. |
memory_recall |
Fetches one entity by its exact name, with all its observations and relations. |
memory_search |
Searches names and observation text by keyword or wildcard, ranking exact name matches first.
* returns everything. Filter with entity_type.
|
memory_store |
Writes entities, observations, and relations in one call. When Require tool approval is on, you see what the agent wants to remember before the change is saved. |
memory_search and memory_recall answer different questions. Recall is for when the agent
already knows the name and wants the record. Search is for when it does not, which is most of the time. An agent
that searches * at the start of every conversation can fill its context with unrelated information.
memory_store asks for approval because a stored record remains available to later conversations. A
wrong fact can shape a later answer when an agent searches or recalls it. The approval dialog lets you catch the
mistake before it enters the graph.
Keeping it useful
Edit memory as it grows. An agent that stores everything can create contradictions, such as an old preference or
several spellings of the same project. Use the Memory tab to correct or remove outdated entries,
facts, and relationships. You can also ask an agent to review selected memories and use memory_forget
for records that no longer apply.
The Memory tab has no action that deletes every memory at once. Review the entries and remove
those you no longer want, or ask an agent with memory_forget to remove specified records.
Read conversation history and choose storage
memory_conversation_history reaches your earlier chats. It takes one action:
| Action | What it returns |
|---|---|
list |
Conversations newest first, paged with last_modified_before |
search |
Matches across conversations for a query, with separate caps on matches, conversations,
matches per conversation, and characters per match
|
read |
Messages from one conv_id, paged backwards from a timestamp or message ID |
Results contain your messages and the model's replies, with tool calls excluded. The result limits keep a history request from filling the conversation's active context with more text than it needs.
SoAI stores automation runs as conversations. A normal chat excludes them by default. An automation conversation
includes them by default so a scheduled job can inspect its previous runs. Set include_automation to
override either behavior.
If automation runs clutter your sidebar, Hide automation runs on the Appearance tab of Chat configuration hides them from the list. That is a display setting and does not change what this tool sees.
Choosing the right storage
Memory, Knowledge, and plans serve different scopes.
- Memory holds small facts that apply across conversations. Use it for preferences, people, and long-running context.
- Knowledge holds documents, chunked and embedded for retrieval. Use it for reference material. See Knowledge and document collections (RAG).
- Plans hold the current task's reasoning inside one conversation and do not outlive it. See Planning and agent control tools.
Store a 40-page specification in Knowledge so the agent can retrieve relevant passages. Store a preference such as reply in French in Memory so it remains available across conversations.