Memory API

Memory and embedding endpoints for persistent vector storage. The backend uses PostgreSQL with pgvector for similarity search and ETS for fast key-value access.

Overview

The memory system provides two storage modes:

Mode	Backend	Use Case
Key-value	ETS + WAL	Fast TTL-based caching, reflections
Vector search	PostgreSQL + pgvector	Semantic similarity search

Memory entries are scoped to agent_id and user_uuid. Users can only access their own entries unless they are admin.

Store a Memory Entry

POST /api/v1/memory/:agent_id/store

Store a key-value pair with optional embedding and TTL.

Request

{
  "key": "lesson_learned_42",
  "value": "Always validate input before processing in Erlang",
  "ttl": 86400000,
  "embedding": [0.1, 0.2, 0.3, 0.4]
}

Field	Required	Description
key	Yes	Unique key within the agent's namespace
value	Yes	String value to store
ttl	No	Time-to-live in milliseconds (0 = no expiry)
embedding	No	Pre-computed embedding vector. Auto-generated if omitted

Response

{
  "status": "ok"
}

If no embedding is provided, the system auto-generates one from the value using the configured embedding model. Embedding generation is best-effort and does not fail the store operation.

Retrieve a Memory Entry

GET /api/v1/memory/:agent_id/:key

Retrieve a stored memory entry by key.

Response

{
  "key": "lesson_learned_42",
  "value": "Always validate input before processing in Erlang",
  "created_at": 1716192000000
}

Error Responses

Code	Description
404	Key not found
410	Entry has expired
503	Memory service disabled

Delete a Memory Entry

DELETE /api/v1/memory/:agent_id/:key

Delete a specific memory entry. Only the owner can delete entries.

Response

{
  "status": "ok"
}

Search Memory

GET /api/v1/memory/:agent_id/search?q=<query>&limit=20

Full-text search across memory entries for an agent.

Parameters

Parameter	Default	Description
q	(required)	Search query string
limit	20	Maximum results to return

Response

{
  "results": [
    {
      "key": "lesson_learned_42",
      "value": "Always validate input before processing in Erlang",
      "created_at": 1716192000000
    }
  ]
}

Vector Search

POST /api/v1/memory/:agent_id/vector-search

Semantic similarity search using pgvector. Requires pgvector to be enabled.

Request (by text)

{
  "text": "input validation best practices",
  "limit": 10,
  "threshold": 0.75
}

Request (by embedding)

{
  "embedding": [0.1, 0.2, 0.3, 0.4],
  "limit": 10,
  "threshold": 0.75
}

Field	Required	Description
text	One of text/embedding	Query text (auto-embedded)
embedding	One of text/embedding	Pre-computed embedding vector
limit	No	Maximum results (default: 20)
threshold	No	Minimum similarity score 0-1 (default: 0.75)

Response

{
  "results": [
    {
      "key": "lesson_learned_42",
      "value": "Always validate input before processing in Erlang",
      "similarity": 0.92
    }
  ]
}

List Memory Entries

GET /api/v1/memory/:agent_id/list?limit=50&offset=0

Paginated list of all memory entries for an agent.

Parameters

Parameter	Default	Description
limit	50	Maximum entries per page
offset	0	Pagination offset

Response

{
  "entries": [
    {
      "key": "lesson_learned_42",
      "value": "Always validate input before processing in Erlang",
      "created_at": 1716192000000
    }
  ]
}

Clear All Memory

DELETE /api/v1/memory/:agent_id/clear

Delete all memory entries for an agent. Only the owner can clear memory.

Response

{
  "status": "ok"
}

Pin a Memory Entry

POST /api/v1/memory/:agent_id/:key/pin

Pin or unpin a memory entry. Pinned entries are exempt from importance decay.

Request

{
  "pinned": true
}

Response

{
  "status": "ok",
  "pinned": true
}

Get Reflections

GET /api/v1/memory/:agent_id/reflections

Retrieve all memory entries with keys matching reflection:*. Filtered by user ownership.

Response

{
  "reflections": [
    {
      "key": "reflection:session_42",
      "value": "The user prefers concise explanations"
    }
  ]
}

Memory Statistics

GET /api/v1/memory/stats

Admin-only. Returns memory usage statistics.

Response

{
  "total_entries": 1500,
  "total_agents": 12,
  "pg_enabled": true,
  "pgvector_enabled": true
}

Trigger Importance Decay

POST /api/v1/memory/decay

Admin-only. Manually trigger the importance decay process that reduces relevance of old, unpinned entries.

Response

{
  "status": "ok",
  "forgotten": 23
}

Share Memory

POST /api/v1/memory/share

Admin-only. Copy memory entries matching a pattern from one agent to another.

Request

{
  "from": "agent-a",
  "to": "agent-b",
  "pattern": "lesson_*"
}

Response

{
  "status": "ok",
  "copied": 15
}

Agent ID

The agent_id path parameter identifies the memory namespace. Default is "default". Maximum length is 128 characters.

User Scoping

Memory entries are tagged with user_uuid at store time. The following rules apply:

• Non-admin users see only their own entries
• Admin users see all entries
• System entries (no user_uuid) are visible to all
• Ownership is checked on retrieve, delete, and pin operations