Memory

Memory is durable Agent-owned text in the Agent extension model that persists across Sessions. Use it for recall that can change over time; Session messages remain one conversation's transcript, while Skill content is reusable instruction material.

Ownership and visibility

Every Memory belongs to exactly one tenant's Agent. userId: "" creates an Agent-general row; a non-empty userId creates an end-user partition. During a Turn, the Agent can see its general rows plus rows matching that Turn's userId; a Turn without userId sees only general rows.

The tenant API key can administer every Memory owned by the tenant and Agent, and list filtering by userId is an exact match. Attribution is a data and filtering dimension, not an ACL or end-user authentication mechanism.

Save and search Memory

This example creates an end-user Memory, then searches that exact partition for a distinctive term.

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });
const agent = await client.agents.create({ name: "Support Agent" });
const created = await client.memories.create(agent.id, {
  userId: "customer-42",
  text: "Prefers heliotrope accents in generated reports.",
});
const page = await client.memories.list(agent.id, {
  userId: "customer-42",
  search: "heliotrope",
});
const match = page.data.find(({ id }) => id === created.memory.id);
console.log(match?.id, match?.text);

The search result contains the newly created Memory ID and text. Search uses PostgreSQL full-text web-search behavior with the simple configuration, so it is lexical rather than semantic search.

Agent Memory Tools

Enabling the memory Tool group exposes save_memory, get_memory, search_memories, update_memory, and delete_memory. These Tools are scoped to the current Agent and the Turn's visible general/end-user rows. save_memory stamps the Turn's userId.

Tool get_memory and search_memories touch returned rows' lastAccessedAt on a best-effort basis; Tool updates also advance it. Tenant-facing administrative get/list calls do not touch access time.

Automatic injection

memoryInjectionEnabled defaults to false. When enabled on the resolved Agent Version, each Turn selects the Agent-general rows plus its current userId partition, ordered newest first, and injects up to 4,000 words as context. The last included Memory can be truncated to fit, and included rows are touched best effort.

Injection is independent of the memory Tool group: enable injection for automatic context, the group for explicit CRUD/search actions, or both.

Retention and lifecycle

The enforced pool is 500 rows per Agent across all userId partitions, not 500 per end-user. Creation locks that Agent's pool, transactionally evicts the least-recently-accessed rows by lastAccessedAt, then creation time and ID, and inserts the new row. Concurrent creates therefore stay within the same Agent-wide cap, and a failed insert rolls back its eviction.

Memory has no time-based retention. Text can be replaced and rows can be deleted explicitly; userId is immutable. Rows persist across Sessions and are cascade-deleted with their Agent.

Production considerations

Store only content appropriate for durable recall. Memory can contain end-user data and is included in prompts when injection is enabled.
Follow the tenancy and Attribution model. Stamp the same opaque userId on Memory and Turns that should share an end-user partition; do not treat it as authorization.
Design search terms for lexical full-text matching and handle an empty result.
Plan for Agent-wide eviction across every partition and the documented platform limits. Frequently accessed rows survive longer, but no individual end-user has a reserved share.
Concurrent creation is serialized per Agent for cap enforcement; do not build workflows that depend on a specific eviction victim surviving another create.

Reference

TypeScript SDK: Memories and Agent configuration
REST API: Memories and Agent configuration

On this page