Long-term memory

Sessions give an agent short-term memory: history within one conversation. The memory bank gives it long-term memory: facts that survive across sessions, forever, until you delete the agent. This page shows how to write to the bank and how the agent reads from it.

How it works

1. You memorize a session. The platform extracts the session's text, turns it into vectors (an embedding — a list of numbers that captures meaning) using the platform's embedding model, and stores those vectors in a managed VectorDB collection that belongs to this agent (named mem_<project-short>_<agent>).
2. In any later session, the agent's built-in search_memory tool embeds the question the same way and returns the top 5 most similar stored snippets, which the agent uses to answer.

Nothing is written automatically — memorize is an explicit step, on purpose. You decide which conversations become durable knowledge.

Memory is shared across all callers

The memory bank has no per-caller partition. Anything memorized is retrievable by every future caller of that agent. That is exactly why writing to it always requires authentication, even when invoking does not.

Write to the memory bank

Two ways, both requiring a signed-in caller:

1. The memorize endpoint — commit an existing session:

POST /v1/agents/{name}/sessions/{id}/memorize

curl -s -X POST \
  "$CAI_API/v1/agents/research-buddy/sessions/3f2c8a1e-9d41-4c1b-a2f7-0b1c2d3e4f5a/memorize" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"status": "ok"}

A missing session returns 404 session <id> not found. An unauthenticated call returns 401:

writing to the memory bank requires authentication, even though invoking this agent does not: stored memories are read back into later callers' context. Sign in (POST /v1/auth/login) and send 'Authorization: Bearer <token>'

2. The memorize flag on invoke — memorize as you go, in one call:

{"session_id": "…", "message": "…", "memorize": true}

Anonymous callers get 401 with a message pointing at the endpoint above. See invoke.

With the CLI:

platformctl memorize research-buddy --session 3f2c8a1e-9d41-4c1b-a2f7-0b1c2d3e4f5a

The --session flag is required — leaving it off fails with --session is required.

Read from the memory bank

Reading happens inside the agent, through the built-in search_memory tool. Give your agent the tool and tell it when to use it. For an ADK agent:

from google.adk.agents import Agent
from crusoe_adk.foundry import foundry_model
from crusoe_adk.tools import run_python, search_memory

root_agent = Agent(
    name="research_buddy",
    model=foundry_model(),
    instruction="Use search_memory to recall facts you were taught earlier.",
    tools=[run_python, search_memory],
)

When the agent calls it, search_memory(query) returns the top 5 matching snippets from this agent's own collection. The call shows up in the invoke response's tool_calls list. See built-in tools for LangGraph and CrewAI equivalents.

End-to-end example: teach in session 1, recall in session 2

# 0) Sign in once — memorize needs it
platformctl login --email you@example.com

# 1) Session 1: tell the agent a fact
platformctl invoke research-buddy "My boat is a Mastercraft Maristar 245."

You should see:

Got it - a Mastercraft Maristar 245.
(session: 3f2c8a1e-9d41-4c1b-a2f7-0b1c2d3e4f5a)

# 2) Commit that session to the memory bank
platformctl memorize research-buddy --session 3f2c8a1e-9d41-4c1b-a2f7-0b1c2d3e4f5a

# 3) Session 2: a brand-new conversation — no --session flag, fresh history
platformctl invoke research-buddy "What do you know about my boat?"

You should see:

You have a Mastercraft Maristar 245.
(session: 91b0f4d7-2a6c-4e8f-b3d1-5c7e9a0f2b4d)
tool_call: search_memory called with args={'query': 'boat'}

The new session started blank, but the search_memory tool call pulled the fact back out of the memory bank.

What's behind it

• Storage: a managed VectorDB (Qdrant) collection per agent, named mem_<project-short>_<agent>. The platform creates and manages it — you don't need to create an index yourself.
• Embeddings: generated with the platform's configured embedding model (the EMBED_MODEL injected into every agent). Memorized text and search queries go through the same model, so similarity search is apples-to-apples.
• Want to build your own retrieval instead of (or alongside) the built-in bank? See use VectorDB with agents.

Quick reference

Action	How	Auth
Write memory	POST /v1/agents/{name}/sessions/{id}/memorize, or "memorize": true on invoke, or platformctl memorize <agent> --session <id>	Always required
Read memory	The agent's search_memory tool during invoke	Same as invoke (open by default)
Scope	Per agent, shared by all its callers	—
Results returned	Top 5 snippets per search	—