Work with memory
On this page you’ll write memories explicitly through the API, then list, edit, and delete them.
The output on this page is real output from v1.0.0-rc.2. It differs from the OpenAPI spec in several places: a memory’s status is active where the spec lists valid and invalidated; the default page_size is 50 where the spec says 20; and the responses to editing and deleting a memory have a different shape, and need an ns parameter the spec doesn’t declare.
Prerequisites
- A running Cortrix service. See the Quickstart.
- A namespace to hold the memories. This page uses
assistant:
Memory types
| Type | Meaning |
|---|---|
fact | A fact |
preference | A preference |
event | An event. Event memories decay over time, while facts and preferences don’t |
Write a memory
namespace, content, and memory_type are required. metadata is optional:
A memory written this way is an explicit memory. It isn’t validated by an LLM.
List memories
Query parameters:
| Parameter | Description |
|---|---|
namespace | Required |
memory_type | List only one type: fact, preference, or event |
include_invalidated | When true, also return invalidated memories. The default is false |
limit, offset | Paging |
Edit a memory
An edit doesn’t overwrite the original. Cortrix creates a new memory and marks the old one invalidated:
The edit request body must include both ns and content, or the request returns 400 ns + content are required. The OpenAPI spec doesn’t list ns in this endpoint’s request body, so this page follows the tested behavior.
Delete a memory
Deleting a memory is a soft delete. The memory is marked invalidated, but it’s always kept and never physically removed. Pass the namespace as the ns query parameter:
Invalidated memories don’t appear in the list by default. Add include_invalidated=true to see them:
Sessions
A memory session groups a set of conversation turns. namespace is required when you create one:
To write a turn to a session, use POST /api/v1/memory/sessions/{session_id}/interactions. namespace, query_text, and response_text are required.
In development
| Capability | Status |
|---|---|
| Automatic memory extraction from conversations | In development. Not supported yet |
| Automatic handling of contradicting memories | In development. Not supported yet |
Known limitation
POST /api/v1/memory/search requires query, namespace, and user_id. In testing, it didn’t return memories written explicitly through POST /api/v1/memory, and a regular query against the same namespace didn’t return them either. To read explicit memories, use the list endpoint above.