Memory store endpoints

The /v1/store endpoints let you store, search, list, read, update, delete and bulk-forget long-term memories through the 10xGraph API server. They work only when a store is configured in 10xgraph.json; without one, every endpoint returns 503 with “Store is not configured”. Responses use the standard data and metadata envelope.

Base path: /v1/store

Request fields shared by every endpoint

Every request body accepts two optional fields besides the endpoint-specific ones, and the server decides whose memories a request touches from the authenticated user, not from the body.

The server sets user_id from the authenticated user (or anonymous when auth is off). Sending user_id in config has no effect. See the REST conventions for the envelope and error format.

POST /v1/store/memories

Store a memory record. Requires store:write permission.

Request body:

{
  "content": "User prefers concise responses.",
  "memory_type": "episodic",
  "category": "preference",
  "metadata": {"source": "chat"},
  "config": {}
}

Response (200 OK):

{
  "data": {
    "memory_id": "mem_abc123"
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "Memory stored successfully"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:write)

Example:

curl -X POST http://localhost:8000/v1/store/memories \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers concise responses.",
    "memory_type": "episodic",
    "category": "preference"
  }'

POST /v1/store/search

Search memories by semantic similarity. Requires store:read permission.

Request body:

{
  "query": "How does this user like to receive information?",
  "category": "preference",
  "limit": 5,
  "config": {}
}

Response (200 OK):

{
  "data": {
    "results": [
      {
        "id": "mem_abc123",
        "content": "User prefers concise responses.",
        "score": 0.91,
        "memory_type": "episodic",
        "metadata": {"source": "chat", "category": "preference"},
        "user_id": "user-123",
        "thread_id": null,
        "timestamp": "2026-10-08T10:30:00Z"
      }
    ]
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "OK"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:read)
• 422 Unprocessable Entity: query is empty or whitespace-only, or limit outside valid range

Example:

curl -X POST http://localhost:8000/v1/store/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "limit": 5,
    "config": {}
  }'

POST /v1/store/memories/list

List stored memories (subject to backend limits). Requires store:read permission.

This is a POST endpoint (not GET) because the request carries a config object for scoping. An empty or null body is valid and applies defaults.

Request body (optional):

{
  "limit": 50,
  "config": {}
}

Response (200 OK):

{
  "data": {
    "memories": [
      {
        "id": "mem_abc123",
        "content": "User prefers concise responses.",
        "score": 0.0,
        "memory_type": "episodic",
        "metadata": {"category": "preference"},
        "user_id": "user-123",
        "thread_id": null,
        "timestamp": "2026-10-08T10:30:00Z"
      }
    ]
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "OK"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:read)
• 422 Unprocessable Entity: limit is outside the 1 to 1000 range

Example:

curl -X POST http://localhost:8000/v1/store/memories/list \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "config": {}
  }'

POST /v1/store/memories/{memory_id}

Retrieve a single memory by ID. Requires store:read permission.

The request body is optional and carries only config and options. A memory_id that is empty or whitespace-only returns 422.

Request body (optional):

{
  "config": {}
}

Response (200 OK):

{
  "data": {
    "memory": {
      "id": "mem_abc123",
      "content": "User prefers concise responses.",
      "score": 0.0,
      "memory_type": "episodic",
      "metadata": {"category": "preference"},
      "user_id": "user-123",
      "thread_id": null,
      "timestamp": "2026-10-08T10:30:00Z"
    }
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "OK"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:read)
• 422 Unprocessable Entity: memory_id is empty or whitespace-only

Example:

curl -X POST http://localhost:8000/v1/store/memories/mem_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {}
  }'

PUT /v1/store/memories/{memory_id}

Update the content or metadata of a stored memory. Requires store:write permission.

Request body:

{
  "content": "Updated memory content.",
  "metadata": {"updated": true},
  "config": {}
}

Response (200 OK):

{
  "data": {
    "success": true,
    "data": null
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "Memory updated successfully"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:write)
• 422 Unprocessable Entity: memory_id is empty or whitespace-only

Example:

curl -X PUT http://localhost:8000/v1/store/memories/mem_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated memory content.",
    "metadata": {"updated_at": "2026-10-08"}
  }'

DELETE /v1/store/memories/{memory_id}

Delete a single memory record by ID. Requires store:delete permission.

The request body is optional and carries only config and options. A memory_id that is empty or whitespace-only returns 422.

Response (200 OK):

{
  "data": {
    "success": true,
    "data": null
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "Memory deleted successfully"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:delete)
• 422 Unprocessable Entity: memory_id is empty or whitespace-only

Example:

curl -X DELETE http://localhost:8000/v1/store/memories/mem_abc123 \
  -H "Authorization: Bearer <token>"

POST /v1/store/memories/forget

Delete all memories matching the given filters. Requires store:delete permission.

Use this to bulk-delete memories by type, category, or custom filters without listing them first.

Request body:

{
  "memory_type": "episodic",
  "category": "preference",
  "filters": {"source": "chat"},
  "config": {}
}

Response (200 OK):

{
  "data": {
    "success": true,
    "data": null
  },
  "metadata": {
    "request_id": "req_xyz",
    "timestamp": "2026-10-08T10:30:00Z",
    "message": "Memories removed successfully"
  }
}

Error codes:

• 401 Unauthorized: missing or invalid auth token
• 403 Forbidden: insufficient permission (not store:delete)

Example:

curl -X POST http://localhost:8000/v1/store/memories/forget \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "old_session",
    "config": {}
  }'

Memory object fields

Search, list and get return memory objects with these fields. score is a relevance score for search and 0.0 for list and get; vector is also part of the model and is null unless the backend returns it.

Client metadata keys that the store owns (content, user_id, thread_id, memory_type, category, timestamp, memory_id) are dropped on store and update.

The data of update, delete and forget responses is {"success": true, "data": <backend result>}, where the inner data depends on the store backend and is often null.

Permissions and authentication

All endpoints require the authenticated user to hold the appropriate permission:

Auth tokens are passed via the Authorization: Bearer <token> header. See Authentication and authorization for JWT setup and custom auth backends.

Related pages

• Use the memory store for a task walkthrough.
• Memory stores (Python) for the BaseStore API behind these routes.
• Memory API (client) for the TypeScript wrappers.