Memory API Reference

Complete REST API reference for agent memory management, semantic recall, and collections.

Base URL

base-url

https://api.stack0.dev/v1

Authentication

All API requests require authentication using your API key:

authentication

curl -X POST https://api.stack0.dev/v1/memory/memories \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode"}'

Agents

POST/memory/agents

Create a new agent identity for memory scoping.

Request Body

Field	Type	Description
name	string	Agent name (required)
description	string	Agent description
instructions	string	System instructions for memory handling
metadata	object	Custom metadata

create-agent

curl -X POST https://api.stack0.dev/v1/memory/agents \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Customer support assistant",
    "instructions": "Remember customer preferences and past issues"
  }'
 
# Response
{
  "id": "agent_abc123",
  "name": "Support Agent",
  "description": "Customer support assistant",
  "createdAt": "2025-01-15T10:30:00Z"
}

GET/memory/agents

List all agents.

list-agents

curl "https://api.stack0.dev/v1/memory/agents?limit=20" \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "items": [
    { "id": "agent_abc123", "name": "Support Agent", "createdAt": "..." }
  ],
  "total": 1,
  "hasMore": false
}

GET/memory/agents/:agentId

Get a single agent by ID.

get-agent

curl https://api.stack0.dev/v1/memory/agents/agent_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "agent_abc123",
  "name": "Support Agent",
  "description": "Customer support assistant",
  "instructions": "Remember customer preferences and past issues",
  "metadata": {},
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

PATCH/memory/agents/:agentId

Update an agent.

update-agent

curl -X PATCH https://api.stack0.dev/v1/memory/agents/agent_abc123 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Agent Name" }'
 
# Response
{ "id": "agent_abc123", "name": "Updated Agent Name", ... }

DELETE/memory/agents/:agentId

Delete an agent and all associated memories.

delete-agent

curl -X DELETE https://api.stack0.dev/v1/memory/agents/agent_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "success": true }

Memories

POST/memory/memories

Store a new memory. Embeddings are generated automatically for semantic search.

Request Body

Field	Type	Description
content	string	Memory content (required)
agentId	string	Agent that owns this memory
collectionId	string	Collection to assign to
type	string	episodic, semantic, procedural, or identity
confidence	number	Confidence score 0-1 (default 1.0)
metadata	object	Custom metadata for filtering
tags	string[]	Tags for categorization

store-memory

curl -X POST https://api.stack0.dev/v1/memory/memories \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode and compact layout",
    "agentId": "agent_abc123",
    "type": "semantic",
    "confidence": 0.95,
    "tags": ["preferences", "ui"],
    "metadata": { "userId": "user_123" }
  }'
 
# Response
{
  "id": "mem_xyz789",
  "content": "User prefers dark mode and compact layout",
  "type": "semantic",
  "tier": "hot",
  "confidence": 0.95,
  "createdAt": "2025-01-15T10:30:00Z"
}

POST/memory/memories/batch

Store multiple memories in a single request (up to 100).

batch-store

curl -X POST https://api.stack0.dev/v1/memory/memories/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      { "content": "User likes Python", "type": "semantic" },
      { "content": "Discussed pricing on Jan 15", "type": "episodic" }
    ],
    "agentId": "agent_abc123"
  }'
 
# Response
{
  "created": 2,
  "memories": [
    { "id": "mem_001", "content": "User likes Python", ... },
    { "id": "mem_002", "content": "Discussed pricing on Jan 15", ... }
  ]
}

POST/memory/memories/recall

Semantic recall using vector similarity search. Returns the most relevant memories for a query.

Request Body

Field	Type	Description
query	string	Natural language query (required)
agentId	string	Filter by agent
collectionId	string	Filter by collection
type	string	Filter by memory type
limit	number	Max results (default 10)
threshold	number	Minimum similarity score 0-1
metadata	object	Filter by metadata fields

recall-memories

curl -X POST https://api.stack0.dev/v1/memory/memories/recall \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user\'s UI preferences?",
    "agentId": "agent_abc123",
    "limit": 5,
    "threshold": 0.7
  }'
 
# Response
{
  "memories": [
    {
      "id": "mem_xyz789",
      "content": "User prefers dark mode and compact layout",
      "type": "semantic",
      "confidence": 0.95,
      "similarity": 0.92,
      "metadata": { "userId": "user_123" },
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

GET/memory/memories/search

Keyword search across memory content and tags.

search-memories

curl "https://api.stack0.dev/v1/memory/memories/search?q=dark+mode&agentId=agent_abc123" \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "memories": [
    { "id": "mem_xyz789", "content": "User prefers dark mode and compact layout", ... }
  ],
  "total": 1
}

GET/memory/memories

List memories with optional filters.

Query Parameters

Parameter	Type	Description
agentId	string	Filter by agent
collectionId	string	Filter by collection
type	string	Filter by type
tier	string	hot, warm, cold, or archived
limit	number	Max results (default 20)
offset	number	Pagination offset

list-memories

curl "https://api.stack0.dev/v1/memory/memories?agentId=agent_abc123&type=semantic&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "items": [...],
  "total": 42,
  "hasMore": true
}

GET/memory/memories/:memoryId

Get a single memory by ID.

get-memory

curl https://api.stack0.dev/v1/memory/memories/mem_xyz789 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "mem_xyz789",
  "content": "User prefers dark mode and compact layout",
  "type": "semantic",
  "tier": "hot",
  "confidence": 0.95,
  "accessCount": 5,
  "tags": ["preferences", "ui"],
  "metadata": { "userId": "user_123" },
  "agentId": "agent_abc123",
  "createdAt": "2025-01-15T10:30:00Z",
  "lastAccessedAt": "2025-01-20T14:00:00Z"
}

