Agent Memory

How working, session, and long-term memory work in Prisme.ai agents: the layers, the tools, and the data flow.

Prisme.ai agents have three independent memory layers. Each one answers a different question, runs on its own backend, and is toggled separately. The rest of this page focuses on long-term memory, but the table below makes the three layers explicit so you know which one to reach for.

The three layers

Layer	Question it answers	Scope	Backend	How it’s updated
Working memory	”Does my agent remember what we said 5 messages ago in this same conversation?”	One conversation	Conversation database	Automatic: past turns of the current conversation are reloaded into the prompt at each turn
Session memory	”Does my agent remember what we discussed in a different conversation earlier today?”	One user × one agent, across their conversations, for the duration of the user’s login session	User session store, reset at each new login	Automatic: after the first completed exchange of each conversation, the platform asks an LLM to merge that exchange into a rolling summary, which is added to the agent’s instructions in the user’s later conversations
Long-term memory	”Can my agent save a specific preference I tell it to remember and recall it later?”	One user × one agent	Dedicated memory service	Tool-driven: the agent calls memory_remember when something is worth keeping; memory_recall (and an automatic pre-load) brings it back later

Practical consequences:

• Without working memory an agent is effectively stateless between turns inside a single conversation.
• Session memory is the only layer that bridges separate conversations automatically. It produces a compact LLM-written summary, not a verbatim transcript.
• Long-term memory never saves silently. The agent must call memory_remember; that’s why “Tell the agent what’s worth remembering” in your Instructions matters.

If you inspect an agent’s raw memory config, the structure is:

{
  "session_memory": true,
  "types": [
    { "id": "working_memory", "enabled": true, "config": { "max_tokens": 8000, "compaction_strategy": "hybrid" } },
    { "id": "long_term",      "enabled": true, "config": { "max_memories": 50 } }
  ]
}

session_memory is a top-level toggle, separate from types[] which holds working memory and long-term memory side by side. The three are fully independent; you can enable any combination.

You edit this JSON in the agent’s Memory capability (Capabilities → Memory → Parameters (JSON)). The profile sets its values when the agent is created and each time the profile changes: session_memory is true on Workflow, Light Agent, Full Agent and Orchestrator (only Simple sets it to false), and long_term is enabled on Full Agent and Orchestrator. The session_memory: false shown in the default JSON of the capability catalog only applies when you add the Memory capability by hand.

Working memory: budget and compaction

Working memory reloads past turns of the current conversation into the prompt. Left unchecked, a long conversation, or one big tool result, would grow the prompt until every reply becomes slow, expensive, or rejected by the model. Two settings keep it under control.

max_tokens: the working-memory target

Sets the target size of the conversation history reloaded at the start of each turn (default: 8000 tokens; the effective value is clamped to at least 8000 and never more than the model’s usable context). When the reloaded history exceeds this target, the older turns are summarized into a rolling summary that is persisted and reused on later turns, they are not dropped. The most recent turn is always kept verbatim, and summarization happens at whole-turn boundaries so tool-call sequences are never corrupted.

The summary is written once, at load time, and reused at no extra cost on subsequent messages; it is only refreshed when the history grows past the target again. This is the same mechanism a coding assistant uses to keep a long session in memory: recent turns stay verbatim, everything older lives on as a compact summary that carries the decisions, facts and results forward.

The model’s context budget (which drives both this target’s ceiling and the mid-turn compaction threshold below) is derived automatically from the configured model’s real context window, so a larger-window model gets a proportionally larger working memory with no extra configuration.

compaction_strategy: what happens when the live conversation grows too large

During a single turn, an agent can loop through many tool calls and accumulate a large context. When the context reaches ~70% of the model’s context budget, the platform compacts it mid-conversation. The user sees a “Compacting conversation history” step in the response, only when something was actually compacted.

Value	Behavior	When to choose it
hybrid (default)	First pass replaces old tool results with compact stubs (cheap, no LLM call). If the context is still too large on a later iteration, escalates to a summarization pass.	Best default: cheap first, thorough when needed.
summarize	Summarizes the oldest part of the conversation with an LLM call, keeping the recent turns intact. The summary is injected back into the conversation.	Conversations where old dialogue (not tool output) is what grows.
compact_tool_results	Only replaces old tool results with stubs; never summarizes.	Cost-sensitive agents where an extra LLM call per compaction is unacceptable.

