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 last week?”	One user × one agent, across all their conversations	Fast in-memory session store	Automatic: at the end of each completed conversation, the platform asks an LLM to merge the new exchange into a rolling summary, which is reloaded into the next conversation’s prompt
Long-term memory	”Can my agent save a specific preference I tell it to remember and recall it later by semantic search?”	One user × one agent (or shared user-wide)	Dedicated memory service (vector search)	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.

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 at the end of a conversation, so enabling it doesn’t add latency to user-facing responses. The summary becomes available the next time the user opens a conversation with the same agent.

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 agent runs a similarity search against the user’s stored memories using the new message as the query and injects the top relevant ones 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.

Semantic recall via vector embeddings

Memories are not stored as plain text alone. Each memory is also embedded as a vector. When the agent calls memory_recall("what are my dietary restrictions?"), the service:

1. Embeds the query into the same vector space.
2. Returns the top‑K most similar stored memories, ranked by semantic distance.
3. The agent reads them and answers.

This is why the user can ask the question in any wording (“what can’t I eat?”, “any food I avoid?”) and still get the right memories back.

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. They are also optionally scoped per agent:

• User-only memory: visible to that user across all agents they interact with on the platform. Useful for general user preferences (“I prefer concise answers”).
• User + agent memory: visible only to one agent for that user. Useful for agent-specific context (“For this support agent, always start by checking ticket history”).

Two different users never see each other’s memories. Two different agents within the same user account see each other’s memories only if those memories were saved as user-only.

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. Enable it in Settings

   Go to Settings → Memory and turn on Long-term memory.

3. Set the recall budget

   Choose 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