Skip to main content

Use with agents

Agents deployed on the Agent Engine get long-term memory powered by the same vector-search engine as VectorDB. This page explains how that memory bank works, how it relates to the VectorDB indexes you create yourself, and which one to use for what.

Two different things, one engine​

It's worth being precise, because the distinction saves confusion later:

  • VectorDB indexes are resources you create and manage. You bring your own vectors, choose dimensions and distance, and query them however you like. Internally they get collection names like p_<project-short>_<index-name>.
  • The agent memory bank is storage the platform creates and manages for each deployed agent. You never write vectors into it directly — the platform embeds conversation text for you. Internally each agent gets a collection named mem_<project-short>_<agent-name> (agents deployed before project scoping use the older mem_<agent-name> form).

Memory-bank collections do not appear in your VectorDB index list, and you don't pay attention to their internals in normal use. But because both run on the same engine, everything you learned about vectors and similarity search applies to how agent memory behaves.

How memories get written: memorize​

An agent's conversation history lives in a session. Sessions are short-term memory — they end. Memorize is the step that turns a session into long-term memory:

  1. The platform flattens the session's turns into a text blob (user: ... / assistant: ... lines).
  2. It embeds that text using the platform's embedding model — you don't generate vectors yourself here.
  3. It upserts the result into the agent's mem_ collection, with the original text and the session id stored as the payload.

You trigger it explicitly, either per session:

platformctl memorize research-buddy --session S1

You should see:

memorized session S1 for research-buddy

Or inline at invoke time with the --memorize flag, which memorizes the exchange immediately:

platformctl invoke research-buddy "My boat is a Mastercraft Maristar 245." --session S1 --memorize

Nothing is memorized automatically. If you never call memorize, the agent's long-term memory stays empty — sessions alone don't leak into it.

How memories get read: search_memory​

Agents built with the platform's toolset get a search_memory(query) tool. When the agent calls it:

  1. The query is embedded with the same embedding model used at memorize time.
  2. The memory bank returns the closest stored snippets (top 5), joined together as the tool's text result.
  3. If nothing relevant is stored, the tool returns the literal string No relevant memories found.

Because this is vector search, recall works by meaning: a session memorized as "My boat is a Mastercraft Maristar 245" is found by a later question like "what do you know about my boat?" even in a brand-new session — no shared words with "Mastercraft" required, no session continuity required.

The end-to-end flow looks like this:

# Session 1: tell the agent something, then memorize it
platformctl invoke research-buddy "My boat is a Mastercraft Maristar 245." --session S1
platformctl memorize research-buddy --session S1

# Session 2 (fresh session): the agent recalls it via search_memory
platformctl invoke research-buddy "What do you know about my boat?" --session S2

The second response draws on the memorized snippet — watch for a search_memory entry in the response's tool calls. The research agent tutorial walks this exact scenario step by step.

Memory bank vs. your own VectorDB index​

You want to...Use
Have an agent remember what users told it across sessionsMemory bank (memorize + search_memory) — zero setup
Ground an agent or app in your documents (RAG)Your own VectorDB index — you control chunking, embeddings, payloads, filters
Filter search by metadata (tags, dates, sources)Your own VectorDB index — the memory bank has no filter interface
Choose the embedding model, dimensions, or distance metricYour own VectorDB index — the memory bank's embedding setup is platform-managed
Inspect, edit, or bulk-delete stored entries in a console UIYour own VectorDB index — it has a data browser and query panel

The two compose well: a research agent typically uses the memory bank for "what has this user told me" and a VectorDB index for "what do my documents say". The RAG chatbot tutorial builds the second half.

Alpha honesty

The memory bank has no management surface of its own yet — no listing, browsing, or selective deletion of memories through the console or CLI. What you can do today is write (memorize) and read (search_memory). If you need managed, inspectable semantic storage now, use a VectorDB index directly.

Next steps​