Memory
Long-term context stored in Postgres and recalled per query, scoped to org, project, agent, or session.
Memory is how agents carry context across sessions. Every memory is a row in the memories table, scoped to an org and a user, with optional links to a project, agent, or session.
What gets stored
| Field | Purpose |
|---|---|
key | Short label used to look up or dedupe a memory. |
value | The actual content (up to a fixed character limit). |
summary | Optional shorter form for prompt injection. |
category | Free-form bucket — defaults to fact. |
tags | String tags for filtering. |
importance | Integer 1–10; higher items surface first. |
pinned | Always-on items, ranked above unpinned. |
expiresAt | Optional TTL; expired rows are filtered out. |
source | Where the memory came from (manual, auto, …). |
Each memory may also carry assets (binary attachments stored separately) and sources (links back to the message or session that produced it).
Scopes
A memory has one of three scopes that define who can see it:
| Scope | Visible to |
|---|---|
global | The user, anywhere in the org. |
project | Anyone in the project, plus that project's sessions. |
agent | Sessions belonging to that agent. |
When workspaces are enabled on an org, memories are additionally constrained by the active workspace — the runtime adds a workspace condition to every read.
How recall works
Recall happens per query. The runtime tokenizes the query, runs a Postgres full-text search across key, summary, value, category, and tags, and falls back to ILIKE for partial matches. Results are ranked by ts_rank_cd, then by pinned, importance, and updatedAt. The default cap is 5 results, max 50.
The pgvector column lives alongside this row for semantic recall on top of the lexical index.
Manual save vs auto
| Source | How it's written |
|---|---|
manual | The user (or an agent on the user's behalf) calls the save endpoint. |
auto | The runtime extracts a fact from a session and saves it. |
| Other | Tools may write with their own source label (capped length). |
Saves dedupe by default: if a memory with the same key, scope, and context already exists, it's updated in place rather than duplicated. Pass dedupe: "create" to force a new row.
See /docs/concepts/learning-mode for a related but separate store of user insights.