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

# Memory API

> JSON-RPC methods, notifications, and DTOs for durable agent memory.

Memory protocol methods let clients inspect and manage durable agent memory directly. The agent can also use model-visible memory tools during agent-mode turns, but those tools are separate from the client JSON-RPC protocol.

All memory methods are served by the gateway and routed through `MemoryService`. Clients should treat the service response as authoritative even when the underlying capsule backend has stale search data.

This page is about durable memory, not thread episodic context. Durable memory is where Pioneer stores long-lived facts and decisions. Thread episodic context is the searchable conversation-history layer; it is controlled through gateway settings and used by the agent recall path, but it is not exposed as the `memory/*` JSON-RPC API.

## Methods

| Method                               | Purpose                                                      |
| ------------------------------------ | ------------------------------------------------------------ |
| `memory/search`                      | Search active memory in allowed scopes.                      |
| `memory/get`                         | Get one memory record by id or scoped key.                   |
| `memory/list`                        | List memory records with filters.                            |
| `memory/remember`                    | Store or update a durable memory record through the service. |
| `memory/forget`                      | Tombstone/suppress memory by id or scoped key.               |
| `memory/candidates/list`             | List memory candidates and dormant review records.           |
| `memory/candidates/get`              | Get one candidate.                                           |
| `memory/candidates/decide`           | Apply an approve/reject/expire decision.                     |
| `memory/candidates/approve`          | Approve a candidate.                                         |
| `memory/candidates/reject`           | Reject a candidate.                                          |
| `memory/candidates/edit_and_approve` | Edit candidate text and approve it.                          |
| `memory/candidates/merge`            | Merge a candidate into an existing memory.                   |
| `memory/candidates/suppress_similar` | Suppress a candidate and similar future suggestions.         |

Candidate review methods exist even though the default product path currently rejects/suppresses middle-confidence candidates instead of surfacing a review queue to users.

## Notifications

| Event                      | Payload                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| `memory/changed`           | Active memory was created, updated, superseded, or otherwise changed. |
| `memory/candidate_created` | A memory candidate was created.                                       |
| `memory/forgotten`         | One or more memory ids were forgotten/tombstoned.                     |

Clients should listen for these events if they render memory management screens or cached memory lists.

Thread episodic vector indexing has a separate gateway notification, `gateway/thread_episodic/vector_refill/status_changed`. It reports workspace-scoped refill progress such as running, complete, or failed. Clients that show semantic-search readiness should use this event together with settings and the memory/embedding model status; it is not a durable-memory mutation event.

## Core dtos

| Type                        | Meaning                                                                                                                      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `MemoryRecord`              | Active or historical durable memory row with scope, category, key, content, status, timestamps, sensitivity, and provenance. |
| `MemoryScope`               | `{ kind, key }` pair such as user, workspace, agent, thread, or task.                                                        |
| `MemorySearchParams`        | Query, categories, scopes, limit, sensitivity policy, and ranking inputs.                                                    |
| `MemoryRememberParams`      | Client-facing direct remember request.                                                                                       |
| `MemoryForgetParams`        | Forget target, reason, dry-run flag, and actor.                                                                              |
| `MemorySemanticFields`      | Structured semantic description used by service-owned write/dedupe.                                                          |
| `MemorySemanticWriteParams` | Internal/public semantic write contract for extractor and candidate policy paths.                                            |
| `MemoryCandidate`           | Proposed memory plus policy score, status, evidence, and decision metadata.                                                  |

Generated schemas are exported under `schemas/` in the repository. The protocol source is `crates/protocol/src/memory.rs`.

## Durable memory vs thread context

The protocol intentionally keeps these surfaces separate:

| Surface                 | Protocol shape                                                                                       | Product meaning                                                                     |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Durable memory          | `memory/search`, `memory/list`, `memory/get`, `memory/remember`, `memory/forget`, candidate methods. | Stable user/project/agent facts that can survive across turns and threads.          |
| Thread episodic context | Gateway settings plus internal recall hooks.                                                         | Searchable old conversation snippets used during prompt construction.               |
| Thread event replay     | `thread/history`, `thread/timeline/page`, `turn/items`, `turn/work/page`, `turn/work/items/get`.     | Exact durable and semantic timeline data for clients to render or recover UI state. |

Do not use `memory/remember` to store every thread message. That would pollute durable memory and make forgetting/ranking much harder. If a client wants to display transcript history, use thread and turn APIs. If the agent needs older discussion as context, the thread episodic layer handles that through bounded recall.

## Candidate statuses

Candidate statuses include active review states and dormant states:

| Status                     | Meaning                                                                  |
| -------------------------- | ------------------------------------------------------------------------ |
| `pending`                  | Candidate exists but has not been decided.                               |
| `pending_silent`           | Candidate is retained silently for future UX/policy.                     |
| `ask_on_use`               | Candidate may be surfaced when relevant later.                           |
| `needs_review`             | Candidate needs explicit review.                                         |
| `approved`                 | Candidate was approved into active memory.                               |
| `rejected`                 | Candidate was rejected.                                                  |
| `auto_rejected`            | Candidate was automatically rejected by policy.                          |
| `review_disabled_rejected` | Middle-confidence candidate rejected because review routing is disabled. |
| `merged_duplicate`         | Candidate was merged into an existing record/candidate.                  |
| `expired`                  | Candidate expired.                                                       |

The default runtime does not currently use `pending_silent`, `ask_on_use`, or `needs_review` for user-facing review.

## Semantic write contract

Semantic writes are used by internal extraction and future advanced clients. They include:

* semantic fields: intent, explicitness, category, subject, attribute, scope hint, durability, sensitivity, certainty;
* normalized content and optional value;
* evidence with source thread/turn/item/ref and quote/span;
* provenance actor;
* confidence and importance;
* disposition such as `route_to_candidate_policy`.

Even when a caller provides semantic fields, the service still owns canonical key generation, duplicate detection, scoring, and final state.

## Related pages

* [Desktop Memory](/desktop/memory) explains user-facing behavior.
* [Memory Architecture](/architecture/memory) explains the service and storage model.
* [Thread Episodic Context](/architecture/thread-episodic-context) explains searchable conversation-history recall.
* [Protocol Introduction](/protocol/introduction) explains the JSON-RPC envelope.