Memory API

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.

Desktop Memory explains user-facing behavior.
Memory Architecture explains the service and storage model.
Thread Episodic Context explains searchable conversation-history recall.
Protocol Introduction explains the JSON-RPC envelope.

Introduction

Workspace & Threads

Features

Methods

Notifications

Core dtos

Durable memory vs thread context

Candidate statuses

Semantic write contract

​Methods

​Notifications

​Core dtos

​Durable memory vs thread context

​Candidate statuses

​Semantic write contract

​Related pages

Methods

Notifications

Core dtos

Durable memory vs thread context

Candidate statuses

Semantic write contract

Related pages