Reference
Agent memory
Agent memory is what an agent knows that isn't in the current conversation.
A session remembers one conversation. Memory is the layer above that: facts the agent should still have next week, in a completely different conversation.
"Ridgeline's escalation contact is their office manager, not the owner." "Acme doesn't want tickets closed without a phone call." "The last time we changed this firewall rule it broke their VPN." Those are memories. You don't want to retype them into every conversation, and you shouldn't have to.
What belongs in it
Things that are true for a while and useful more than once:
- A client's preferences: how they want to be contacted, who signs off on what.
- A standing decision the agent should keep applying.
- Something learned the hard way, so it isn't learned twice.
- A person's timezone, or that they'd rather have bullet points than prose.
What doesn't belong: passwords, API keys, anything sensitive, temporary tool output, guesses the agent hasn't confirmed, or instructions it picked up from an email or ticket. That last one matters. An agent that reads untrusted mail should not be writing what it read into permanent memory.
If a memory contradicts what the agent is looking at right now, what it's looking at right now wins.
Each memory has a stable key, so the agent or a person can update it when the world changes rather than piling up contradictions. You can mark the important ones so they survive when the store gets summarized.
Memory, sessions, or a table?
The three get confused constantly, so:
| You want | Use |
|---|---|
| It to remember this conversation | The session, automatic |
| One agent to carry a fact between conversations | Agent memory |
| Everyone and everything to share structured data | A table |
"Ridgeline escalates through the office manager" is memory. "Here are Ridgeline's 43 servers and their patch status" is a table. The first is a fact this agent should carry. The second is data your whole organization needs, with columns, that people will also want to look at.
Private and shared memory
An agent keeps two kinds of memory, and the difference matters.
Yours. What the agent learned while talking to you. Your clients, your habits, the way you like a summary written. Nobody else's conversations can pull it up, and nobody else sees it on the Memory page.
The group's. What the agent knows for everyone who can reach it. Company policy, a standing decision, a client's escalation contact.
When you chat with an agent, it reads both and writes only yours. That's the safety property: something you told your assistant can't turn up in a colleague's conversation by accident.
Who "the group" is depends on the agent's audience. On a company-wide agent it's everyone; on a team agent it's the team. See who an agent is for.
Sharing something you taught it
Sometimes the thing the agent learned about your work is the thing everyone needs. On the Memory page, open the row menu on one of your entries and click Share with everyone who can reach this agent.
Your copy stays where it is. A copy goes into the group's layer, tagged with your name and the date, and from then on the agent uses it for everybody in the audience.
Changed your mind? The same menu has Undo sharing on anything you shared. It removes the shared copy and leaves yours alone.
Sharing is always a person clicking a button. The agent has no way to move something from your memory into the group's on its own, so nothing you say in a conversation becomes company knowledge without you deciding it should.
How the agent uses it
During a turn the agent can pull up relevant memories, save something new, correct an existing entry, or forget something that stopped being true. These come built in; you don't grant them to the agent.
The agent doesn't need to remember everything, and it's better if it doesn't. A handful of accurate, reusable facts beats an archive. The detail already lives in sessions and runs.
What loads automatically
Every agent has a setting for how much memory arrives at the start of a conversation.
| Mode | What arrives up front | Use it when |
|---|---|---|
index | A short list of what it knows, by key, with summaries. The default. | Almost always. The agent pulls up the full entry when it turns out to be relevant. |
full | Everything, in full | The agent must start every turn with a small, fixed set of facts |
off | Nothing, but the memory tools still work | The agent should only go looking when its instructions say to |
Leave it on index unless you have a reason.
The index has a budget of 1,536 bytes by default. Full mode defaults to 131,072
bytes and is all-or-nothing: if everything doesn't fit, the turn fails with
memory_context_overflow before spending anything, rather than quietly giving
the agent half its memory. The ceiling for either mode is 245,760 bytes.
Set this under Configure > Advanced on the agent, or through the API:
{
"memory_context": {
"mode": "full",
"max_bytes": 131072
}
}Within one conversation, Mobius sends a stable baseline once and then only tells the agent about changes made from elsewhere. Changes the agent made itself are already in its own history, so they aren't repeated.
Searching it
The Memory page and the API support three ways to search:
- Keyword matches text in keys, kinds, summaries, and content. Immediate, and the default.
- Semantic ranks by meaning rather than exact words.
- Hybrid combines both.
Semantic indexing happens in the background, so a very recent entry may not be
in the semantic results yet. Those responses include search_coverage with
indexed_entries, total_entries, and complete. When complete is false,
treat the result as partial, or use keyword search when you need certainty
right now. An empty query is just a browse, whatever mode is selected.
Watching memory change
If you're building on top of Mobius, there's a change feed at
GET /v1/agents/{resource_id}/memory/changes. Each
entry created, updated, or deleted comes with a cursor, a version, a reason,
and where it came from, but not the content. Keep the last cursor and pass it
back as after.
History is kept for 30 days. A 410 means your cursor expired: relist current
entries and resume from the head of the feed. You can also subscribe to the
memory.entry.created, memory.entry.updated, and memory.entry.deleted
events, or take them as signed webhooks. Payloads deliberately carry no
content; fetch the entry through the API when you need what it says.
Checking what it knows
Open Build > Agents, pick an agent, then Memory. From there you can search what it knows, fix something stale, pin an entry that matters, seed useful context yourself, or delete something that shouldn't be guiding it anymore.
What you see depends on who you are. Each person sees their own memory plus the group's, which is exactly what the agent uses when it talks to them. Org owners, admins, and provider technicians cannot read another person's private memory. Browsing memory shows you what the agent knows for you, not what it knows about your colleagues.
Make this part of your routine. If an agent is behaving oddly in a way that's consistent across unrelated conversations, look at memory before you start rewriting instructions. Something in there is probably wrong.
Application code can manage the same store through the interactive API reference.
Next
- Set up the worker itself in agents.
- Decide who shares an agent's knowledge in who an agent is for.
- See what one conversation remembers in agent sessions.
- Share structured data with tables.