Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openmem.blog/llms.txt

Use this file to discover all available pages before exploring further.

The /memories endpoints cover the full lifecycle of a memory record: creating, reading, updating, deleting, and paginated listing. All five operations share the same Memory response schema and the same error envelope described in Error codes and HTTP status mapping.

​
POST /memories

Add a new memory record. Returns the created Memory object with a provider-assigned id.

​
Request body

​
content
string
required
The text content of the memory. This is the only field that all providers are required to index and return.
​
user_id
string
required
The user this memory belongs to. All memory operations are scoped to a user_id.
​
scope
string
Slash-delimited hierarchical namespace, e.g. coding/preferences or health/symptoms. Used to filter and access-control memories. See Scopes for full scope semantics.
​
tags
string[]
Free-form labels attached to this memory. You can filter by a single tag using GET /memories?tag=<value>.
​
source
object
Origin metadata for the memory.
​
confidence
number
A float between 0 and 1 indicating how confident the system is in this memory. Defaults to null if omitted.
​
valid_from
string
ISO 8601 datetime from which this memory is considered valid.
​
valid_to
string
ISO 8601 datetime after which this memory is no longer valid. Pass null for no expiry.
​
supersedes
string[]
List of memory IDs that this record replaces. Useful when updating a fact while preserving history.

​
Response — 201 Created

​
id
string
required
Provider-assigned unique identifier for the memory (e.g. mem_abc123).
​
content
string
required
The stored text content.
​
user_id
string
required
The user this memory belongs to.
​
created_at
string
required
ISO 8601 datetime when the record was created.
​
scope
string
Scope if provided at creation time.
​
tags
string[]
Tags if provided at creation time.
​
source
object
Source metadata if provided at creation time.
​
confidence
number
Confidence score between 0 and 1.
​
valid_from
string
Validity start datetime.
​
valid_to
string
Validity end datetime, or null.
​
supersedes
string[]
IDs of memories this record supersedes.
​
embedding_model
string
The embedding model used to index the content, if reported by the provider.
​
updated_at
string
ISO 8601 datetime of the last update.
​
status
string
Ingestion lifecycle state. One of queued, indexing, done, or failed. Synchronous providers always return done. Absent or null means the provider does not track ingestion state.

​
Example

curl -s -X POST http://localhost:8080/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers pnpm over npm",
    "user_id": "u1",
    "scope": "coding/preferences",
    "tags": ["tooling", "nodejs"],
    "source": { "app": "cursor", "type": "extracted" },
    "confidence": 0.92
  }'

{
  "id": "mem_abc123",
  "content": "User prefers pnpm over npm",
  "user_id": "u1",
  "scope": "coding/preferences",
  "tags": ["tooling", "nodejs"],
  "source": { "app": "cursor", "type": "extracted", "ref": null },
  "confidence": 0.92,
  "valid_from": null,
  "valid_to": null,
  "supersedes": null,
  "embedding_model": "text-embedding-3-small",
  "created_at": "2026-04-27T10:00:00Z",
  "updated_at": "2026-04-27T10:00:00Z",
  "status": "done"
}

​
GET /memories/{id}

Retrieve a single memory by its ID.

​
Path parameters

​
id
string
required
The memory ID returned when the record was created (e.g. mem_abc123).

​
Response — 200 OK

Returns the Memory object. Returns 404 with a not_found error code if the ID does not exist.

​
Example

curl -s http://localhost:8080/memories/mem_abc123

{
  "id": "mem_abc123",
  "content": "User prefers pnpm over npm",
  "user_id": "u1",
  "scope": "coding/preferences",
  "tags": ["tooling", "nodejs"],
  "created_at": "2026-04-27T10:00:00Z",
  "updated_at": "2026-04-27T10:00:00Z",
  "status": "done"
}

​
PATCH /memories/{id}

Update one or more fields of an existing memory. All fields in the request body are optional — only the fields you include are modified.

​
Path parameters

​
id
string
required
The ID of the memory to update.

​
Request body

​
content
string
New text content for the memory.
​
scope
string
Updated scope path.
​
tags
string[]
Replacement tag list. The entire list is replaced, not merged.
​
confidence
number
Updated confidence score between 0 and 1.
​
valid_to
string
Updated expiry datetime, or null to remove the expiry.
​
supersedes
string[]
Updated list of memory IDs that this record replaces.

​
Response — 200 OK

Returns the full updated Memory object. Returns 404 if the ID does not exist.

​
Example

curl -s -X PATCH http://localhost:8080/memories/mem_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers bun for new projects",
    "supersedes": ["mem_abc123"]
  }'

​
DELETE /memories/{id}

Permanently delete a memory. This action cannot be undone.

​
Path parameters

​
id
string
required
The ID of the memory to delete.

​
Response — 204 No Content

Returns an empty body on success. Returns 404 if the ID does not exist.
Deletion is permanent. If you want to preserve history while marking a memory as replaced, use PATCH /memories/{id} with the supersedes field instead.

​
Example

curl -s -X DELETE http://localhost:8080/memories/mem_abc123
# (empty body, HTTP 204)

​
GET /memories

Return a paginated list of memories for a user, with optional filtering by scope, tag, and time range.

​
Query parameters

​
user_id
string
required
Return only memories belonging to this user.
​
scope
string
Glob pattern to filter by scope, e.g. coding/* returns all memories under the coding/ hierarchy.
​
tag
string
Return only memories that have this tag. To filter by multiple tags, call the endpoint multiple times and intersect client-side, or use GET /memories/search.
​
since
string
ISO 8601 datetime. Return only memories created at or after this time.
​
until
string
ISO 8601 datetime. Return only memories created before or at this time.
​
limit
integer
default:"50"
Maximum number of results per page. Maximum is 500.
​
cursor
string
Opaque pagination cursor from the previous response’s next_cursor field. Omit to start from the beginning.

​
Response — 200 OK

​
items
Memory[]
required
The list of memory records for this page.
​
next_cursor
string
Opaque string to pass as cursor in the next request. null when there are no more results.

​
Pagination example

# First page
curl -s "http://localhost:8080/memories?user_id=u1&limit=2"

{
  "items": [
    { "id": "mem_abc123", "content": "User prefers pnpm over npm", "..." },
    { "id": "mem_def456", "content": "User prefers dark mode", "..." }
  ],
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}

# Second page — pass the cursor from the previous response
curl -s "http://localhost:8080/memories?user_id=u1&limit=2&cursor=eyJvZmZzZXQiOjJ9"

{
  "items": [
    { "id": "mem_ghi789", "content": "User is based in Berlin", "..." }
  ],
  "next_cursor": null
}
Treat next_cursor as an opaque value. Its internal structure is provider-defined and may change across releases.