Any other value falls back to hybrid and emits a memory.config.invalid_strategy warning event; it is never silently ignored.

Two more context guards run automatically and require no configuration:

• Large tool results are offloaded. A tool result above ~30,000 characters is stored as an artifact instead of entering the prompt. The agent sees a preview plus the artifact id, and reads further pages with get_artifact only if it needs them (~20,000 characters per page). Large documents can be edited without a full rewrite via the patch_artifact tool.
• A hard pre-flight ceiling. Before each model call, the platform estimates the context size. If it would exceed the model’s context budget and cannot be compacted enough, the turn fails with an explicit CONTEXT_OVERFLOW message (instead of an opaque provider error) and nothing is billed for that call.

The rest of this page focuses on long-term memory, the layer that lets your agent remember a user’s preferences from one week to the next, on explicit cue.

Choosing which layers to enable

A quick decision guide for new agents:

Agent style	Working memory	Session memory	Long-term memory
One-shot Q&A bot (each question is independent)	✗	✗	✗
Multi-turn assistant inside a single chat	✓	✗	✗
Recurring assistant the same user comes back to over days/weeks	✓	✓	optional
Personal assistant that should remember explicit user preferences	✓	✓	✓

Session memory’s summary is generated asynchronously, so enabling it doesn’t add latency to user-facing responses. It is kept in the user’s login session: a new login starts from an empty summary, and it is never shared with another user. The Playground never uses it: test it from the published agent.

Turn off cross-conversation memory

To keep each conversation strictly isolated, turn off session memory, and long-term memory if the agent has it, while keeping working memory.

1. Open the Memory capability

   In the agent, go to Capabilities and open Memory.

2. Edit Parameters (JSON)

   Set session_memory to false. On Full Agent and Orchestrator, also set long_term to "enabled": false. Keep your current working_memory values: that is the memory of the current conversation.

   {
     "session_memory": false,
     "types": [
       { "id": "working_memory", "enabled": true, "config": { "max_tokens": 4000, "compaction_strategy": "summarize" } },
       { "id": "long_term", "enabled": false, "config": { "max_memories": 50 } }
     ]
   }
   
3. Save, then republish the agent

   Conversations run the published version. From the next message on, in every conversation, the agent no longer reads or writes the session summary.

4. Check the isolation

   In the published agent, not the Playground, share a distinctive fact in one conversation, then open a new conversation and ask for it. The agent does not know it, while it still remembers earlier messages of the same conversation.

Through the API, send PATCH /v1/agents/{agent_id} with the updated tools array and without the profile field, then POST /v1/agents/{agent_id}/publish.

• Don’t remove the Memory capability to turn memory off. If it is the agent’s only capability, the profile restores it at run time, session memory included. If the agent has other capabilities, removing it also turns off working memory: the agent forgets earlier messages of the current conversation.
• A profile change resets these values to the profile’s (session_memory: true on every profile except Simple). Repeat the change after any profile change.
• Turning it off doesn’t erase anything. The summary already built stays in the user’s login session and comes back if session memory is turned on again; a new login starts from scratch. Long-term memories stay stored until they are forgotten or wiped.

How long-term memory works

Long-term memory is provided by a dedicated memory service. The agent does not store memories itself: it calls three tools, and the service handles persistence and retrieval.

            ┌──────────────────────────────────────────────┐
            │                Conversation                  │
            │                                              │
   user ─►  │  ┌─ pre-load ──────────────────────────┐    │
            │  │ relevant past memories injected     │    │
            │  └────────────────────────────────────-┘    │
            │                  │                          │
            │                  ▼                          │
            │             [ Agent / LLM ]                 │
            │            /     │      \                   │
            │  remember()  recall()  forget()            │
            │       │          │         │                │
            └───────┼──────────┼─────────┼────────────────┘
                    ▼          ▼         ▼
                ┌──────────────────────────────┐
                │      Memory service          │
                │  (vector search + storage)   │
                └──────────────────────────────┘

Three tools the agent uses

When long-term memory is enabled on an agent, three tools are injected into its toolkit. The agent decides on its own when to call each one.

memory_remember

Store something worth keeping for next time.

Called when the user shares a preference, a fact, an ongoing instruction, or a relationship the agent should not forget.

memory_recall

Search past memories by meaning, not just keywords.

Called when the agent needs context that may have come from an earlier conversation.

memory_forget

Delete a specific memory.

