List, Get, Delete

Read-side and record-level endpoints for the memory store. This page covers health checks, basic CRUD operations (list, get, delete, expand), and per-user statistics / storage quota.

Base URL: http://localhost:3050

All request bodies are JSON (Content-Type: application/json). Field names on the raw HTTP prototype surface use snake_case.

Health

GET /health

Top-level server liveness check.

Response:

{ "status": "ok" }

GET /v1/memories/health

Memory subsystem health with active runtime config.

Response:

{
  "status": "ok",
  "config": {
    "retrieval_profile": "balanced",
    "embedding_provider": "ollama",
    "embedding_model": "mxbai-embed-large",
    "llm_provider": "ollama",
    "llm_model": "qwen3:8b",
    "clarification_conflict_threshold": 0.8,
    "max_search_results": 12
  }
}

CRUD

GET /v1/memories/list

List memories for a user with pagination.

Query params:

Param	Type	Default	Notes
user_id	string	required	User identifier
limit	number	20	Max results
offset	number	0	Pagination offset
workspace_id	string	—	Scope list to a workspace. Requires agent_id (400 otherwise)
agent_id	string (uuid)	—	Agent identifier within the workspace
source_site	string	—	Filter by source platform (user scope only)
episode_id	string (uuid)	—	Filter to a single episode (user scope only)

Scope resolution: when workspace_id is absent, the list uses the user scope and honors source_site + episode_id filters. When workspace_id is present, agent_id is required and the list uses the workspace scope (source_site / episode_id filters do not apply).

Response (captured from running prototype — note: includes full embedding vector, truncated here):

{
  "memories": [
    {
      "id": "7a52eec6-ede8-4904-8bfd-e393bf83f279",
      "user_id": "docs-demo",
      "content": "User is allergic to peanuts and avoids all tree nuts.",
      "embedding": [-0.0395, 0.0089, "... (1024 floats)"],
      "memory_type": "episodic",
      "importance": 0.7,
      "source_site": "chatgpt",
      "source_url": "https://chat.openai.com/c/example-123",
      "episode_id": "e0727aba-000b-4c38-84dc-c023e23b8298",
      "status": "active",
      "metadata": {},
      "keywords": "allergic peanuts avoids tree nuts",
      "namespace": "site/chatgpt",
      "trust_score": 1,
      "created_at": "2026-04-05T03:21:42.748Z",
      "access_count": 2
    }
  ],
  "count": 1
}

Example:

curl 'http://localhost:3050/v1/memories/list?user_id=docs-demo&limit=3&offset=0'

GET /v1/memories/:id

Get a single memory by ID. Returns the full memory object including embedding, keywords, network, and audit fields.

Query params:

Param	Type	Default	Notes
user_id	string	required	User identifier
workspace_id	string	—	Read from a workspace scope (requires agent_id)
agent_id	string (uuid)	—	Required when workspace_id is present (400 otherwise)

Response (captured from running prototype — embedding truncated):

{
  "id": "3fa330cb-ee9e-4614-825c-1ce27539d24d",
  "user_id": "docs-demo",
  "content": "Our production stack is TypeScript, React, PostgreSQL with pgvector, and we deploy on Fly.io.",
  "embedding": [-0.0057, 0.0184, -0.0542, "... (1024 floats total)"],
  "memory_type": "episodic",
  "importance": 0.5,
  "source_site": "claude",
  "source_url": "",
  "episode_id": "6fa13017-8193-482c-84d2-5a7ad9e61a9e",
  "status": "active",
  "metadata": {},
  "keywords": "production stack typescript react postgresql pgvector deploy flyio",
  "namespace": "site/claude",
  "summary": "Our production stack is TypeScript, React, PostgreSQL with...",
  "overview": "",
  "trust_score": 1,
  "observed_at": "2026-04-05T03:21:28.152Z",
  "created_at": "2026-04-05T03:21:28.152Z",
  "last_accessed_at": "2026-04-05T03:21:49.601Z",
  "access_count": 2,
  "expired_at": null,
  "deleted_at": null,
  "network": "experience",
  "opinion_confidence": null,
  "observation_subject": null,
  "deferred_audn": false,
  "audn_candidates": null,
  "workspace_id": null,
  "agent_id": null,
  "visibility": null,
  "search_vector": "'deploy':12,21 'fly.io':14 'flyio':22 'pgvector':9,20 ..."
}

Returns 404 { "error": "Memory not found" } if the ID does not exist for the given user.

Example:

curl 'http://localhost:3050/v1/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo'

DELETE /v1/memories/:id

Delete a single memory.

Query params:

Param	Type	Default	Notes
user_id	string	required	User identifier
workspace_id	string	—	Delete from a workspace scope (requires agent_id)
agent_id	string (uuid)	—	Required when workspace_id is present (400 otherwise)

Response:

{ "success": true }

Returns 404 { "error": "Memory not found" } when the memory does not exist in the requested scope.

Example:

curl -X DELETE 'http://localhost:3050/v1/memories/3fa330cb-ee9e-4614-825c-1ce27539d24d?user_id=docs-demo'

POST /v1/memories/expand

Expand a set of memory IDs into their full content. Used for follow-up retrieval after search returns expand_ids.

Request:

{
  "user_id": "ethan",
  "memory_ids": ["cf3a5877-...", "4c2df147-..."]
}

Response:

{
  "memories": [
    { "id": "cf3a5877-...", "content": "...", "importance": 0.5 }
  ]
}

Stats & Cap

GET /v1/memories/stats

Per-user memory statistics.

Query params: user_id (required)

Response (captured from running prototype):

{
  "count": 3,
  "avgImportance": 0.600000003973643,
  "sourceDistribution": {
    "chatgpt": 2,
    "claude": 1
  }
}

Example:

curl 'http://localhost:3050/v1/memories/stats?user_id=docs-demo'

GET /v1/memories/cap

Check user storage quota.

Query params: user_id (required)

Example:

curl 'http://localhost:3050/v1/memories/cap?user_id=ethan'