> ## 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.

# Long-Term Memory: Persistent User Facts

> Store semantic facts about users in vector storage so agents recall preferences and context across every conversation, not just the current one.

Long-term memory lets Agent Manager store semantic facts about a user—preferences, decisions, background context—in a pgvector table that persists across all sessions. Unlike session history, which is scoped to a single conversation, memory is permanent until you explicitly delete it. When an agent starts a new conversation, it searches memory for relevant facts and uses them to personalize its response without you having to repeat yourself.

## How agents use memory

During a conversation, agents can call two built-in tools automatically:

* **`save_memory(content)`** — stores a new fact extracted from the conversation.
* **`search_memory(query)`** — performs a semantic vector search over stored facts to retrieve relevant context.

You do not configure these tools manually. When an agent detects information worth remembering (a user preference, a decision, a correction), it calls `save_memory`. When it needs context from past interactions, it calls `search_memory`. Both happen transparently as part of the agent's reasoning loop.

<Info>
  Long-term memory is distinct from session history. Session history records the raw message transcript for a single conversation. Memory stores distilled facts that travel with the user indefinitely.
</Info>

## Adding a memory

You can add facts programmatically using `POST /api/memories`. This is useful for seeding initial context—for example, onboarding information from your CRM—before a user's first conversation.

```bash theme={null}
curl -X POST http://localhost:8080/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "The user prefers responses in Spanish and works in the healthcare industry."}'
```

**Response**

```json theme={null}
{
  "status": "saved"
}
```

<ParamField body="content" type="string" required>
  The fact to store. Write facts as plain prose sentences. The content is embedded as a vector, so descriptive natural-language phrasing improves retrieval accuracy.
</ParamField>

## Searching memories

`GET /api/memories` performs a semantic vector search and returns the facts most relevant to your query. This is the same mechanism agents use internally when calling `search_memory`.

```bash theme={null}
curl "http://localhost:8080/api/memories?query=communication+preferences"
```

**Response**

```json theme={null}
[
  "The user prefers responses in Spanish and works in the healthcare industry.",
  "The user previously requested that summaries be limited to three bullet points."
]
```

Results are ranked by semantic similarity to the query string.

## Deleting memories

To remove specific memories, send a `DELETE /api/memories` request with a JSON array of memory IDs in the body.

```bash theme={null}
curl -X DELETE http://localhost:8080/api/memories \
  -H "Content-Type: application/json" \
  -d '["mem-uuid-1", "mem-uuid-2"]'
```

Returns `204 No Content` on success.

<Warning>
  Deleted memories cannot be recovered. If an agent saved a memory automatically during a conversation, deleting it here removes it permanently.
</Warning>

## Optimizing memory

Over time, a user's memory store can accumulate redundant or outdated facts. `POST /api/memories/optimize` triggers an LLM-based consolidation pass that deduplicates overlapping facts, resolves contradictions, and improves overall memory quality.

```bash theme={null}
curl -X POST "http://localhost:8080/api/memories/optimize?userId=user-123"
```

**Response**

```json theme={null}
{
  "status": "optimization_started"
}
```

Optimization runs asynchronously. Run it periodically—for example, after a user completes a long onboarding flow—or on a scheduled basis for active users.

<Tip>
  Memory optimization is especially effective after a user has had several conversations. Early optimization on sparse memory stores has minimal benefit.
</Tip>

## Memory statistics

`GET /api/memories/stats` returns usage statistics for a given user's memory store. Use this to monitor memory growth and decide when to run optimization.

```bash theme={null}
curl "http://localhost:8080/api/memories/stats?userId=user-123"
```

**Response**

```json theme={null}
{
  "totalMemories": 47,
  "oldestMemoryDate": "2026-01-15T08:30:00Z",
  "lastUpdated": "2026-05-06T09:00:00Z"
}
```

## Memory topics

`GET /api/memories/topics` returns high-level topic clusters derived from a user's stored facts. Use this to build summary views in your UI or to understand what the agent knows about a user at a glance.

```bash theme={null}
curl "http://localhost:8080/api/memories/topics?userId=user-123"
```

**Response**

```json theme={null}
[
  "Communication preferences",
  "Industry and role",
  "Product usage patterns",
  "Past support interactions"
]
```

## Memory vs. session history

|                  | Long-term memory                      | Session history                    |
| ---------------- | ------------------------------------- | ---------------------------------- |
| **Scope**        | All sessions, all time                | A single conversation              |
| **Storage**      | Vector database                       | Relational database                |
| **Retrieval**    | Semantic similarity search            | Chronological message replay       |
| **Managed by**   | `save_memory` / `search_memory` tools | Automatic per-session context      |
| **Deleted with** | `DELETE /api/memories`                | `DELETE /api/sessions/{sessionId}` |

For more on session history, see [Sessions: Conversation History and Context](/knowledge/sessions).