Skip to main content
Beyond ingest and search, AtomicMemory exposes three management endpoints that let you inspect and clean up the memories stored in any given scope. You can list all memories with pagination, retrieve a single record by its ID, or soft-delete a memory to remove it from active retrieval while preserving it in the audit trail.

​
GET /v1/memories/list

Returns a paginated list of all memories that belong to the specified scope. At least one scope query parameter is required. Use this endpoint to browse what the memory engine has stored for a user, agent, or namespace — for example, to build a memory inspector UI or to verify that an ingest operation produced the expected records.

​
Query Parameters

​
user
string
Filter to memories belonging to this user identifier.
​
agent
string
Filter to memories belonging to this agent identifier.
​
namespace
string
Filter to memories in this logical namespace.
​
thread
string
Filter to memories from this conversation thread or session.
​
limit
number
default:"20"
Maximum number of memories to return per page.
​
offset
number
default:"0"
Number of records to skip before returning results. Use with limit to paginate through large scopes.
At least one scope parameter (user, agent, namespace, or thread) must be present. Requests with no scope filters are rejected with a 400 Bad Request error.

​
Example Request

curl -G http://127.0.0.1:17350/v1/memories/list \
  -H "Authorization: Bearer local-dev-key" \
  --data-urlencode "user=alice" \
  --data-urlencode "limit=10"

​
Response

{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "Alice prefers TypeScript over JavaScript.",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "scope": {"user": "alice"},
      "version": 1
    }
  ],
  "total": 1
}

​
GET /v1/memories/:id

Fetches a single memory record by its unique ID. Use this to inspect an individual memory’s full metadata — including its version history stamp, scope, and timestamps — after retrieving its ID from a search or list response.

​
Path Parameters

​
id
string
required
The unique memory ID, for example mem_abc123. Memory IDs are returned in the id field of every ingest, search, and list response.

​
Example Request

curl http://127.0.0.1:17350/v1/memories/mem_abc123 \
  -H "Authorization: Bearer local-dev-key"

​
Response

Returns a single Memory object.
​
id
string
The unique identifier for this memory record.
​
content
string
The stored memory content as a plain-language claim.
​
createdAt
string
ISO 8601 timestamp of when the memory was first created.
​
updatedAt
string
ISO 8601 timestamp of the most recent update to this memory record.
​
scope
object
The scope dimensions this memory belongs to (user, agent, namespace, thread).
​
version
number
The current version number of this memory record. Incremented on every update.

​
Example Response

{
  "id": "mem_abc123",
  "content": "Alice prefers TypeScript over JavaScript.",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "scope": {"user": "alice"},
  "version": 1
}

​
DELETE /v1/memories/:id

Soft-deletes a memory by marking it as deleted in the store. Soft-deleted memories are excluded from all search and list results immediately, but the underlying record is retained for audit and lineage purposes.

​
Path Parameters

​
id
string
required
The unique memory ID to delete, for example mem_abc123.

​
Example Request

curl -X DELETE http://127.0.0.1:17350/v1/memories/mem_abc123 \
  -H "Authorization: Bearer local-dev-key"

​
Response

​
deleted
boolean
true if the memory was successfully soft-deleted.
​
id
string
The ID of the deleted memory, confirming which record was affected.

​
Example Response

{
  "deleted": true,
  "id": "mem_abc123"
}
This endpoint performs a soft delete. The memory record is retained internally for audit and temporal lineage tracking and will not be returned in any search or list response going forward. If you need to permanently and irrecoverably remove a memory record, use the governance Operator Action API with an admin key.