> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory API — Long-Term User Facts

> Store, search, optimize, and delete semantic vector memories that persist user preferences and facts across all agent conversations.

The Memory API manages long-term semantic memory for users. Unlike session history (which stores the conversation transcript), memories capture specific user facts and preferences that should persist across sessions — for example, "User prefers dark mode" or "User works in the finance department." These facts are stored as vector embeddings in PostgreSQL and retrieved by semantic similarity during agent runs.

All endpoints scope their operations to a specific user via the `userId` parameter. When `userId` is omitted, the server resolves it from the authenticated principal.

All requests require a valid bearer token in the `Authorization` header.

***

## Add a memory

```
POST /api/memories
```

Stores a new fact in the semantic memory store for the authenticated user. The content is embedded and indexed in pgvector for future retrieval.

<ParamField body="content" type="string" required>
  The fact or preference to store. Write it as a natural language statement, e.g. `"User prefers responses in bullet-point format."`. The `content` field must not be blank.
</ParamField>

<ResponseField name="message" type="string">
  Confirmation that the memory was saved.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/memories" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --data '{ "content": "User prefers responses in bullet-point format." }'
  ```
</CodeGroup>

**Example response**

```json theme={null}
{ "message": "Memory saved" }
```

***

## Search memories

```
GET /api/memories?query=string
```

Performs a semantic vector search across the user's memory store and returns the most relevant facts as plain strings. The search uses embedding similarity — you do not need exact keyword matches.

<ParamField query="query" type="string" required>
  The natural language query to search for relevant memories.
</ParamField>

<ResponseField name="[]" type="string[]">
  Array of memory content strings, ranked by semantic similarity to the query.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/memories?query=user+preferences" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
[
  "User prefers responses in bullet-point format.",
  "User prefers dark mode in all applications.",
  "User works in the finance department and focuses on equity research."
]
```

***

## Delete memories

```
DELETE /api/memories
```

Deletes a specific list of memories by their document IDs. Pass an array of IDs in the request body. Returns `204 No Content` on success.

<ParamField body="[]" type="string[]" required>
  Array of memory document IDs to delete.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/memories" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --data '["mem_id_001", "mem_id_002", "mem_id_003"]'
  ```
</CodeGroup>

Returns `204 No Content` with an empty body on success.

***

## Optimize memories

```
POST /api/memories/optimize?userId=string
```

Triggers an asynchronous background job that consolidates and deduplicates the user's memory store using an LLM. Redundant or contradictory memories are merged or removed. Returns a `jobId` immediately.

<ParamField query="userId" type="string">
  The user whose memories to optimize. Defaults to the authenticated principal when omitted.
</ParamField>

<ResponseField name="jobId" type="string">
  The background job identifier. The optimization runs asynchronously — no webhook or polling endpoint is currently exposed for this job type.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "http://localhost:8080/api/memories/optimize?userId=user_abc123" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{ "jobId": "job_4c7e2a89-1b3d-4f5e-9c6a-xyz012abc345" }
```

<Note>
  Memory optimization runs asynchronously. If an optimization pass is already in progress for the same user when you call this endpoint, the system returns immediately without queuing a duplicate job.
</Note>

***

## Memory statistics

```
GET /api/memories/stats?userId=string
```

Returns aggregate statistics about the user's memory store, such as total memory count and approximate token usage.

<ParamField query="userId" type="string">
  The user whose statistics to retrieve. Defaults to the authenticated principal.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/memories/stats?userId=user_abc123" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "totalMemories": 42,
  "estimatedTokens": 1850,
  "userId": "user_abc123"
}
```

***

## Memory topics

```
GET /api/memories/topics?userId=string
```

Returns a list of high-level topic clusters derived from the user's memories. Topics are generated and cached by the memory optimization routine.

<ParamField query="userId" type="string">
  The user whose topics to retrieve. Defaults to the authenticated principal.
</ParamField>

<ResponseField name="[]" type="string[]">
  Array of topic label strings, e.g. `"work preferences"`, `"communication style"`, `"domain expertise"`.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "http://localhost:8080/api/memories/topics?userId=user_abc123" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

**Example response**

```json theme={null}
[
  "work preferences",
  "communication style",
  "domain expertise",
  "tool preferences",
  "scheduling habits"
]
```

<Tip>
  Topics are refreshed by the optimize endpoint. If topics are stale or empty, trigger `POST /api/memories/optimize` to regenerate them from the current memory store.
</Tip>