Memory & knowledge

Memory — what agents remember

Memory is Exolvra’s built-in note-taking system for agents. During a session, an agent can save a short observation — a fact, a preference, a key outcome — into memory. On the next turn, and the next conversation, and the one after that, memory is searched and the most relevant notes are injected into the agent’s context automatically.

A good mental model: memory is the agent’s private notebook. They decide what goes in, they decide what’s worth remembering, and the platform makes sure the right notes surface at the right time.

Memories look like this:

“User prefers dense markdown reports with section headers, not bullet lists. Confirmed after they asked me to rewrite the last three drafts.”

Or:

“The staging environment runs on port 5079, the production environment runs on 443 behind Cloudflare.”

Or:

“Failed API attempt: calling /api/legacy/users returns 410 Gone. Use /api/v2/users instead.”

Short, specific, actionable later.

The three scopes

Every memory is saved into one of three scopes, which decide who can see it:

System scope — visible to every agent in the instance. Use this for facts that apply to the whole platform: “The company’s legal name is X Corp”, “Invoice numbers always start with INV-”. System memories are rare; most things are narrower.

Project scope — visible only to agents working inside a specific project. Use this for facts that matter within one initiative: “The pricing page launch is targeting end of Q2”, “The blue palette was rejected in the last design review”. Most memories land here because most work is project-scoped.

Agent scope — visible only to one specific agent, but across every project that agent works on. Use this for things an agent learns about itself or its working style: “I get better research results when I web_fetch the top 3 sources in parallel”, “The user likes my summaries to lead with conclusions”. Agent-scoped memories follow the agent everywhere.

When retrieval happens, all three scopes are searched. Project memories get a slight relevance boost over agent memories, which get a slight boost over system memories. The best-ranking matches are injected into the agent’s context for that turn.

How retrieval actually works

On every turn of a conversation, Exolvra runs a semantic search across the memory store using the current message as the query. The top results are inserted into the agent’s system prompt under a section labelled ## Relevant Memories. The agent reads them alongside the user’s message and uses them to shape its response.

This is why memory is lightweight: you’re not loading a database on every call, you’re injecting a handful of the most relevant notes. Memories that don’t match the current topic stay out of the way.

Memory search is hybrid — it combines keyword matching (for exact terms) with semantic matching (for conceptual similarity). That means both “migration failure in the payment module” and “checkout bug after the billing update” can surface the same memory.

Document collections — a different thing

Document collections are not memory. They’re a separate system, used for a different job.

A document collection is a set of files — markdown, text, PDFs — that you upload into Exolvra and attach to a chatbot. When a user talks to the chatbot, Exolvra retrieves the most relevant chunks of the uploaded content and injects them into the bot’s context as grounding. This is Retrieval-Augmented Generation (RAG) in the traditional sense.

You use document collections for:

• A support bot that answers questions from your product’s help articles
• An FAQ bot grounded in your public documentation
• An onboarding bot that knows your company’s policies
• Any chatbot that needs to cite specific written content you control

The key difference from memory: you curate documents, agents curate memory. You upload documents as a human administrator. You don’t write memories — agents save their own memories as they work.

Memory vs documents, side by side

If you want a chatbot that answers questions from your product docs, that’s documents. If you want an agent that remembers facts about what it did last week, that’s memory. Some chatbots use both.

Curating memory

Memories aren’t set-and-forget. Over time they can drift, contradict each other, or go stale. The Memory Browser (/memory) is where you curate them: search across scopes, filter by agent, and edit or delete bad entries.

Good hygiene looks like:

• Periodically review agent-scope memories for things that are no longer true
• Promote commonly-shared memories from agent scope to project scope
• Delete duplicates — agents sometimes save the same fact multiple times in slightly different phrasing
• Trust but verify — the agent saves what it believes; if it saves something wrong, fix it

You can also disable memory for an agent entirely if you want pure stateless behaviour.

Common pitfalls

Expecting memory to store whole documents. Memories are short notes, not files. If an agent tries to save a 5,000-word document into memory, the system will reject or truncate it. Use the data store or the file store for long-form content.

Expecting document collections to be conversational state. Documents are read-only grounding, not a chat history. The chatbot doesn’t remember what a user said three messages ago from the document collection — that’s what the session transcript is for.

Treating memory as a database. Memory is for fuzzy, natural-language observations. If you want structured data (records with fields), use the data store.

Where to go next

• Memory browser — search, curate, and edit memories
• Documents — create collections and upload files for chatbots
• Bots — create chatbots with attached knowledge collections
• Agents & chatbots — how agents use memory during work