PATCH/memory/memories/:memoryId

Update a memory. Changing content regenerates the embedding.

update-memory

curl -X PATCH https://api.stack0.dev/v1/memory/memories/mem_xyz789 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode, compact layout, and large fonts",
    "confidence": 0.98
  }'
 
# Response
{ "id": "mem_xyz789", "content": "User prefers dark mode, compact layout, and large fonts", ... }

DELETE/memory/memories/:memoryId

Delete a single memory.

delete-memory

curl -X DELETE https://api.stack0.dev/v1/memory/memories/mem_xyz789 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "success": true }

POST/memory/memories/delete-many

Delete multiple memories by ID.

delete-many-memories

curl -X POST https://api.stack0.dev/v1/memory/memories/delete-many \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "memoryIds": ["mem_001", "mem_002", "mem_003"] }'
 
# Response
{ "deletedCount": 3 }

Collections

POST/memory/collections

Create a collection to group related memories.

create-collection

curl -X POST https://api.stack0.dev/v1/memory/collections \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Preferences",
    "description": "UI and behavior preferences",
    "compactionEnabled": true,
    "compactionConfig": {
      "strategy": "summarize",
      "threshold": 100
    }
  }'
 
# Response
{
  "id": "col_abc123",
  "name": "User Preferences",
  "compactionEnabled": true,
  "createdAt": "2025-01-15T10:30:00Z"
}

GET/memory/collections

List all collections.

list-collections

curl "https://api.stack0.dev/v1/memory/collections?limit=20" \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "items": [
    { "id": "col_abc123", "name": "User Preferences", "memoryCount": 42, ... }
  ],
  "total": 1,
  "hasMore": false
}

GET/memory/collections/:collectionId

Get a single collection by ID.

get-collection

curl https://api.stack0.dev/v1/memory/collections/col_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "col_abc123",
  "name": "User Preferences",
  "description": "UI and behavior preferences",
  "compactionEnabled": true,
  "compactionConfig": { "strategy": "summarize", "threshold": 100 },
  "memoryCount": 42,
  "createdAt": "2025-01-15T10:30:00Z"
}

PATCH/memory/collections/:collectionId

Update a collection.

update-collection

curl -X PATCH https://api.stack0.dev/v1/memory/collections/col_abc123 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "All Preferences", "compactionEnabled": false }'
 
# Response
{ "id": "col_abc123", "name": "All Preferences", ... }

DELETE/memory/collections/:collectionId

Delete a collection. Memories can be optionally deleted or reassigned.

delete-collection

curl -X DELETE https://api.stack0.dev/v1/memory/collections/col_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{ "success": true }

GET/memory/collections/:collectionId/stats

Get statistics for a collection including memory counts by tier and type.

collection-stats

curl https://api.stack0.dev/v1/memory/collections/col_abc123/stats \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "totalMemories": 42,
  "byTier": { "hot": 20, "warm": 15, "cold": 5, "archived": 2 },
  "byType": { "semantic": 25, "episodic": 10, "procedural": 5, "identity": 2 },
  "storageBytes": 102400,
  "lastCompactionAt": "2025-01-14T00:00:00Z"
}

POST/memory/collections/:collectionId/compact

Trigger memory compaction for a collection. Summarizes and deduplicates memories.

trigger-compaction

curl -X POST https://api.stack0.dev/v1/memory/collections/col_abc123/compact \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "jobId": "cjob_abc123",
  "status": "pending",
  "collectionId": "col_abc123"
}

GET/memory/compaction-jobs/:jobId

Get the status of a compaction job.

get-compaction-job

curl https://api.stack0.dev/v1/memory/compaction-jobs/cjob_abc123 \
  -H "Authorization: Bearer sk_live_xxx"
 
# Response
{
  "id": "cjob_abc123",
  "status": "completed",
  "collectionId": "col_abc123",
  "memoriesProcessed": 42,
  "memoriesCreated": 8,
  "memoriesArchived": 15,
  "startedAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:31:00Z"
}

Memory Types

Type	Description
episodic	Event-based memories (conversations, interactions)
semantic	Facts and knowledge (preferences, attributes)
procedural	How-to instructions and processes
identity	Core identity and personality traits

Memory Tiers

Tier	Description
hot	Frequently accessed, highest priority in recall
warm	Occasionally accessed, included in broad queries
cold	Rarely accessed, available on explicit request
archived	Compacted or superseded, retained for history

Compaction Job Status

Status	Description
pending	Job queued, waiting to start
processing	Compacting and summarizing memories
completed	Compaction finished successfully
failed	Compaction encountered an error

API Overview Error Handling

Memory API Reference

Base URL

Authentication

Agents

Request Body

Memories

Request Body

Request Body

Query Parameters

Collections

Memory Types

Memory Tiers

Compaction Job Status

Related