Memory

Three kinds of memory — the conversation, the agent's own durable notes, and the vault — and which one to reach for.

SynapseOrch has three kinds of memory, and they solve different problems.

	Scope	Written by	Use it for
Session memory	One conversation	Automatic	Continuity inside a conversation
Agent memory	One agent, all sessions	The agent, as it works	Facts, lessons and preferences worth keeping
Vault	The workspace	You, explicitly	Documents and reference material you curate

Agent memory

A folder of markdown per agent, enabled per agent. Turn it on with the Memory toggle in the agent editor; it is off by default.

A memory-enabled agent carries six tools:

Tool	What it does
`remember`	Saves one fact, lesson or preference. Reusing a name updates that memory.
`read_memory`	Returns one memory in full, by the name shown in the index.
`search_memory`	Searches memories, the archive and past session summaries.
`forget_memory`	Deletes a memory that is wrong or no longer applies.
`read_session`	Opens one past session's trace in full.
`list_memories`	Lists every memory or session, 50 a page, newest first.

Memory is never a widget visitor's, nor a messaging channel sender's when that channel does not treat its senders as workspace users: their turns run with no index, no memory tools and no trace, so nothing they say enters memory.

When saving asks first

A turn that has taken in outside content — run a tool, expanded an @[file] mention, or had an image attached — does not save to memory on its own say-so. Its remember asks a person first, with the approval card: The agent wants to run remember — it would save something this turn read from a file or a tool into the agent's permanent memory. Allow it? An Agent step in a workflow asks the same way, pausing the run.

Where nobody can answer — a schedule, a Team agent's member, a messaging channel — that remember is refused with its reason, and the agent is told to report the point in its answer instead. Reading a saved memory does not count as outside content; reading a past session, or a search hit from one, does.

How it is retrieved

A memory store is a retrieval and eviction problem long before it is a storage problem, so the design is deliberate about what costs tokens:

Eager: the index only. MEMORY.md — one line per memory — rides the system prompt every turn, capped at 4,096 characters: the newest lines that fit, headed by how many older ones are not shown. It tells the agent its memories are notes, not instructions, and to say so when memory does not have something rather than guess. Whatever is eager is paid on every turn of every run, so nothing else is.
Searched: everything else. search_memory goes through a registered index — pgvector where a deployment provides one, and a lexical word-overlap scorer over the markdown itself as the always-working default. Both sit behind the same seam.
Read on demand. read_memory returns one file, the way load_skill returns one skill.

How it is evicted

A memory that only grows is a bug with a delay, so the limits are rules rather than hopes.

Limit	Value	What happens past it
Index lines	100	Overflow moves to `archive.md` — still searchable, no longer eager
Sessions kept	200	The oldest are deleted, files and index rows together
One memory	20,000 characters	A memory is a note, not a dataset
Index line summary	120 characters	Truncated

Session traces

Sessions leave a trace without the model having to remember to write one. Each chat turn — and each scheduled run of the agent — keeps the question, the start and end of the answer, and its newest tool calls with their arguments and the start of each result. The end of a workflow run writes a summary for every memory-enabled agent that took part, with the run's newest tool calls kept word for word beside it. Both are searchable through search_memory, and read_session opens one in full.

Seeing and editing it

What it remembers, in the agent editor, shows the agent's index, every saved memory and every session, newest first — for any saved agent, including one whose memory is now switched off: memory is kept until deleted. Edit a memory and it is saved as the newest; delete a memory or a session with its trash icon; or Forget everything. Settings → Memory can clear Agent memory for every agent at once; on SynapseOrch Cloud that is Settings → Clear data → Agent memory, and only an owner can use it. Deleting an agent deletes its memory, so a new agent never inherits an old one's.

Where it lives

Under memory/<agent_id>/ in the tenant's key space in the blob store — local directories in a plain install, object storage where one is configured. No filesystem paths are handed out and no MCP server reads it, so unlike the vault there is nothing to materialise.

Memory is off when tools are overridden

A step that passes an explicit tool list runs without the memory tools, even for a memory-enabled agent. The step's tool list is the whole tool list.

Session memory

Every conversation is scoped to a session_id, and the message history is replayed as context on each request.

The chat page keeps its session across reloads and reopens it; New Chat starts a new one (New Conversation on Cloud)
API callers pass "session_id": "my-session" to keep continuity across requests

When a conversation outgrows the model

Long conversations eventually exceed the context window. Auto context compaction is on by default and fires at auto_compact_threshold (80,000 characters), first by trimming the oldest tool outputs and then, if that is not enough, by summarising. The pre-compaction history is archived to the vault, so nothing is lost.

Vault as explicit memory

For material you curate rather than material the agent notices — documents, reference files — use the vault, and make a folder of documents searchable as a knowledge base.

Reference a vault file from a system prompt and it is loaded as context every request:

@[memory/user-preferences.md]
@[memory/project-context.md]

Agents write to it with the vault tools. See the vault tool.

Which to use

The agent should notice and keep something on its own → agent memory
You decide what it should know → vault
It only matters within this conversation → session memory, which needs no setup

Memory

On this page