Memory

Chorus provides a durable memory system that lets agents store, search, and relate knowledge. Memories are namespaced, access-controlled, and support semantic search through embeddings.

Memory Types

Each memory has a type that categorizes it:

Type	Purpose	Example
semantic	Facts and knowledge	"The API uses JWT authentication"
episodic	Events and timeline	"Deployed v2.3 on March 15"
procedural	Workflows and how-to	"To deploy: run docker compose up"
emotional	Preferences and context	"User prefers concise responses"
reflective	Insights and patterns	"Deployments go smoother on Tuesdays"

Storing Memories

curl -X POST http://localhost:3000/memory/store \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "agent:my-agent",
    "content": "The production database is on SurrealDB v3.0",
    "type": "semantic",
    "entity": "infrastructure",
    "category": "database",
    "tags": ["surrealdb", "production"]
  }'

Namespaces

Memories are organized into namespaces that control visibility:

• agent:{id} -- Private to a specific agent
• ring:{name} -- Shared within a ring (visible to all ring members)

Access control enforces that agents can only read memories in namespaces they have access to.

Semantic Search

Query memories by meaning, not just keywords:

curl -X POST http://localhost:3000/memory/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "agent:my-agent",
    "query": "database configuration",
    "limit": 5
  }'

When an embedding provider is configured (via EMBEDDING_PROVIDER environment variable), memories are automatically embedded on storage. Queries use cosine similarity to find semantically related memories.

Recall by Entity

Retrieve all memories about a specific entity:

curl http://localhost:3000/memory/recall/infrastructure \
  -H "Authorization: Bearer YOUR_API_KEY"

Knowledge Graph

Memories can be connected with typed edges to form a knowledge graph:

# Create a relationship between two memories
curl -X POST http://localhost:3000/memory/relate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_id": "memory:abc123",
    "to_id": "memory:def456",
    "relation_type": "depends_on",
    "weight": 0.9
  }'

# Traverse the graph from a memory
curl http://localhost:3000/memory/graph/memory:abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Decay

Memories decay over time based on their decay_rate. The garbage collector (running at MEMORY_GC_INTERVAL_MINUTES) removes memories that have decayed below threshold. Set decay_rate: 0 for memories that should never expire.

Quotas

Administrators can set per-namespace memory quotas to control storage usage:

# Via JSON-RPC
curl -X POST http://localhost:3000/rpc \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "memory/admin/set_quota",
    "params": {"namespace": "agent:my-agent", "max_memories": 10000},
    "id": 1
  }'

Import and Export

Bulk import and export memories for backup or migration:

• Export: POST /rpc with method memory/admin/export
• Import: POST /rpc with method memory/admin/import