Agent memory reference v7

Reference for agent memory functions, views, and configuration parameters. For guide-style documentation, see Agent memory.

Catalog views

aidb_memory.namespaces

Lists the available agent memory namespaces.

aidb_memory.events

Lists the ingestion events created when applications call aidb_memory.add. Query this view to audit submitted conversation turns, trace asynchronous processing, correlate retries through idempotency keys, and check whether each event was accepted, processed, made ready, or failed.

aidb_memory.messages

Stores the ordered message history generated from memory events, including the actor and session context, role, content, and timestamps.

aidb_memory.sessions

One row per conversation, created lazily by session_start, session_end, or a compacting session_get. The aidb_users role can't read this view directly.

aidb_memory.session_compactions

Summaries that stand in for the turns a session has compacted, ordered per session by seq. Written only by a compacting session_get, one row per compaction.

Functions

aidb_memory.init

Initializes a namespace and prepares it to store and retrieve memories. Run it once before any other aidb_memory function, so that the LLM, embedding configuration, and Agent Memory Server are set up. Call it once during setup or before the first memory operation. If the namespace already exists, the function returns it without changing it.

aidb_memory.init(name TEXT, config JSONB)

Returns a row that describes the namespace:

aidb_memory.add

Persists agent turns as an event so that they can be retrieved later as memory. Typically used to store a user's conversation with an agent.

aidb_memory.add(
  turns JSONB,
  namespace TEXT,
  actor_id TEXT,
  agent_id TEXT DEFAULT NULL,
  session_id TEXT DEFAULT NULL,
  idempotency_key TEXT DEFAULT NULL,
  metadata JSONB DEFAULT '{}'
)

Returns:

aidb_memory.status

Reports the status of a memory event: ACCEPTED, PROCESSING, READY, SKIPPED, or FAILED. Use it to confirm that an event is ready for retrieval, or to diagnose a failed memory formation.

aidb_memory.status(
  namespace TEXT,
  id UUID DEFAULT NULL,
  actor_id TEXT DEFAULT NULL,
  session_id TEXT DEFAULT NULL,
  agent_id TEXT DEFAULT NULL,
  limit INTEGER DEFAULT 100,
  offset INTEGER DEFAULT 0
)

Returns a row for each matching event:

aidb_memory.search

Searches the stored memories and returns the entries that match a natural-language query. Use it to retrieve information that was saved with aidb_memory.add.

aidb_memory.search(
  namespace TEXT,
  actor_id TEXT,
  query TEXT,
  limit INTEGER DEFAULT 10,
  session_id TEXT DEFAULT NULL,
  agent_id TEXT DEFAULT NULL
)

Returns a row for each matching memory:

aidb_memory.list_memories

Lists the memories stored in agent memory. Use it to inspect saved context, audit memories, debug memory behavior, or verify that expected records exist.

aidb_memory.list_memories(
  namespace TEXT,
  actor_id TEXT,
  session_id TEXT DEFAULT NULL,
  agent_id TEXT DEFAULT NULL,
  limit INTEGER DEFAULT 100
)

Returns a row for each memory:

aidb_memory.delete

Removes memories when they must be deleted for compliance, privacy, or retention reasons. Deleted memories no longer appear in searches or listings.

aidb_memory.delete(
  namespace TEXT,
  actor_id TEXT,
  selector JSONB,
  reason TEXT,
  session_id TEXT DEFAULT NULL,
  agent_id TEXT DEFAULT NULL
)

Returns:

aidb_memory.session_start

Opens a conversation, or resumes one, and returns the handoff left by the previous conversation in the same scope. Makes no model call and is idempotent.

aidb_memory.session_start(
  namespace TEXT,
  actor_id TEXT,
  agent_id TEXT,
  session_id TEXT DEFAULT NULL
)

Returns:

aidb_memory.session_get

Returns a conversation's history in order, within an optional character budget. When the budget is exceeded, it summarizes the oldest part of the history. It isn't exposed as an agent tool, because an agent must not choose its own history.

aidb_memory.session_get(
  namespace TEXT,
  actor_id TEXT,
  session_id TEXT,
  limit_chars BIGINT DEFAULT NULL,
  fallback_model TEXT DEFAULT NULL
)

Returns:

aidb_memory.session_end

Closes a conversation and stores a handoff that describes it. Makes no model call and is idempotent: a repeated close returns the stored handoff without overwriting it.

aidb_memory.session_end(
  namespace TEXT,
  actor_id TEXT,
  session_id TEXT,
  notes TEXT DEFAULT NULL
)

Returns:

Configuration parameters

Agent memory exposes Postgres configuration parameters in the aidb.agent_memory_* namespace. For examples, see Configuring advanced settings.

Changes to these parameters don't require a Postgres restart. If you change them in postgresql.conf, reload the configuration for the change to take effect.

Users can set both parameters for their own sessions. You set the Agent Memory Server address in the namespace, using agentmemory_spec.config.base_url, not in a parameter.