Memory write lifecycle
Memory, embedding, recall, and similarity endpoints.
The Memory API is the primary interface for reading and writing agent
memory. All write operations respect the mutationsFrozen kill switch — if
enabled, writes return 503. For a typed client wrapper, see the Sdk.
GET /api/memories
Section titled “GET /api/memories”List memories with basic stats. Simple pagination and a type filter only; for
filtered search use POST /api/memory/recall or GET /memory/search.
Requires recall permission.
The list and its stats are scoped to the requesting agent’s read policy, the
same scope recall uses. The agent comes from agentId, the
x-signet-agent-id header, or an agent:<id>:... session key, and falls back
to the credential’s scoped agent, then the daemon’s configured agent
($SIGNET_AGENT_ID, otherwise default), the same fallback memory writes use.
A scoped credential that asks for another agent gets 403.
agentId=all lists every agent’s live memories. It requires admin
permission, which local mode grants. The dashboard and desktop tray use it;
agent-facing clients should send their own agent instead.
Every memory read route resolves the agent the same way and applies the same
read scope in every auth mode: this list, GET /memory/search,
GET /api/memories/most-used, GET /api/memories/curator-slices,
GET /api/memory/timeline, GET /api/memory/review-queue,
GET /api/memory/:id with its history and lineage, GET /api/memory/search,
GET /memory/similar, and GET /api/embeddings. Only the list, the timeline,
and GET /memory/search accept all.
Listed content goes through credential redaction.
GET /api/memory/:id returns the stored content.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 100 | Max records to return, 1–500 |
offset |
integer | 0 | Pagination offset |
type |
string | — | Only memories of this type |
agentId |
string | daemon agent | Agent whose read scope to apply, or all |
Credential redaction
Section titled “Credential redaction”Remembered content is stored as written. When it is projected into a prompt,
recall result, memory list, Dreaming evidence, MEMORY.md, or an MCP tool
response, any detected credential (provider API keys and tokens, private keys,
JWTs, bearer tokens, and values assigned to secret-named keys) is replaced with
[redacted credential]. Nothing is withheld for safety reasons, and the
original content and provenance stay unchanged.
The scan is not a truth judgment and is not a replacement for permissions or agent scoping. A blocked memory can still be inspected by an authorized caller; it is excluded from ordinary recall, reranking, native-source fallback, and Dreaming projections.
Response
{ "memories": [ { "id": "uuid", "content": "User prefers dark mode", "created_at": "2026-02-21T10:00:00.000Z", "who": "claude-code", "importance": 0.8, "tags": "preference,ui", "source_type": "manual", "pinned": 0, "type": "preference", "agent_id": "default" } ], "stats": { "total": 1247, "withEmbeddings": 1200, "critical": 12 }}POST /api/memory/remember
Section titled “POST /api/memory/remember”Create a new memory. Requires remember permission.
Content prefixes are parsed automatically:
critical: <content>— setspinned=true,importance=1.0[tag1,tag2]: <content>— sets tags
Body-level fields override prefix-parsed values.
Request body
{ "content": "User prefers vim keybindings", "type": "preference", "who": "claude-code", "project": "my-project", "importance": 0.9, "tags": "preference,editor", "pinned": false, "sourceType": "manual", "sourceId": "optional-external-id", "sourcePath": "/absolute/or/original/source.md", "runtimePath": "memory/MEMORY.md", "idempotencyKey": "stable-import-key", "createdAt": "2026-02-21T10:00:00.000Z", "occurredAt": "2026-02-20T15:00:00.000Z", "observedAt": "2026-02-21T09:55:00.000Z", "sourceCreatedAt": "2026-02-20T15:05:00.000Z", "validFrom": "2026-02-20T00:00:00.000Z", "validUntil": "2026-03-01T00:00:00.000Z", "reviewAfter": "2026-08-03T00:00:00.000Z", "supersedes": "existing-memory-id", "reason": "newer evidence replaces the old claim", "agentId": "alice", "visibility": "global"}Only content is required.
type is optional. When it is present, the memory is stored with that type,
trimmed of surrounding whitespace. When it is missing or null, the daemon
infers the type from the content (see Memory Types).
Any other value returns 400: a value that is not a string, a blank string, or a
type longer than 64 characters. The type is free text; there is no fixed list
of allowed values. Types are case-sensitive: use decision for the built-in
decision behavior; Decision is a distinct custom label.
When content deduplicates to an existing memory, the stored type is returned
unchanged. Use the modify endpoint to retype an eligible existing memory.
For oversized content split into chunks, every chunk gets the requested type.
When no type is given, the type is inferred for each chunk separately, so
chunks of the same request can end up with different types.
Multi-agent fields:
| Field | Description |
|---|---|
agentId |
Agent that owns this memory. Defaults to the agent in an agent:<id>: session key (x-signet-session-key), then the credential’s scoped agent, then the daemon’s configured agent ($SIGNET_AGENT_ID, otherwise "default"). When credential scope is enforced, naming another agent directly or through the session key gets 403. |
visibility |
"global" (any permitted agent can read), "private" (owner only). Defaults to "global". |
First-seen named agentId values are registered in the agents table with
read_policy set to isolated; existing agent policy rows are preserved.
createdAt is optional and must be a valid ISO timestamp. Use it when the
memory is sourced from an older conversation or imported artifact so structured
currentness and supersession can compare facts by source time instead of ingest
time.
occurredAt, observedAt, sourceCreatedAt, and validFrom/validUntil
attach explicit temporal edges to the memory without duplicating the memory
content. Use them when the memory is saved later than the event, observation,
source creation time, or validity window it describes. Each value must be a
valid ISO timestamp; validUntil must be after validFrom when both are set.
Dreaming claims carry the same occurred and valid facets on their semantic
memories (see Claim time).
reviewAfter is an optional ISO timestamp for a future temporal claim. Dreaming
uses it to surface the memory for review after the deadline instead of assuming
that the planned event occurred.
supersedes is an optional memory id. When set, the named memory is marked
superseded_by = the new id in the same transaction (atomic lineage, no
orphans). The new row becomes the head of a drillable chain; reason is
recorded on the superseded row. A missing or cross-scope supersedes target
fails the whole write. Chain history is readable from any row via
GET /api/memory/:id/lineage, which walks superseded_by links newest-first.
Row-level provenance fields are optional: sourcePath/source_path stores the
original source path, runtimePath/runtime_path stores the runtime-relative
path, and idempotencyKey/idempotency_key stores a stable import key. When an
idempotencyKey is supplied, remember checks it before content-hash dedupe;
retries with the same key return the existing row instead of inserting a
duplicate within the same agentId, visibility, and scope tuple. Importers
may also supply the snake_case names inside a metadata object for
compatibility.
Structured callers may also pass structured.entities, structured.aspects,
and structured.hints. As of the episodic-evidence cutover, a structured
payload is retained as immutable episodic evidence alongside the memory
content but is no longer applied directly to the knowledge graph from the
remember endpoint. The response includes structured: true and
structured_applied: false to signal this explicitly. structured.hints are
still written as prospective recall aids for the saved evidence. Only Dreaming
derives semantic state (entities, aspects, attributes, links) from episodic
evidence through the audited ontology control plane.
All remember saves (plain, chunked, or structured) are immutable episodic
evidence (memory_kind = 'episodic'). They remain inspectable through list
and GET /api/memory/:id; only clean rows are eligible for ordinary recall
or Dreaming evidence through the shared episodic-sources selector.
The remember endpoint no longer performs any direct semantic side effects: it
does not persist structured graph state, does not inline-link entities, and
does not enqueue legacy extraction jobs. Extraction status is none —
Dreaming owns semantic processing.
Response
{ "id": "uuid", "type": "preference", "tags": "preference,editor", "pinned": false, "importance": 0.9, "content": "User prefers vim keybindings", "embedded": true, "entities_linked": 0, "hints_written": 0, "structured": false, "structured_applied": false, "deduped": false}entities_linked is always 0 for remember saves (no direct graph writes).
structured_applied is false even when a structured payload is supplied,
signaling that it was retained as episodic evidence but not applied to the
graph. If a structured payload was supplied, structured is true.
If an identical memory (by sourceId, idempotencyKey, or content hash) already
exists in the relevant scope, deduped: true is returned with the existing
record — no duplicate is created.
POST /api/memory/save
Section titled “POST /api/memory/save”Alias for POST /api/memory/remember. Accepts the same request body and
returns the same response. Requires remember permission.
POST /api/memory/codex-native-note
Section titled “POST /api/memory/codex-native-note”Write an explicit Codex native memory note under the local Codex memory
extension path. Requires remember permission and respects the
mutationsFrozen kill switch.
Request body
{ "content": "Small scoped note to preserve", "title": "Optional title", "tags": "codex,note"}content is required and capped at 8000 characters. title and tags are
optional strings.
Response
{ "ok": true, "path": "/home/user/.codex/memories/extensions/ad_hoc/notes/..."}POST /api/hook/remember
Section titled “POST /api/hook/remember”Alias for POST /api/memory/remember. Used by Claude Code skill
compatibility. Requires remember permission.
GET /api/memory/:id
Section titled “GET /api/memory/:id”Get a single memory by ID. Returns deleted memories only if the query
explicitly requests them; by default, soft-deleted records return 404.
Direct reads are filtered through the same resolved agent read policy used by
recall/search. Pass agentId/agent_id, x-signet-agent-id, or an
x-signet-session-key that resolves to an agent when reading non-default
agent memories; cross-agent or private memories outside that read scope return
404 without provenance fields. A scoped credential that names another agent
gets 403. history and lineage apply the same scope: history for a memory
outside it returns 404, and lineage stops at the first node outside it.
Requires recall permission.
Response
{ "id": "uuid", "content": "User prefers vim keybindings", "type": "preference", "importance": 0.9, "tags": "preference,editor", "pinned": 0, "who": "claude-code", "source_id": "optional-external-id", "source_type": "manual", "source_path": "/absolute/or/original/source.md", "runtime_path": "memory/MEMORY.md", "idempotency_key": "stable-import-key", "sourcePath": "/absolute/or/original/source.md", "runtimePath": "memory/MEMORY.md", "idempotencyKey": "stable-import-key", "project": null, "session_id": null, "confidence": null, "access_count": 3, "last_accessed": "2026-02-21T11:00:00.000Z", "is_deleted": 0, "deleted_at": null, "extraction_status": "done", "embedding_model": "nomic-embed-text", "version": 2, "created_at": "2026-02-21T10:00:00.000Z", "updated_at": "2026-02-21T10:30:00.000Z", "updated_by": "operator"}sourcePath, runtimePath, and idempotencyKey are camelCase aliases for
source_path, runtime_path, and idempotency_key so import provenance written
through POST /api/memory/remember is visible on direct reads.
GET /api/memory/:id/history
Section titled “GET /api/memory/:id/history”Full audit history for a memory in chronological order. Requires recall
permission.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 200 | Max events (cap: 1000) |
Response
{ "memoryId": "uuid", "count": 3, "history": [ { "id": "hist-uuid", "event": "created", "oldContent": null, "newContent": "User prefers vim keybindings", "changedBy": "claude-code", "actorType": "operator", "reason": null, "metadata": null, "createdAt": "2026-02-21T10:00:00.000Z", "sessionId": null, "requestId": null } ]}GET /api/memory/:id/lineage
Section titled “GET /api/memory/:id/lineage”Supersession chain for a memory, newest first. Requires recall permission.
Walks superseded_by links from any row in the chain to the head, so drilling
from an old version surfaces the full v3 → v2 → v1 history.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 50 | Max chain rows (cap: 500) |
Response
{ "memoryId": "old-uuid", "count": 3, "lineage": [ { "id": "newest-uuid", "content": "newest claim", "type": "fact", "importance": 0.9, "version": 3, "createdAt": "...", "updatedAt": "...", "supersededBy": null, "supersededAt": null, "supersededReason": null }, { "id": "middle-uuid", "content": "middle claim", "type": "fact", "importance": 0.8, "version": 2, "createdAt": "...", "updatedAt": "...", "supersededBy": "newest-uuid", "supersededAt": "...", "supersededReason": "newer evidence" }, { "id": "old-uuid", "content": "original claim", "type": "fact", "importance": 0.7, "version": 1, "createdAt": "...", "updatedAt": "...", "supersededBy": "middle-uuid", "supersededAt": "...", "supersededReason": "newer evidence" } ]}Mutation scope
Section titled “Mutation scope”Every route that changes an existing memory by ID (recover, PATCH,
DELETE, POST /api/memory/forget, POST /api/memory/modify, and the
curator tombstone and supersede routes) only touches memories the caller
owns:
- A credential scoped to an agent can change only that agent’s memories, and a credential scoped to a project only that project’s memories. Admin credentials are not restricted.
- A request that names an agent with
agentId/agent_id,x-signet-agent-id, or anagent:<id>:session key can change only that agent’s memories. A scoped credential that names another agent gets403. - A memory outside that scope returns
404with statusnot_found, the same as a memory that does not exist. Batch routes leave it out of the candidates (forget) or report it asnot_found(modify).
In local mode a request that names no agent is not restricted.
POST /api/memory/:id/recover
Section titled “POST /api/memory/:id/recover”Restore a soft-deleted memory. The recovery window is 30 days from deletion.
Requires recover permission. See Mutation scope.
Request body
{ "reason": "Accidentally deleted", "if_version": 3}reason is required. if_version is optional — if provided, the operation
is rejected with 409 if the current version does not match (optimistic
concurrency).
Response
{ "id": "uuid", "status": "recovered", "currentVersion": 3, "newVersion": 4, "retentionDays": 30}Possible status values and their HTTP codes:
| Status | Code | Meaning |
|---|---|---|
recovered |
200 | Success |
not_found |
404 | Memory does not exist |
not_deleted |
409 | Memory is not deleted |
retention_expired |
409 | Outside 30-day recovery window |
version_conflict |
409 | if_version mismatch |
PATCH /api/memory/:id
Section titled “PATCH /api/memory/:id”Update a memory’s metadata fields. At least one of content, type, tags,
importance, or pinned must be provided. Requires modify permission.
Rate-limited to 60/min.
See Mutation scope for which memories a request can change.
Episodic evidence immutability: memories saved via remember (memory_kind = 'episodic') are immutable evidence. content and type cannot be changed on
an episodic memory — attempts return episodic_content_immutable (409).
Metadata fields (tags, importance, pinned) remain editable so curators can
re-rank or re-label evidence without altering the originally recorded content.
To correct episodic evidence, save a new memory and optionally supersede the old
one.
Request body
{ "content": "Updated content", "type": "fact", "tags": ["updated", "fact"], "importance": 0.7, "pinned": false, "reason": "Correcting outdated information", "if_version": 2, "changed_by": "operator"}reason is required. if_version is optional optimistic concurrency guard.
type follows the same rules as on remember: a non-blank string of at most 64
characters, otherwise 400.
tags may be a string (comma-separated), an array of strings, or null to
clear tags.
Response
{ "id": "uuid", "status": "updated", "currentVersion": 2, "newVersion": 3, "contentChanged": true, "embedded": true}Possible status values and their HTTP codes:
| Status | Code | Meaning |
|---|---|---|
updated |
200 | Success |
no_changes |
200 | Patch produced no diff |
not_found |
404 | Memory does not exist |
deleted |
409 | Cannot modify a deleted memory |
version_conflict |
409 | if_version mismatch |
duplicate_content_hash |
409 | New content matches an existing memory |
episodic_content_immutable |
409 | Episodic evidence content/type protected |
DELETE /api/memory/:id
Section titled “DELETE /api/memory/:id”Soft-delete a memory. Deleted memories can be recovered within 30 days.
Requires forget permission. Rate-limited to 30/min.
See Mutation scope for which memories a request can
delete. Pinned memories require force: true. Autonomous agents (pipeline/agent actor type)
cannot force-delete pinned memories.
Request body (or query parameters)
{ "reason": "No longer relevant", "force": false, "if_version": 3}reason is required, either in the body or as ?reason=... query parameter.
force defaults to false. if_version is optional.
Response
{ "id": "uuid", "status": "deleted", "currentVersion": 3, "newVersion": 4}Possible status values and their HTTP codes:
| Status | Code | Meaning |
|---|---|---|
deleted |
200 | Success |
not_found |
404 | Memory does not exist |
already_deleted |
409 | Memory is already deleted |
version_conflict |
409 | if_version mismatch |
pinned_requires_force |
409 | Pinned memory requires force: true |
autonomous_force_denied |
403 | Autonomous agents cannot force-delete |
POST /api/memory/forget
Section titled “POST /api/memory/forget”Batch forget with preview/execute workflow. Requires forget permission.
Rate-limited to 5/min (batch forget limiter). Candidates are limited to the
mutation scope.
Requires at least one of: query, ids, or a filter field (type, tags,
who, source_type, since, until). The batch size cap is 200.
For large operations (>25 candidates), the execute mode requires a
confirm_token obtained from a prior preview call.
Request body — preview mode
{ "mode": "preview", "query": "outdated preferences", "type": "preference", "tags": "old", "who": "claude-code", "source_type": "manual", "since": "2025-01-01T00:00:00Z", "until": "2026-01-01T00:00:00Z", "limit": 20}Or target specific IDs:
{ "mode": "preview", "ids": ["uuid1", "uuid2"]}Preview response
{ "mode": "preview", "count": 3, "requiresConfirm": false, "confirmToken": "abc123...", "candidates": [ { "id": "uuid1", "score": 0.85, "pinned": false, "version": 2 } ]}Request body — execute mode
{ "mode": "execute", "query": "outdated preferences", "reason": "Cleaning up stale data", "force": false, "confirm_token": "abc123..."}reason is required in execute mode. confirm_token is required when
requiresConfirm was true in the preview.
Execute response
{ "mode": "execute", "requested": 3, "deleted": 3, "results": [ { "id": "uuid1", "status": "deleted", "currentVersion": 2, "newVersion": 3 } ]}POST /api/memory/modify
Section titled “POST /api/memory/modify”Batch update multiple memories in a single request. Requires modify
permission. Rate-limited to 60/min. Maximum 200 patches per request. A patch
for a memory outside the mutation scope reports
not_found.
Request body
{ "reason": "Bulk correction", "changed_by": "operator", "patches": [ { "id": "uuid1", "content": "Updated content", "reason": "Per-patch reason override", "if_version": 2 }, { "id": "uuid2", "tags": ["updated"], "importance": 0.6 } ]}Top-level reason and changed_by are defaults applied to all patches. Each
patch can override reason individually. if_version per patch is optional.
Response
{ "total": 2, "updated": 2, "results": [ { "id": "uuid1", "status": "updated", "currentVersion": 2, "newVersion": 3, "contentChanged": true, "embedded": true }, { "id": "uuid2", "status": "updated", "currentVersion": 1, "newVersion": 2, "contentChanged": false } ]}Individual patch items that fail validation return status: "invalid_request"
with an error field. The batch continues — partial success is possible.

