Skip to main content
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.

​
Methods

MethodPurpose
memory/searchSearch active memory in allowed scopes.
memory/getGet one memory record by id or scoped key.
memory/listList memory records with filters.
memory/rememberStore or update a durable memory record through the service.
memory/forgetTombstone/suppress memory by id or scoped key.
memory/candidates/listList memory candidates and dormant review records.
memory/candidates/getGet one candidate.
memory/candidates/decideApply an approve/reject/expire decision.
memory/candidates/approveApprove a candidate.
memory/candidates/rejectReject a candidate.
memory/candidates/edit_and_approveEdit candidate text and approve it.
memory/candidates/mergeMerge a candidate into an existing memory.
memory/candidates/suppress_similarSuppress 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

EventPayload
memory/changedActive memory was created, updated, superseded, or otherwise changed.
memory/candidate_createdA memory candidate was created.
memory/forgottenOne or more memory ids were forgotten/tombstoned.
Clients should listen for these events if they render memory management screens or cached memory lists.

​
Core DTOs

TypeMeaning
MemoryRecordActive 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.
MemorySearchParamsQuery, categories, scopes, limit, sensitivity policy, and ranking inputs.
MemoryRememberParamsClient-facing direct remember request.
MemoryForgetParamsForget target, reason, dry-run flag, and actor.
MemorySemanticFieldsStructured semantic description used by service-owned write/dedupe.
MemorySemanticWriteParamsInternal/public semantic write contract for extractor and candidate policy paths.
MemoryCandidateProposed 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.

​
Candidate Statuses

Candidate statuses include active review states and dormant states:
StatusMeaning
pendingCandidate exists but has not been decided.
pending_silentCandidate is retained silently for future UX/policy.
ask_on_useCandidate may be surfaced when relevant later.
needs_reviewCandidate needs explicit review.
approvedCandidate was approved into active memory.
rejectedCandidate was rejected.
auto_rejectedCandidate was automatically rejected by policy.
review_disabled_rejectedMiddle-confidence candidate rejected because review routing is disabled.
merged_duplicateCandidate was merged into an existing record/candidate.
expiredCandidate 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.