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).

Memory nodes

Structured recall graphs live in memory nodes (GET /api/v1/memory-nodes). Row memories and node items share org scope but serve different agent tools — see Memories API. Deleting memories requires a browser session; API keys receive 403.

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.

Deleting memories

DELETE /api/v1/memories/:id and bulk DELETE /api/v1/memories require a browser session with fresh step-up. API keys are rejected with 403 even for org owners.

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.