Memories

client.memories exposes nine operations for managing memories. All methods return typed promises and throw typed errors on failure.

---

create

Stores a new memory in the workspace. Processing is asynchronous — the memory is available for search once its status reaches READY.

Signature

client.memories.create(params: CreateMemoryInput): Promise<Memory>

Parameter	Type	Required	Description
content	string	Yes	The memory content — write as a clear, self-contained statement
userId	string	No	ID of the user this memory belongs to
agentId	string	No	ID of the agent this memory belongs to
sessionId	string	No	ID of the conversation session
metadata	Record<string, unknown>	No	Arbitrary key-value metadata
categories	string[]	No	Category tags for filtering and organization
priority	MemoryPriority	No	LOW, MEDIUM (default), or HIGH
layer	MemoryLayer	No	TASK (temporary, with TTL) or RAW (permanent, default)

Example

const memory = await client.memories.create({
  content: 'The user is building a SaaS product using Next.js and Supabase.',
  userId: 'user_123',
  priority: 'HIGH',
  categories: ['project', 'tech-stack'],
  metadata: { source: 'onboarding-form' },
});

console.log(memory.id);      // "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
console.log(memory.status);  // "PENDING"
console.log(memory.layer);   // "RAW"

---

search

Searches memories using semantic similarity, keyword matching, or a hybrid of both. Returns memories ranked by relevance with a score field.

Signature

client.memories.search(params: SearchMemoriesInput): Promise<SearchResult>

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
userId	string	No	Filter results to a specific user
limit	number	No	Maximum number of results to return (default 10)
mode	SearchMode	No	hybrid (default), semantic, or keyword
categories	string[]	No	Filter results to specific categories
priority	MemoryPriority	No	Filter results by priority level

Example

const results = await client.memories.search({
  query: 'what tech stack does the user prefer?',
  userId: 'user_123',
  mode: 'hybrid',
  limit: 5,
  categories: ['tech-stack'],
});

for (const memory of results.data) {
  console.log(memory.content);  // "The user is building a SaaS product..."
  console.log(memory.score);    // 0.91
}

console.log(results.meta.total);  // 1
console.log(results.meta.mode);   // "hybrid"

---

list

Lists memories chronologically with optional filters. Use this when you need to browse all memories rather than search by relevance.

Signature

client.memories.list(params?: ListMemoriesInput): Promise<PaginatedResult<Memory>>

Parameter	Type	Required	Description
userId	string	No	Filter by user ID
agentId	string	No	Filter by agent ID
status	MemoryStatus	No	Filter by status: PENDING, PROCESSING, READY, FAILED
layer	MemoryLayer	No	Filter by layer: TASK or RAW
priority	MemoryPriority	No	Filter by priority: LOW, MEDIUM, or HIGH
categories	string[]	No	Filter by category tags
page	number	No	Page number (default 1)
pageSize	number	No	Results per page (default 20)

Example

const page = await client.memories.list({
  userId: 'user_123',
  layer: 'RAW',
  categories: ['project'],
  page: 1,
  pageSize: 20,
});

console.log(page.data.length);       // up to 20
console.log(page.meta.total);        // 47
console.log(page.meta.totalPages);   // 3

---

get

Retrieves a single memory by its ID.

Signature

client.memories.get(params: { id: string }): Promise<Memory>

Example

const memory = await client.memories.get({
  id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
});

console.log(memory.content);         // "The user is building a SaaS product..."
console.log(memory.status);          // "READY"
console.log(memory.categories);      // ["project", "tech-stack"]
console.log(memory.priority);        // "HIGH"
console.log(memory.createdAt);       // "2026-06-07T10:00:00.000Z"

Throws NotFoundError if the memory does not exist or does not belong to the workspace.

---

update

Updates a memory's content, metadata, categories, or priority. The memory is re-processed after an update.

Signature

client.memories.update(params: UpdateMemoryInput): Promise<Memory>

Parameter	Type	Required	Description
id	string	Yes	ID of the memory to update
content	string	No	New memory content
metadata	Record<string, unknown>	No	New metadata (replaces existing)
categories	string[]	No	New category list (replaces existing)
priority	MemoryPriority	No	New priority level

Example

const updated = await client.memories.update({
  id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
  content: 'The user is building a SaaS product using Next.js, Supabase, and TypeScript.',
  priority: 'HIGH',
  categories: ['project', 'tech-stack', 'typescript'],
});

console.log(updated.content);   // "The user is building a SaaS product..."
console.log(updated.status);    // "PENDING" — re-processing triggered

---

delete

Permanently deletes a memory. This action cannot be undone.

Signature

client.memories.delete(params: { id: string }): Promise<void>

Example

await client.memories.delete({
  id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
});

// Memory is permanently removed. No return value.

---

promote

Promotes a TASK-layer memory (temporary, with expiration) to RAW layer (permanent, no expiration). Use this when a memory that was created as temporary context proves to be persistently relevant.

Signature

client.memories.promote(params: { id: string }): Promise<void>

Example

// A TASK memory was created during onboarding with a short TTL.
// The user confirmed they want it kept permanently.
await client.memories.promote({
  id: 'task-memory-uuid',
});

// The memory is now RAW layer — it will not expire.

---

feedback

Submits a quality signal on a memory. Feedback is used to improve retrieval quality over time.

Signature

client.memories.feedback(params: FeedbackInput): Promise<void>

Parameter	Type	Required	Description
id	string	Yes	ID of the memory
signal	FeedbackSignal	Yes	POSITIVE, NEGATIVE, or NEUTRAL
comment	string	No	Optional explanation for the feedback

Example

// Memory was accurate and useful in this conversation
await client.memories.feedback({
  id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
  signal: 'POSITIVE',
});

// Memory was wrong — user corrected it
await client.memories.feedback({
  id: 'another-memory-uuid',
  signal: 'NEGATIVE',
  comment: 'The user actually prefers Vue.js, not React.',
});

---

history

Returns the event timeline for a memory — creation, updates, promotions, and feedback submissions.

Signature

client.memories.history(params: MemoryHistoryInput): Promise<PaginatedResult<MemoryEvent>>

Parameter	Type	Required	Description
id	string	Yes	ID of the memory
page	number	No	Page number (default 1)
limit	number	No	Events per page (default 20)

Example

const history = await client.memories.history({
  id: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
  limit: 10,
});

for (const event of history.data) {
  console.log(event.type);       // "CREATED" | "UPDATED" | "PROMOTED" | "FEEDBACK_SUBMITTED"
  console.log(event.createdAt);  // "2026-06-07T10:00:00.000Z"
  console.log(event.payload);    // event-specific data
}

---

Related

• Advanced Search — search modes, filters, and feedback loops
• Knowledge — consolidated knowledge profile built from memories
• Type Reference — Memory, SearchResult, PaginatedResult, and all related types