> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/architecture-and-concepts/user-memory.md).

# Persistent User Memory

Persistent User Memory enables EDDI agents to remember facts, preferences, and context about individual users **across conversations**. Unlike conversation-scoped properties that are lost when a conversation ends, persistent memories survive indefinitely and are automatically loaded into every new conversation with the same user.

## Overview

| Feature             | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **Scope**           | Per-user, per-agent (or globally shared)                                                     |
| **Storage**         | MongoDB (`usermemories` collection) or PostgreSQL (`usermemories` table)                     |
| **LLM Integration** | 4 built-in tools for autonomous memory management                                            |
| **Visibility**      | `self`, `group`, `global` scoping                                                            |
| **Guardrails**      | Configurable key/value limits, write-rate limits, capacity caps                              |
| **GDPR**            | Full right-to-erasure support via REST API and MCP tools                                     |
| **Maintenance**     | Background "Dream" consolidation (stale pruning, contradiction detection, LLM summarization) |

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Conversation Pipeline              │
│                                                      │
│  LLM ──→ UserMemoryTool ──→ IUserMemoryStore        │
│            ↑                       ↑                 │
│            │                       │                 │
│      AgentOrchestrator     MongoUserMemoryStore      │
│      (per-invocation)      PostgresUserMemoryStore   │
│                                                      │
│  REST API ───────────────────→ IUserMemoryStore      │
│  MCP Tools ──────────────────→ IUserMemoryStore      │
│  DreamService (background) ─→ IUserMemoryStore      │
└─────────────────────────────────────────────────────┘
```

## Agent Configuration

Enable advanced memory features (LLM tools, Dream consolidation, guardrails, recall settings) in your agent's configuration:

```json
{
  "name": "My Agent",
  "enableMemoryTools": true,
  "userMemoryConfig": {
    "maxEntriesPerUser": 500,
    "maxRecallEntries": 50,
    "recallOrder": "most_recent",
    "onCapReached": "evict_oldest",
    "guardrails": {
      "maxKeyLength": 100,
      "maxValueLength": 1000,
      "maxWritesPerTurn": 10,
      "allowedCategories": ["preference", "fact", "context"]
    },
    "dream": {
      "enabled": true,
      "pruneStaleAfterDays": 90,
      "detectContradictions": true,
      "summarizeInteractions": true,
      "summarizeMinEntries": 5,
      "summarizeTargetEntries": 2,
      "summarizeGroupBy": "category",
      "preserveAgentProvenance": false,
      "maxCostPerRun": 0.50,
      "parameters": { "apiKey": "${vault:anthropic-api-key}" }
    }
  }
}
```

The LLM task (`langchain.json`) must separately enable built-in tools — `builtInToolsWhitelist` is a field of the LLM task, not of the agent:

```json
{
  "enableBuiltInTools": true,
  "builtInToolsWhitelist": ["usermemory"]
}
```

Attaching the memory tools is a three-way conjunction across the two configuration files: the agent's `enableMemoryTools: true` **and** its `userMemoryConfig` **and** the LLM task's `enableBuiltInTools: true`, with `builtInToolsWhitelist` either omitted (all built-ins) or containing `"usermemory"`. Miss any part and the agent gets no memory tools, with only a WARN in the log.

> **Note:** `enableMemoryTools` gates exactly one thing: attaching the LLM `UserMemoryTool` (and with it the `guardrails`, which only that tool enforces). Everything else in `userMemoryConfig` applies whenever the block is declared, with or without the flag — `defaultVisibility` and the recall settings govern the `longTerm` property path that **every** agent uses, and Dream is switched on by `dream.enabled` plus a schedule. Earlier releases ignored the whole block unless `enableMemoryTools` was on, so a rule-based agent's `"defaultVisibility": "self"` silently persisted as `global`.

### Configuration Reference

| Field                  | Type           | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------- | -------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxEntriesPerUser`    | `int`          | `500`                   | Maximum memory entries per user. Enforced across concurrent writers: the count is checked before a new fact is written and again after it, so two conversations of the same user saving at the same moment cannot leave the user above the cap — the insert that lands over it is undone (`reject`) or makes room by evicting one more of its agent's oldest entries (`evict_oldest`) |
| `maxRecallEntries`     | `int`          | `50`                    | Maximum entries returned by recall                                                                                                                                                                                                                                                                                                                                                    |
| `recallOrder`          | `String`       | `"most_recent"`         | `"most_recent"` (by updatedAt) or `"most_accessed"` (by accessCount)                                                                                                                                                                                                                                                                                                                  |
| `onCapReached`         | `String`       | `"evict_oldest"`        | `"reject"` (refuse a **new** entry once `maxEntriesPerUser` is reached — updating an existing one is always allowed, it adds no row) or `"evict_oldest"` (permanently delete this agent's oldest entries to make room — entries owned by other agents are never evicted)                                                                                                              |
| `defaultVisibility`    | `String`       | `"self"`                | Visibility applied to a `longTerm` property that sets none (an unparseable value, or no `userMemoryConfig` at all, falls back to `global`). Applies without `enableMemoryTools`                                                                                                                                                                                                       |
| `autoRecallCategories` | `List<String>` | `["preference","fact"]` | **Reserved — not applied.** Every visible category is recalled at conversation start. It cannot be switched on retroactively: the store writes this default into every saved agent, so a stored value is indistinguishable from an explicit one, and enforcing it would stop recalling `context`, `legacy` and `property` entries for all of them                                     |

### Guardrails

| Field                     | Type           | Default                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxKeyLength`            | `int`          | `100`                             | Maximum characters for memory keys                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `maxValueLength`          | `int`          | `1000`                            | Maximum characters for memory values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `maxWritesPerTurn`        | `int`          | `10`                              | Write-rate limit per conversation turn, shared by `rememberFact` and `forgetFact`: a stored fact and a deleted one each count once. The turn is the whole turn — every LLM task in it, every step of an agent-mode model cascade, the continuation of a turn resumed after a HITL tool approval, and a rerun of the turn (whose first run's writes stand) spend the same budget. A re-save of a fact that is already stored unchanged is not a write and does not count, and neither does a refused write or a `forgetFact` that finds nothing to delete |
| `allowedCategories`       | `List<String>` | `["preference","fact","context"]` | Allowed memory categories                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `allowedVisibilities`     | `List<String>` | `["self"]`                        | Visibilities the `rememberFact` tool may write (`self`, `group`, `global`). By default the model can only store memories private to this agent, so a prompt-injected model cannot broadcast to every agent (`global`) or the group. The configured `defaultVisibility` is always added, so a default can never block every write                                                                                                                                                                                                                         |
| `allowGlobalKeyOverwrite` | `boolean`      | `false`                           | Whether a `global` write may replace the value of an existing global key this agent does not provably own — one owned by another agent, or one whose entry records no owning agent (legacy/migrated data). Off by default: such a write is refused with a message suggesting a different key or `self` visibility                                                                                                                                                                                                                                        |

### Dream Configuration

| Field                     | Type                 | Default                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                 | `boolean`            | `false`                  | Enable background consolidation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `pruneStaleAfterDays`     | `int`                | `90`                     | Remove entries whose `updatedAt` (last write) is older than N days. Recalling an entry does **not** refresh this — only a write does. Set to 0 to disable.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `detectContradictions`    | `boolean`            | `true`                   | Detect entries with the same key but different values; what happens to them is `contradictionResolution`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `summarizeInteractions`   | `boolean`            | `false`                  | Enable LLM-driven memory consolidation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `summarizeMinEntries`     | `int`                | `5`                      | Minimum entries in a group before summarization triggers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `summarizeTargetEntries`  | `int`                | `2`                      | Target number of entries per group after consolidation. It is passed to the model; an answer above it (but below the original count) is kept whole — never truncated, because the originals are deleted                                                                                                                                                                                                                                                                                                                                                           |
| `summarizeGroupBy`        | `String`             | `"category"`             | Grouping strategy: `"category"` or `"all"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `preserveAgentProvenance` | `boolean`            | `false`                  | Sub-group by `sourceAgentId` (preserves per-agent provenance)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `maxSummarizationCalls`   | `int`                | `10`                     | **Deprecated** — prefer `maxCostPerRun`. Still honoured as a secondary backstop *if you set it explicitly*, because silently dropping a bound an operator wrote is worse than enforcing a redundant one. A call count is a poor budget: consolidations differ wildly in cost.                                                                                                                                                                                                                                                                                     |
| `summarizationPrompt`     | `String`             | *(built-in)*             | Custom LLM instructions for consolidation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `maxCostPerRun`           | `double`             | `0.50`                   | Maximum dollar cost per dream cycle — the primary ceiling. A soft cap: it is checked before each consolidation call against the **estimated** spend so far (see `inputPricePer1M`)                                                                                                                                                                                                                                                                                                                                                                                |
| `inputPricePer1M`         | `Double`             | *(unset)*                | USD price per 1M input tokens of `llmModel`, used to estimate spend against `maxCostPerRun`. Unset: an upper bound of **$15** is assumed — the input list price of the most expensive mainstream tier (Claude Opus) — so the estimate errs high and a run stops early rather than late. Set both prices to make the budget accurate                                                                                                                                                                                                                               |
| `outputPricePer1M`        | `Double`             | *(unset)*                | USD price per 1M output tokens of `llmModel`. Unset: an upper bound of **$75** (Claude Opus output). When the provider reports no token usage, tokens are estimated at 3 characters each                                                                                                                                                                                                                                                                                                                                                                          |
| `crossAgentMaintenance`   | `boolean`            | `false`                  | By default a dream cycle only touches memories the **firing agent** wrote (`sourceAgentId`). Set `true` to let it maintain the user's whole memory set across agents — otherwise agent A's retention setting would delete agent B's memories, and A's model endpoint would see B's private text. A merged entry's last writer (`lastWriterAgentId`) follows the values merged, not their owners: no agent when the user or an admin wrote them all, the one agent that wrote any of them, and the firing agent when several did, since its model wrote the merge. |
| `llmProvider`             | `String`             | `"anthropic"`            | LLM provider for dream operations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `llmModel`                | `String`             | `"claude-sonnet-4-6"`    | Model for dream operations. Passed under the key the provider reads (`model` for Ollama, `modelId` for Bedrock/HuggingFace/Vertex, `deploymentName` for Azure, `modelName` otherwise)                                                                                                                                                                                                                                                                                                                                                                             |
| `parameters`              | `Map<String,String>` | `{}`                     | Model parameters for the consolidation LLM — `apiKey`, `baseUrl`, `temperature`, … — passed to the model registry exactly like an LLM task's `parameters` block, so `${vault:…}` and `${vars:…}` resolve. **Required when `summarizeInteractions` is `true`**: a background dream cycle has no parent LLM task to inherit credentials from, so without it every summarization step fails with a provider 401 while stale pruning keeps working.                                                                                                                   |
| `schedule`                | `String`             | `"0 3 * * *"`            | Cron expression the dream schedule should use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `citeSources`             | `boolean`            | `false`                  | Make every consolidated entry name the originals it came from, check each one without a model, and record their ids in `sourceEntryIds`. See [Traceable consolidation](#traceable-consolidation-citesources)                                                                                                                                                                                                                                                                                                                                                      |
| `onValidationFailure`     | `String`             | `"fallback_to_previous"` | What a consolidation group that fails the `citeSources` check does: `fallback_to_previous` (keep the originals), `retry_once` or `keep`. Ignored while `citeSources` is false                                                                                                                                                                                                                                                                                                                                                                                     |
| `contradictionResolution` | `String`             | `"keep_newest"`          | What a cycle does with a detected contradiction: `keep_newest` (count and log only — the default and the behaviour of earlier releases), `mark_contested` (flag both sides `CONTESTED`, keep both) or `supersede_older` (retire the older side as `SUPERSEDED` where the newer one reaches all of its readers, otherwise contested). No value deletes an entry. An unknown value logs a WARN and acts as `keep_newest`. See [Contradiction resolution](#contradiction-resolution)                                                                                 |

`rememberFact` resolves which stored entry a write lands on before writing: re-stating an unchanged fact answers `✅ Already remembered (unchanged)` without writing, and an update of an existing entry never counts against `maxEntriesPerUser`.

## LLM Tools

When the LLM task has `enableBuiltInTools: true` and `usermemory` is in its `builtInToolsWhitelist` (or no whitelist is set), the LLM gets access to four tools:

### `rememberFact`

Store a fact about the user.

```
Parameters:
  key       - Short key name (e.g. "favorite_color", "dietary_restriction")
  value     - The value to remember
  category  - One of: "preference", "fact", "context"
  visibility - One of: "self", "group", "global" (default: "self")

Returns: "✅ Remembered: favorite_color = blue [preference, self]"
```

### `recallMemories`

Retrieve all memories visible to this agent for the current user.

```
Parameters: none

Returns:
  • name = Alice [fact, self]
  • favorite_color = blue [preference, self]
  • language = English [preference, global]
```

### `searchMemory`

Search for memories by keyword across keys and values. The query is split into terms on anything that is not a letter or digit, and an entry matches when **every** term appears (case-insensitively) in its key or its value — so `"dog name"`, `"dog_name"` and `"dog-name"` all find the key `dog_name`. Punctuation-only queries match nothing.

"Its value" means a **string** value, or a string element of an **array** value. Numbers, booleans and the fields of an object value are not searched — `true` or `42` finds nothing, and neither does a field name inside an object value. This is the same on MongoDB and PostgreSQL (PostgreSQL used to match the value's JSON text, so `true` found every boolean entry). The search returns the newest **200** matches at most (`IUserMemoryStore.MAX_FILTER_RESULTS`); the agent's visibility filter is applied to those, so a user with many matching entries from other agents can see fewer here. The REST `search` endpoint and the `search_user_memories` MCP tool use the same search and the same cap.

```
Parameters:
  query - Search text (e.g. "color")

Returns: matching entries formatted as bullet list
```

### `forgetFact`

Delete a specific memory by key. Only a memory this agent can see is deleted, and a `global` memory only when this agent owns it — unless `allowGlobalKeyOverwrite` is on, the same rule `rememberFact` applies, since deleting another agent's global key and writing it again would replace its value. A deletion counts against `maxWritesPerTurn` like a write, so one turn cannot erase more memories than it could store.

Forgetting a fact removes all of its versions: every entry under the same key that is linked to the deleted one through `supersededBy` (see [Contradiction resolution](#contradiction-resolution)) — the older entries it superseded and the newer one that superseded it, along the whole chain — is deleted with it, so an older value cannot come back once it is the reader's only entry for the key. The same two checks apply to each version: one this agent cannot see or may not delete (another agent's `self` memory, a foreign `global` one) stays, and the chain is not followed through it.

```
Parameters:
  key - The key name to forget (e.g. "favorite_color")

Returns: "✅ Forgotten: favorite_color"
```

## Visibility Scopes

| Scope    | Description                                          | Upsert Key                                                          |
| -------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `self`   | Only the agent that stored it can see it             | `(userId, key, sourceAgentId)` among the agent's non-global entries |
| `group`  | All agents in the same group conversation can see it | `(userId, key, sourceAgentId)` among the agent's non-global entries |
| `global` | All agents for this user can see it                  | `(userId, key)`                                                     |

An agent with `security.requirePeerVerification` (see [Signed contributions](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md#signed-contributions)) sees, in every conversation and not only in groups, only the entries whose value it or no agent wrote (the user, an admin), and its team's lessons: a `group` or `global` entry another agent wrote carries no signature, so it is neither loaded as a property nor returned by `recallMemories`, `searchMemory` or `forgetFact`. What counts is who wrote the value an entry holds, not who created it: a `global` entry is shared, and another agent's write replaces its value while the entry keeps its creator as owner, so each entry also records its last writer (`lastWriterAgentId`; an entry stored before this reads as written by its owner). The store leaves the other entries out before `maxRecallEntries` is applied, so they do not take the places of the ones the agent is shown. Its `longTerm` properties are written like any agent's: one for a `global` key replaces the value another agent last wrote (last writer wins) and makes this agent the writer, so it is shown the value again from then on. A property setter that sets a default for a `global` key every turn therefore overwrites what other agents stored there, verifying agent or not: give such a key `self` visibility, or set it only from the user's input. A team's lessons (`group:<groupId>`, see [Group Memory](#group-memory)) are the engine's, distilled from the team's records under its verification rule, and are loaded as usual. The setting is read from the deployed agent version.

A `self` or `group` write never touches the shared `global` entry with the same key — an agent can hold a private note and a shared fact under one key. (MongoDB used to key self/group writes without the visibility term, so saving a private note flipped the agent's own shared entry to `self` and every other agent lost it; PostgreSQL always had this identity.)

### Group Memory

When agents participate in a [Group Conversation](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md), the `groupId` is automatically injected into the conversation context. Memories stored with `group` visibility are visible to all agents in that group — whether written by `rememberFact` or by a `longTerm` property with `"visibility": "group"`, both of which stamp the conversation's group id on the entry. A `group` property in a conversation that belongs to no group is stored as `self`: without a group id no reader could ever match it, and `self` keeps it reachable without widening it.

The group is taken only from that injected context value. A client cannot supply `groupId` in its own request context (see [Reserved Context Keys](https://docs.labs.ai/agent-configuration/passing-context-information.md#reserved-context-keys)), and a conversation *property* named `groupId` does not select a group scope for the `usermemory` tool.

A `groupId` found only on an earlier step of the conversation — a turn the owner sends into a member conversation directly carries no group context — is used, by the `usermemory` tool and when `longTerm` properties are persisted alike, only while the discussion named on that step is running on this instance, this conversation is one of its members, and it belongs to that group. Otherwise the turn is self-scoped, so a value a client forged before reserved keys were filtered does not keep working.

## REST API

Base path: `/usermemorystore/memories`. Roles: `eddi-admin` or `eddi-user`; with authorization on, a non-admin may only address their own `userId` (`403` otherwise).

| Method   | Path                                                | Description                                                                                                   |
| -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/{userId}`                                         | Get all memories for a user                                                                                   |
| `GET`    | `/{userId}/visible?agentId=&groupId=&order=&limit=` | Get memories visible to a specific agent                                                                      |
| `GET`    | `/{userId}/search?q=`                               | Search memories by keyword — string values and keys, newest 200 at most (see [`searchMemory`](#searchmemory)) |
| `GET`    | `/{userId}/category/{category}`                     | Get memories filtered by category                                                                             |
| `GET`    | `/{userId}/key/{key}`                               | Get a specific memory by key                                                                                  |
| `PUT`    | `/`                                                 | Upsert a memory entry (JSON body) — validated, see below                                                      |
| `DELETE` | `/entry/{entryId}`                                  | Delete a specific memory                                                                                      |
| `DELETE` | `/{userId}`                                         | Delete ALL memories for a user (GDPR)                                                                         |
| `GET`    | `/{userId}/count`                                   | Count memory entries                                                                                          |

### Write validation

REST `PUT` and MCP `upsert_user_memory` share one rule set (`UserMemoryWriteRules`) and answer 400 / an error instead of storing:

* `userId`, `key` and `visibility` are required; keys are at most 255 characters and values at most 64 KiB of JSON;
* `self` and `group` entries need a `sourceAgentId` (MCP: `agentId`), and `group` entries need `groupIds` — an entry without them could never be read by anyone;
* `category` must be one of `preference`, `fact`, `context`, `legacy`, `property`; an absent category is stored as `fact`.

### Example: Upsert a memory

```bash
curl -X PUT http://localhost:7070/usermemorystore/memories \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "key": "preferred_language",
    "value": "German",
    "category": "preference",
    "visibility": "global",
    "sourceAgentId": "agent-456"
  }'
```

### Example: Get visible memories

```bash
curl "http://localhost:7070/usermemorystore/memories/user-123/visible?agentId=agent-456&order=most_recent&limit=20"
```

## MCP Tools

8 MCP tools are available for external integration and administration:

| Tool                       | Role               | Description                                                                       |
| -------------------------- | ------------------ | --------------------------------------------------------------------------------- |
| `list_user_memories`       | conversation tier¹ | List all entries for a user                                                       |
| `get_visible_memories`     | conversation tier¹ | Get entries visible to a specific agent                                           |
| `search_user_memories`     | conversation tier¹ | Search by keyword                                                                 |
| `get_memory_by_key`        | conversation tier¹ | Look up by key name                                                               |
| `count_user_memories`      | conversation tier¹ | Count entries                                                                     |
| `upsert_user_memory`       | `eddi-admin`       | Insert or update an entry (`groupIds` — comma-separated — for `group` visibility) |
| `delete_user_memory`       | `eddi-admin`       | Delete a specific entry; an id that names no entry is an error                    |
| `delete_all_user_memories` | `eddi-admin`       | Delete all memories except the `_gdpr_` bookkeeping entries (requires `CONFIRM`)  |

¹ Any of `eddi-admin`, `eddi-editor`, `eddi-user`, `eddi-viewer`; a non-admin reads only their own `userId`. See [MCP Server → Role Mapping](https://docs.labs.ai/protocols-and-integration/mcp-server.md#role-mapping).

### GDPR Compliance

The `delete_all_user_memories` MCP tool and `DELETE /{userId}` REST endpoint permanently remove a user's memory entries and legacy properties, **except** the GDPR bookkeeping entries (keys starting with `_gdpr_`, such as an Art. 18 processing restriction), which only the GDPR admin endpoints set or lift. They are memory housekeeping, not an Art. 17 erasure — for that use `DELETE /admin/gdpr/{userId}` (MCP: `delete_user_data`), which removes everything, including those entries, across every store. The MCP tool requires an explicit `confirmation="CONFIRM"` parameter as a safety gate.

Keys starting with `_gdpr_` are reserved: agents, property setters and the memory/property REST and MCP endpoints cannot write or delete them.

### What the user sees: "My memory" in Workforce

A signed-in person reviews and deletes their own memory in Workforce, at `/workforce/memory` ("My memory" in the sidebar and the ⌘K switcher; see the [Workforce guide](https://docs.labs.ai/protocols-and-integration/workforce-guide.md#what-your-agents-remember-about-you)). The page is built on this REST API alone:

| What the page does                                            | Endpoint                                                                                                      |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| List the entries, newest first                                | `GET /{userId}` with the caller's own principal name (the token's `preferred_username` in the Keycloak setup) |
| Forget one                                                    | `DELETE /entry/{entryId}`                                                                                     |
| Forget everything, after a confirm that names the consequence | `DELETE /{userId}`                                                                                            |

* **Only the person's own.** Every endpoint is open to `eddi-user`, and `OwnershipValidator` answers 403 when the `userId` is not the caller's principal name, so the page can only ever show its user their own entries. An administrator using the page sees their own memory there too. The Manager's **User Data → Memory** tab is where an administrator works on any user's.
* **Attribution and scope.** Each entry shows the agent that wrote it (`sourceAgentId`, by its catalog name where the person may use it, otherwise its id; legacy global entries without one say so) and its visibility in plain words: *Private* for `self` (only that agent reads it), *Team* for `group` (the agents of the teams in `groupIds`, by name), *All agents* for `global`.
* **What may be deleted.** The person may delete any of their own entries, whatever the visibility. Deleting a `global` or `group` entry removes it for every agent that reads it, and the page says so. The reserved `_gdpr_` rows are not listed at all: `DELETE /entry/{id}` refuses them (400) and `DELETE /{userId}` keeps them, so the page names their existence without offering a button that would fail. Team lessons a RETRO writes are stored under the group's own id (`group:<id>`), not the person's, so they are not part of anyone's personal memory.
* **Search** is done in the browser over what the page shows (the key, the value, the agent and team names, the category), not with `GET /{userId}/search`, which matches keys and string values only, newest 200.
* **Values are shown as text.** A stored value is rendered as a plain text child, never as markdown or HTML, and JSON values as compact JSON.
* With sign-in off there is no principal, so the page explains that there is no personal memory instead of requesting one.

## Dream Consolidation

The Dream service performs background maintenance on user memories:

1. **Stale Pruning** — Removes entries whose `updatedAt` (last write) is older than `pruneStaleAfterDays` days. Recalling an entry does **not** refresh `updatedAt`, so a fact read in every conversation is still pruned if nothing has rewritten it. This is a deterministic operation with zero LLM cost.
2. **Contradiction Detection** — Identifies entries with the same key but different values (e.g., `language=English` from Agent A vs `language=German` from Agent B). Unlike pruning and summarization, detection looks past the firing agent's own entries: every entry is considered for a key the firing agent holds (a disagreement between two *other* agents is not its to report). The log names the key and agents at INFO; the conflicting values are logged at DEBUG only. What happens next is `contradictionResolution` — by default nothing; see [Contradiction resolution](#contradiction-resolution). Matching is by key; LLM-driven semantic detection is future work.
3. **Interaction Summarization** — Contested and superseded entries are held back: consolidating a disputed value would pick a winner after all, and consolidating a superseded one would bring the retired value back. When `summarizeInteractions=true`, compresses multiple related facts into consolidated summaries using the configured LLM. Entries are grouped by the `summarizeGroupBy` strategy (per-category or all together), and each group above `summarizeMinEntries` is distilled toward `summarizeTargetEntries` entries. Safety guarantees: every write target is resolved before anything is written; new entries are inserted before originals are deleted; an original that receives a consolidated entry (the model reused its key) is updated in place and **not** deleted; a key that would overwrite a memory outside the group skips the group untouched; duplicate keys in the answer are merged; a failed insert restores any original it overwrote; an answer that only repeats originals verbatim may drop an original only when it duplicated a kept value (otherwise it merged nothing and the group is skipped); LLM failures or invalid responses preserve the original entries.
4. **Concurrent writes win.** A cycle reads the user's memories, then spends seconds in the LLM call before it writes. Every write it makes is therefore conditional on the memory being exactly as it was read — a compare-and-set on `updatedAt`, one atomic statement on MongoDB and PostgreSQL: a stale entry the conversation rewrote in the meantime is not pruned; a group any of whose originals changed during the LLM call is skipped untouched; an original rewritten after the consolidation was written is kept rather than deleted (the duplicate is reconciled by the next cycle). Each skip is counted as `conflictsSkipped` in the cycle's completion log line and on `eddi.dream.conflicts.skipped`. Earlier releases deleted and overwrote by id, so a fact the user stated during the cycle could be lost.

### Contradiction resolution

The store's upsert identity is `(userId, key, sourceAgentId)` for `self` and `group` entries and `(userId, key)` for `global` ones, so one key can be held by several entries at once — one per agent, plus the shared global row — and they can disagree. Each entry carries an `assessment`:

| Assessment   | Meaning                                                                                                           | Loaded as `{properties.<key>}`?                                                                                                                                                                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACCEPTED`   | The default. Every entry stored before this field existed reads as `ACCEPTED`                                     | Yes                                                                                                                                                                                                              |
| `CONTESTED`  | Another entry for the key holds a different value and neither was chosen                                          | Yes, plus the `contestedMemories` marker below                                                                                                                                                                   |
| `SUPERSEDED` | A newer entry (`supersededBy`) replaced it for every one of its readers. Kept as evidence, never deleted by Dream | No, while the replacement is visible to the reader — it is still loaded if it is the reader's only entry for the key (a recall window that cut the replacement off, say), because losing the fact would be worse |

`userMemoryConfig.dream.contradictionResolution` decides which assessments a cycle writes:

| Value                     | What a cycle does with a disputed key                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep_newest` *(default)* | Nothing: the contradiction is counted (`eddi.dream.contradictions.found`) and logged. Which value an agent sees is the loader's own precedence — the most specific scope (`self`, then `group`, then `global`), then the newest write. The name is historical: Dream chooses nothing. This is exactly what earlier releases did                                                                                                                                       |
| `mark_contested`          | Every entry of the key that this cycle may write is marked `CONTESTED`, and all are kept                                                                                                                                                                                                                                                                                                                                                                              |
| `supersede_older`         | The newest entry wins **only where it reaches every reader of the older one**: a newer `global` entry supersedes anything; a newer `group` entry supersedes an older `group` entry whose groups it includes; a `self` entry supersedes nothing (no other agent can read it). The older entry becomes `SUPERSEDED` with `supersededBy` pointing at the newest. Whatever still disagrees afterwards — including a tie on the newest `updatedAt` — is marked `CONTESTED` |

Rules that hold for every value:

* **Ownership is the pruning rule.** A cycle writes assessments only onto the entries it may maintain: the firing agent's own (`sourceAgentId`) unless `crossAgentMaintenance: true`, and never a `_gdpr_` entry. With the default, agent A's cycle marks A's entry `CONTESTED` and leaves agent B's alone; B's own cycle marks B's.
* **Concurrent writes win.** Every assessment is a compare-and-set on `updatedAt`; one that loses to a conversation's write is skipped and counted in `conflictsSkipped`. Writing an assessment does **not** change `updatedAt` — it is Dream's verdict about the fact, not a new statement of it, so a contested memory still ages out under `pruneStaleAfterDays` and does not jump to the top of a `most_recent` recall.
* **A rewrite resolves the contest.** Any ordinary write of a key — the conversation persisting a changed `longTerm` property, the `rememberFact` tool (even with the same value: re-stating a contested fact is the user confirming it), the REST and MCP upserts, `PUT /propertiesstore/properties/{userId}` — stores it `ACCEPTED`. This is enforced by the stores on every value write, whatever the entry carries: a client that reads a contested entry, edits it and sends the whole body back to `PUT /usermemorystore/memories` gets it stored `ACCEPTED`, `supersededBy` cleared and `conflicted: false` — the `assessment`, `supersededBy` and `conflicted` fields of a written entry are ignored. Only Dream records a verdict. A conversation that rewrites a contested key — a changed `longTerm` property, or a `rememberFact` call, which writes the store directly and leaves the property as it was — also drops it from `contestedMemories` for its remaining turns.
* **Stale verdicts are lifted, whatever the value.** A `CONTESTED` entry whose key no longer disagrees, and a `SUPERSEDED` entry whose replacement was deleted or itself superseded, are set back to `ACCEPTED` by the next cycle (`eddi.dream.contradictions.cleared`) — even under `keep_newest`, so switching back to the default strands no flag.
* **The other agent may still disagree.** Without `crossAgentMaintenance`, the user's correction in agent A's conversation makes A's entry `ACCEPTED`; if agent B still holds the old value, A's next cycle marks A's entry `CONTESTED` again. That is the evidence as it stands, not a bug: only B (or a cross-agent cycle) can retire B's entry.

**How an agent sees a contest.** Contested entries are loaded as properties as usual, and the conversation also gets a conversation-scoped property `contestedMemories` — a map of `key → true`, present only when at least one loaded memory is contested:

```
{#if properties.contestedMemories}
Some things I remember about the user are disputed ({properties.contestedMemories.keys}).
Ask the user to confirm them before relying on them.
{/if}
{#if properties.contestedMemories.preferred_language}
Confirm the user's preferred language before answering in it.
{/if}
```

The competing value is deliberately not exposed — it may be another agent's private `self` memory. The `recallMemories` and `searchMemory` tools mark such lines `(contested: … confirm with the user)` and superseded ones `(superseded by a newer memory)`; an `ACCEPTED` entry reads exactly as before. A memory that is itself named `contestedMemories` keeps its name: the marker is not set and a WARN is logged.

One limit: a property setter that re-sets a contested property to the value it already holds writes nothing (an unchanged `longTerm` property is never rewritten), so it does not resolve the contest. Have the agent call `rememberFact`, or set the value through the REST or MCP surface.

```json
"dream": {
  "enabled": true,
  "detectContradictions": true,
  "contradictionResolution": "mark_contested",
  "crossAgentMaintenance": false
}
```

### Traceable consolidation (`citeSources`)

A consolidated memory replaces its originals — they are deleted once it is written — so a number the model rounded or invented replaces the user's fact for good. With `citeSources: true` each consolidation group is made extractive and checked before anything is written:

```json
"dream": {
  "enabled": true,
  "summarizeInteractions": true,
  "citeSources": true,
  "onValidationFailure": "retry_once"
}
```

* **The request** numbers the group's entries (`"ref": 0`, `1`, …) and asks for a `"sources"` array of refs on every consolidated entry, numbers copied verbatim, and "unclear in source" instead of a guess. Refs are small integers, not the stored ids, so the model never has to copy an ObjectId.
* **The check** (no model) fails an entry that cites no source, cites a ref that does not exist, or states a number in its `value` that none of its cited sources (their key and value) contains verbatim. Numbers are defined as for the [rolling summary](https://docs.labs.ai/agent-configuration/langchain.md#traceable-summaries-citesources): `1,000` matches only `1,000`, `10%` does not match `10`, `-5` does not match `5`. The key is a label and is not checked. Each object of the answer is checked against its own `sources`, before objects that share a key are merged: the merged entry records the union of their sources, but one object cannot borrow another's citations to pass.

**On failure**, `onValidationFailure` decides:

| Value                              | What happens to the group                                                                                                                                                                                                                                                                      | `outcome`                             |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `fallback_to_previous` *(default)* | Nothing is written; the originals stay and the next cycle tries again                                                                                                                                                                                                                          | `fallback`                            |
| `retry_once`                       | One more call with the problems listed. It is bounded like any other consolidation call — refused when `maxCostPerRun`, the legacy `maxSummarizationCalls` or the tenant budget is spent — and its cost is added to the cycle's. If it fails again, throws or is refused, the group falls back | `retried` on success, else `fallback` |
| `keep`                             | The consolidation is written anyway. Out-of-range refs are dropped; an entry left with none records every original of the group                                                                                                                                                                | `kept`                                |

Each checked group is counted on `eddi.summary.citation.checks{source="dream",outcome}`, a passing one as `passed`. The default differs from the rolling summary's on purpose: a rolling summary is a derived view over a conversation that is kept in full, while a consolidation deletes what it read.

**Provenance.** Every entry written by a checked consolidation carries `sourceEntryIds`: the ids of the originals it cited. The originals are deleted afterwards — except one the consolidation overwrote in place (it reused that original's key), whose id is then among them — so these ids identify the facts in logs, backups and the GDPR export rather than pointing at live entries. Any ordinary write of the key (a conversation, `rememberFact`, REST, MCP, a property merge) states the fact anew and clears them. Without `citeSources`, `sourceEntryIds` stays empty and the request, parsing and writes are exactly as before.

### Scheduling a Dream Cycle

Setting `dream.enabled: true` does not start anything on its own — it is the per-agent veto that is checked when a dream schedule fires. Dream runs through the regular cluster-aware schedule machinery, so a cycle only happens if you also create a `ScheduleConfiguration` that targets it:

```json
{
  "name": "nightly-dream",
  "triggerType": "CRON",
  "cronExpression": "0 3 * * *",
  "agentId": "<agentId>",
  "agentVersion": 1,
  "userId": "<userId>",
  "metadata": { "dreamType": "dream_consolidation" }
}
```

Create it with `POST /schedulestore/schedules`. A Dream schedule needs no `message` (it dispatches to `DreamService`, not to a conversation), but it does need a real `userId` — one without is rejected at creation, since the cycle consolidates exactly that user's memories.

`ScheduleFireExecutor` recognises the `dreamType` marker and dispatches to `DreamService` with the schedule's `agentId`, `agentVersion` and `userId`. The cron expression lives on the schedule — `dream.schedule` in the agent config is a documentation-only hint that the engine never reads.

### Metrics

The Dream service exposes Micrometer metrics (Prometheus names at `/q/metrics` replace the dots with underscores, e.g. `eddi_dream_entries_pruned_total`):

| Metric                                 | Type    | Description                                                                                                                                                                                 |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eddi.dream.users.processed`           | Counter | Users processed across all dream cycles                                                                                                                                                     |
| `eddi.dream.entries.pruned`            | Counter | Total entries pruned                                                                                                                                                                        |
| `eddi.dream.contradictions.found`      | Counter | Contradictions detected                                                                                                                                                                     |
| `eddi.dream.contradictions.contested`  | Counter | Entries marked `CONTESTED`                                                                                                                                                                  |
| `eddi.dream.contradictions.superseded` | Counter | Entries marked `SUPERSEDED`                                                                                                                                                                 |
| `eddi.dream.contradictions.cleared`    | Counter | Contested or superseded entries set back to `ACCEPTED` because the disagreement was gone                                                                                                    |
| `eddi.dream.entries.summarized`        | Counter | Entries reduced by LLM consolidation                                                                                                                                                        |
| `eddi.dream.cycles.failed`             | Counter | Cycles that were rejected or ended with an error                                                                                                                                            |
| `eddi.dream.summarization.failed`      | Counter | Consolidation LLM calls that failed                                                                                                                                                         |
| `eddi.dream.conflicts.skipped`         | Counter | Prunes, overwrites, deletes and assessments skipped because the memory was written after the cycle read it — the newer fact is kept                                                         |
| `eddi.dream.duration`                  | Timer   | Duration of dream cycles                                                                                                                                                                    |
| `eddi.summary.citation.checks`         | Counter | Consolidation groups checked under `citeSources`, tagged `source="dream"` and `outcome` (`passed`, `retried`, `kept`, `fallback`); the rolling summary counts under `source="conversation"` |

## Migration from Legacy Properties

In v6, the legacy `IPropertiesStore` interface and the `properties` collection have been **removed**. All user-scoped persistent data now lives in the unified `usermemories` collection.

| Aspect             | Legacy Properties (v5)             | User Memory (v6)                               |
| ------------------ | ---------------------------------- | ---------------------------------------------- |
| **Storage**        | `properties` collection (flat map) | `usermemories` collection (structured entries) |
| **Interface**      | `IPropertiesStore` (deleted in v6) | `IUserMemoryStore`                             |
| **Scoping**        | Per-user only                      | Per-user, per-agent, per-group                 |
| **LLM access**     | Via template variables only        | Direct LLM tool access                         |
| **Querying**       | Key lookup only                    | Key, category, search, visibility filtering    |
| **Administration** | No REST API                        | Full CRUD REST API + MCP tools                 |

### Backward Compatibility

Legacy flat property operations (`readProperties`, `mergeProperties`, `deleteProperties`) continue to work through `IUserMemoryStore` — they operate on `global` visibility entries in the `usermemories` collection. The REST endpoint at `/propertiesstore/properties/{userId}` is preserved.

### Startup Migration (MongoDB only)

On first startup, `PropertiesMigrationService` automatically migrates existing `properties` documents into `usermemories` as `global` entries with `category=legacy`. A key the user already has in `usermemories` keeps its value — it is newer than the frozen v5 data (or the result of an earlier, partial run), so migration never overwrites it. A legacy document without a `userId` cannot be migrated and is skipped (not counted as a failure). Once every key made it across, the old collection is renamed to `properties_migrated_v6` as a safety backup; after a partial failure it stays in place and the next startup retries. The migration is idempotent and skipped if no legacy collection exists.

**Credentials are not migrated.** Long-term memories are loaded into every conversation as `{properties.*}`, so anything copied here reaches template data, prompts and outbound API calls. Two kinds of key stay behind in `properties_migrated_v6`:

* the keys in `eddi.migration.properties.skip-keys` (default `userInfo`). In 5.x, `userInfo` was the caller's per-request identity: a platform bearer token next to names and ids, not a memory;
* any key whose value holds a credential at any depth, judged by the same rules the agent export uses to redact secrets. The check is deliberately cautious: a long, random-looking identifier can be caught too. Its value stays in the backup collection, and an operator can restore it by hand.

Skipped keys are logged by name and count, never by value, and they don't count as failures. Before this rule, the migration copied `userInfo` across. A database that already ran it can be cleaned up with:

```javascript
db.usermemories.deleteMany({ category: "legacy", key: "userInfo" })
```

Once the migration is verified, consider dropping `properties_migrated_v6`, since it keeps the legacy values, credentials included.

> **Note:** PostgreSQL deployments do not need migration — the `properties` table only existed in MongoDB (v5).

## Data Model

Each memory entry contains:

```json
{
  "id": "ObjectId",
  "userId": "user-123",
  "key": "preferred_language",
  "value": "German",
  "category": "preference",
  "visibility": "global",
  "sourceAgentId": "agent-456",
  "groupIds": ["group-1"],
  "sourceConversationId": "conv-789",
  "conflicted": false,
  "assessment": "ACCEPTED",
  "supersededBy": null,
  "sourceEntryIds": [],
  "accessCount": 12,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-29T14:22:00Z",
  "lastWriterAgentId": "agent-789"
}
```

`sourceAgentId` is the agent that created the entry, and a `global` entry keeps it when another agent writes the key. `lastWriterAgentId` is the agent whose write produced the value the entry holds now (here another agent overwrote `agent-456`'s fact), `null` when the user or an admin wrote it. An undo or redo records the conversation's agent, whose value it puts back, and a Dream merge the writer described under `crossAgentMaintenance`. A REST `PUT` stores the `lastWriterAgentId` its body names, and `sourceAgentId` when the body names none. An entry stored before the field existed reads back with its owner as writer. An agent that requires peer verification goes by this field (see [Visibility scopes](#visibility-scopes)).

`assessment` is `ACCEPTED`, `CONTESTED` or `SUPERSEDED` (see [Contradiction resolution](#contradiction-resolution)); `supersededBy` is set only on a `SUPERSEDED` entry. `conflicted` mirrors `assessment == "CONTESTED"` for clients that already read it. All three are read-only for writers: whatever a REST or MCP write sends, the entry is stored `ACCEPTED`. Entries stored before these fields existed read as `ACCEPTED`: MongoDB documents simply lack the fields, and PostgreSQL adds the `assessment` and `superseded_by` columns on startup with `ACCEPTED` as the default for existing rows. `sourceEntryIds` lists the originals a [`citeSources`](#traceable-consolidation-citesources) consolidation built the entry from, and is empty otherwise; it is read-only for writers too — a REST or MCP write stores it empty, and only Dream's consolidation write sets it. PostgreSQL adds the `source_entry_ids` column (JSONB, default `[]`) the same way.