Called when the user asks to forget something or the information is outdated.

Automatic pre-load on every user message

On every user turn, before the LLM is called, the platform loads the user’s most recently updated memories for this agent, up to max_memories (default: 50), and injects them into the prompt. The agent sees them as background context and can answer without explicitly calling memory_recall.

This means the user often does not need to remind the agent of past preferences; the agent already has them in front of it, fresh for each message.

Recall order

When the agent calls memory_recall, the service returns the user’s memories for this agent, most recently updated first, up to the requested number. Each memory is stored with a vector embedding, but recall does not rank memories by semantic similarity: the wording of the question does not change which memories come back. Keep max_memories large enough for the memories that matter to stay within reach.

Memory types

Every memory has a type that helps the agent reason about its purpose.

Type	What it represents	Example
fact	A stable piece of information about the user	”User’s company is Acme Corp.”
preference	A like, dislike, or stylistic choice	”Prefers concise answers over long ones.”
relationship	People, projects, or entities the user is connected to	”Works with Marie on the onboarding project.”
instruction	Standing rules the agent should follow	”Always reply in French unless asked otherwise.”

The agent picks the type when calling memory_remember. You don’t need to manage types yourself.

Scoping

Memories are stored per user and per agent. A memory saved by an agent through memory_remember is visible only to that agent, for that user.

The memory service also accepts user-wide memories (scope: global), which every agent of that user loads. Agents never save memories at that scope themselves.

Two different users never see each other’s memories.

Tags

When the agent stores a memory, it can attach a small set of short lowercase keywords describing the topic, for example ["python", "coding"] or ["family", "children"]. Tags help the agent group, filter, and recall related memories more precisely.

Configure long-term memory on an agent

1. Choose a profile that supports it

   Long-term memory is available on the Full Agent and Orchestrator profiles. Simpler profiles do not include the memory tools.

2. Check the Memory capability

   In Capabilities → Memory → Parameters (JSON), the long_term entry must have "enabled": true. Full Agent and Orchestrator set it when the agent is created or its profile changes. Save and republish after any change.

3. Set the recall budget

   In the same JSON, config.max_memories sets how many memories the agent can pull in per turn (default: 50). Higher values give the agent more context but consume more of the prompt window.

4. Tell the agent what's worth remembering

   Add explicit guidance in the agent’s Instructions, for example:

   Memory guidelines:
   - Remember the user's preferred tone, language, and reporting style.
   - Remember names of people and projects they work with.
   - Do not store sensitive personal data (health, finances) unless asked.
   - When the user explicitly says "remember this", always store it.
   

   Without explicit guidance, an agent’s use of memory tends to be inconsistent.

5. Test it across two conversations

   Open a conversation, share a preference, end the conversation. Open a new one and ask something that should trigger recall. Verify the agent already has the context.

Forgetting

Three mechanisms remove memories:

• Explicit forget: the agent calls memory_forget(memory_id) when the user asks (“forget what I told you about X”).
• User-driven cleanup: administrators can wipe a user’s memories on request, supporting GDPR-style “right to be forgotten” workflows.
• Retention policy: your workspace’s general data retention settings also apply to memories.

The agent never forgets silently: forgetting is always triggered by an action, not by passive decay.

Privacy and security

Long-term memory is stored in a dedicated, secured service. Access is scoped to the user the memory belongs to: an agent only sees memories of the user it is currently talking to, and never memories of other users on the platform.

You can review and clean a user’s memories through the platform’s admin tools, and the same retention and privacy policies that apply to conversations also apply to long-term memories.

When long-term memory is the wrong tool

Long-term memory is designed for stable, user-specific information the agent should carry across conversations. It is not the right place for:

Use case	Use instead
Knowledge an agent should have about a domain (product manuals, policies)	A knowledge base / RAG, not memory
Remembering the previous turns of the current conversation	Working memory: enable it on the agent
Carrying a rolling summary from one conversation to the next, automatically	Session memory: enable it on the agent
Logs, audit trails, analytics	The platform’s event system
Large structured data (tables, full documents)	A collection or external database

A useful test: if the same content would apply to every user, it belongs in a knowledge base. If it only makes sense for one user, it belongs in long-term memory.

Next steps

Capabilities

See which capabilities each agent profile includes

Settings

Configure retention, sharing, and memory limits

Instructions

Write effective guidance, including memory rules

Analytics

Inspect tool calls, including memory_remember and memory_recall