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

# Memory

> Memory search, read, save, edit, and archive.

**Memories** are the day-to-day recall layer (facts, events, how-tos) with a bi-temporal validity model: a memory can be superseded by a newer one while the old one is kept for provenance. Fields: title, intro, markdown body, category, importance (1–10, default 3), tags, `memory_type` (`episodic` = event/run · `semantic` = fact · `procedural` = how-to) and a scope layer (`user` | `department` | `global` | `provider`).

**Routing rule:** memories for conceptual recall; `data_query` for exact numbers; `agent_search_runs` for "what did I do last time".

***

## `memory_search`

Search memories (your own user layer + shared department/global ones). Lean rows; fetch the full body with `memory_get`. Returns only currently-valid memories by default.

| Name                  | Type    | Required | Description                                             |
| --------------------- | ------- | -------- | ------------------------------------------------------- |
| `search`              | string  | no       | Free-text term, case-insensitive over title/intro       |
| `category`            | string  | no       | Exact category filter                                   |
| `limit`               | number  | no       | Max rows (default 25, max 200)                          |
| `memory_type`         | string  | no       | `episodic` \| `semantic` \| `procedural`                |
| `include_invalidated` | boolean | no       | Include superseded/invalidated memories (default false) |

**Returns:** `{ memories: [...], count }`. Each row: `id, title, intro, category, category_id, scope, importance, tags, source, user_id, department_id, created_at, updated_at, memory_type, valid_at, invalid_at, source_type, retrieval_class` (no body).

**Permissions:** read; rights-filtered per user.

```json theme={null}
{ "method": "tools/call", "params": { "name": "memory_search", "arguments": { "search": "quarterly targets", "memory_type": "semantic" } } }
```

## `memory_get`

One memory **with full body** — only if readable for this user.

| Name | Type   | Required | Description |
| ---- | ------ | -------- | ----------- |
| `id` | string | yes      | Memory uuid |

**Returns:** `{ memory }` — the full entry: all search columns plus `body_markdown, confidence, needs_review, supersedes, source_id, source_uri, failure_count`. Not readable/found → `{ error: "Memory not found" }`.

**Permissions:** read; rights-filtered.

```json theme={null}
{ "method": "tools/call", "params": { "name": "memory_get", "arguments": { "id": "<uuid>" } } }
```

## `memory_save`

Save a memory. `scope=user` (default) writes directly to **your** memory layer. Shared scopes (`department`/`global`): a Company-Admin writes directly, and so does a member of the named department (audited, status `saved`); any other shared write becomes a governance candidate (status `pending_governance`). `scope=provider` writes directly and requires Provider-Admin.

| Name            | Type      | Required             | Description                                                                                                                                                        |
| --------------- | --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`         | string    | yes                  | Memory title                                                                                                                                                       |
| `intro`         | string    | no                   | Short summary (defaults to the title)                                                                                                                              |
| `body_markdown` | string    | no                   | Full body                                                                                                                                                          |
| `category`      | string    | no                   | Category (see `category_list {entity:"memory"}`)                                                                                                                   |
| `importance`    | number    | no                   | 1–10 (default 3); out-of-range values are clamped                                                                                                                  |
| `tags`          | string\[] | no                   | Topic tags                                                                                                                                                         |
| `scope`         | string    | no                   | `user` (default) \| `department` \| `global` \| `provider`                                                                                                         |
| `department_id` | string    | for department scope | Membership makes the write direct instead of a governance candidate                                                                                                |
| `memory_type`   | string    | no                   | `episodic` \| `semantic` \| `procedural`                                                                                                                           |
| `supersedes`    | string    | no                   | Id of a memory this one replaces — the old one is invalidated (kept for provenance), not overwritten. Only a memory in the layer you are writing to can be retired |
| `dry_run`       | boolean   | no                   | Validate + return the would-be effect without writing                                                                                                              |

**Returns:** direct write → `{ status:"saved", layer, memory_id, audit }`. Governance-routed shared write → `{ status:"pending_governance", candidate_id, note, audit }`. `dry_run:true` → `{ dry_run:true, valid:true, would: { action, target_id:null, summary, changes: {<field>:{from,to}} }, note }` — nothing written.

**Permissions:** write; role/scope rules as above.

```json theme={null}
{ "method": "tools/call", "params": { "name": "memory_save", "arguments": {
  "title": "Preferred report format",
  "body_markdown": "Pat wants weekly reports as one-page bullet summaries.",
  "memory_type": "procedural",
  "importance": 6
} } }
```

## `memory_update`

Edit an existing memory **in place by id** (the by-id counterpart to `memory_save`, which creates). Patchable: title, intro, body\_markdown, category, importance, tags, memory\_type. Pre-edit state is snapshotted (versioned, revertible); the row's version is bumped under an optimistic lock. To **replace** a fact while keeping provenance use `memory_save` with `supersedes`; to **hide** a memory use `memory_archive`.

| Name                              | Type      | Required | Description                              |
| --------------------------------- | --------- | -------- | ---------------------------------------- |
| `id`                              | string    | yes      | Memory uuid                              |
| `title`, `intro`, `body_markdown` | string    | no       | Content fields                           |
| `category`                        | string    | no       | Category                                 |
| `importance`                      | number    | no       | Importance                               |
| `tags`                            | string\[] | no       | Tags                                     |
| `memory_type`                     | string    | no       | `episodic` \| `semantic` \| `procedural` |

**Returns:** `{ status:"updated", id, version, updated, note, audit }` — `version` is the bumped row version, `updated` lists the patched field names. A concurrent edit returns `{ error: "Edit conflict …" }`.

**Permissions:** write; your **own** user-layer memory directly; editing a shared department/global memory (or one owned by another user) requires **Company-Admin**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "memory_update", "arguments": {
  "id": "<uuid>", "importance": 5, "tags": ["reporting", "preferences"]
} } }
```

## `memory_archive`

Archive a memory (soft + reversible) — hides it from normal recall without deleting; pass `unarchive:true` to restore. Pre-archive state is snapshotted.

| Name        | Type    | Required | Description                |
| ----------- | ------- | -------- | -------------------------- |
| `id`        | string  | yes      | Memory uuid                |
| `unarchive` | boolean | no       | Restore an archived memory |

**Returns:** `{ status:"archived"|"unarchived", id, archived_at, note, audit }` — `archived_at` is the new timestamp (or `null` on unarchive).

**Permissions:** write; own user-layer memory directly; shared memories require **Company-Admin**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "memory_archive", "arguments": { "id": "<uuid>" } } }
```