Skip to content

Knowledge and ontology API

Knowledge navigation, ontology proposal, dreaming, and checkpoint endpoints.

Back to HTTP API overview.

Signet exposes the structured memory graph as a navigable hierarchy for agents. Search discovers unknown paths; navigation inspects known paths without loading the full constellation graph.

Entity -> Aspect -> Group -> ClaimKey -> Attributes

The house/filesystem analogy is intentional: entities are houses or top-level folders, aspects are rooms, groups are dressers, claim keys are drawers, and attributes are notes inside those drawers.

All routes accept optional agent_id and default to default.

List entities with structural counts. Query parameters: q, type, limit, offset.

Resolve one entity by name.

/api/knowledge/navigation/entity?name=Nicholai

Return a compact entity outline for agent browsing. The tree includes aspects, groups, claim slots, counts, and active previews so agents can decide where to drill next without loading the full constellation graph. Query parameters: entity, depth, max_aspects, max_groups, max_claims, and max_total_claims (default 1000, maximum 10000). max_claims caps previews per group. max_total_claims caps claim summaries across the whole tree; previews are allocated across groups by claim rank so one large group cannot consume the entire budget. Groups with omitted claims return claimsHasMore: true.

This budget limits only claims embedded in the tree. It does not change search results or claim-list pages. Use GET /api/knowledge/navigation/claims to read remaining claims for a group.

Depth controls how far the outline expands: 1 returns aspects, 2 returns aspects and groups, and 3 returns aspects, groups, and claim slots.

/api/knowledge/navigation/tree?entity=Nicholai&depth=3

List aspects for an entity.

/api/knowledge/navigation/aspects?entity=Nicholai

List groups under an entity aspect. Attributes without group_key appear under general for backward compatibility.

/api/knowledge/navigation/groups?entity=Nicholai&aspect=food

List claim slots under an entity/aspect/group path. Query parameters: entity, aspect, group, limit, and offset. The default page size is 50, the maximum is 200, and negative offsets are treated as 0; larger offsets are clamped to JavaScript’s maximum safe integer. The response includes limit, offset, and hasMore; when hasMore is true, request the next page with offset increased by the number of returned items.

/api/knowledge/navigation/claims?entity=Nicholai&aspect=food&group=restaurants&limit=50&offset=0

List attributes under an entity/aspect/group/claim path. Defaults to status=active; pass status=all to include superseded history. Query parameters: entity, aspect, group, claim, status, kind, limit, offset.

/api/knowledge/navigation/attributes?entity=Nicholai&aspect=food&group=restaurants&claim=favorite_restaurant

CLI equivalents:

Terminal window
signet knowledge tree Nicholai
signet knowledge tree Nicholai --max-total-claims 1000
signet knowledge entities --query Nicholai
signet knowledge entity Nicholai
signet knowledge aspects Nicholai
signet knowledge groups Nicholai food
signet knowledge claims Nicholai food restaurants --limit 50 --offset 0
signet knowledge attributes Nicholai food restaurants favorite_restaurant
signet knowledge attributes Nicholai food restaurants favorite_restaurant --status all
signet knowledge hygiene

Return the bounded graph overlay used by the dashboard Ontology constellation. Query parameters: agent_id, limit, max_aspects_per_entity, max_attributes_per_aspect, and dependency_limit. When agent_id is omitted, the daemon uses the configured daemon agent ID (SIGNET_AGENT_ID, or default). The read includes the requested agent plus agents whose read_policy is shared, and clamps limits so dashboard navigation cannot load the entire knowledge graph into one read response. agentId is accepted as an alias for agent_id.

agent_id=all returns every agent’s graph in one view and requires admin permission outside local mode. The entity limit then applies across all agents, and metadata still describes the configured daemon agent. Every entity carries its owning agentId. The dashboard graph opens on all agents, colors each agent’s entities, rings their aspects, claims, and evidence in the same color when more than one agent is shown, and offers a picker to show one agent.

The dashboard entity limit is capped at 300, matching the server limit. The 3D view also renders no more than 5,000 nodes at once and labels the view when that display cap is reached; this is a client rendering limit, not a claim that the returned graph is complete.

The route probes the Dreaming episodic backlog using the configured token threshold and tokenizes at most 50 entries (with one additional source row as a lookahead). The probe considers only sources still waiting for Dreaming, so already delivered or reviewed sources do not use up its 50 slots. In metadata.dreaming, episodicTokensPending is an exact number only when episodicBacklogProbe.kind is exact; it is null for a threshold result or an incomplete scan. The probe exposes its status, not a partial token count. The dashboard labels incomplete backlog counts rather than displaying them as exact.

Defaults: limit=150, max_aspects_per_entity=6, max_attributes_per_aspect=4, and dependency_limit=500.

Return a report-only graph hygiene scan. Query parameters: agent_id, limit, and memory_limit.

The response includes suspicious entities, duplicate canonical entity groups, attribute rows missing group_key or claim_key, attributes without source memories, and safe mention-link candidates where an existing entity name appears in a memory that is not yet linked. This endpoint does not mutate graph data.

MCP exposes the same report as knowledge_hygiene_report.

Entity aliases are reviewed ontology metadata used by prompt-submit entity detection and navigation tooling. They do not create duplicate entities. Active aliases are matched as exact normalized phrases and resolve back to the canonical entity current view.

List aliases for an entity id. Query parameters: agent_id and status. status may be active, archived, or all; it defaults to active.

/api/ontology/entities/entity_signet/aliases?agent_id=ant&status=all

Create an active alias for an entity id. Body parameters: alias, confidence, and source. confidence is clamped to 0..1 and defaults to 1.0.

{
"alias": "SignetAI",
"confidence": 0.95,
"source": "operator"
}

DELETE /api/ontology/entities/:id/aliases/:aliasId

Section titled “DELETE /api/ontology/entities/:id/aliases/:aliasId”

Archive an alias. Archived aliases are retained for inspection but are ignored by prompt-submit entity matching.

CLI equivalents:

Terminal window
signet ontology entity alias list entity_signet --status all
signet ontology entity alias add entity_signet SignetAI --confidence 0.95 --source operator
signet ontology entity alias archive entity_signet alias_123

Ontology maintenance writes reviewable proposals before mutating semantic graph state. Read routes require recall; mutation routes require modify. All routes accept optional agent_id.

List proposal records. Query parameters: status, operation, limit, offset.

Return one ontology proposal by id, scoped to the resolved agent_id. Returns 404 when the proposal does not exist in that agent scope. Use this before apply/reject flows when an operator needs to inspect the exact operation, payload, rationale, risk, status, source provenance, and evidence that will be promoted or rejected.

/api/ontology/proposals/prop_123?agent_id=ant

List pending add_claim_value proposal conflicts grouped by claim slot. Query parameters: agent_id and limit. Each conflict group includes the entity, aspect, group, claim key, competing values, and proposal ids so operators can review contradictory pending proposals before consolidation or apply.

/api/ontology/proposals/conflicts?agent_id=ant&limit=100

List persisted contradiction observations between competing applied claim values. The route is recall-authorized and always scoped to the resolved agent_id. It defaults to status=active; pass status=resolved or status=all to inspect resolved history. Optional filters are entity, entity_id, aspect_id, group, claim, source_id, limit, and offset. The response contains both claim ids and content, each side’s confidence, scope/visibility, source provenance, evidence references, detector, and resolution metadata.

/api/ontology/contradictions?agent_id=ant&entity=Signet&status=all

The initial persisted detector is deterministic and lexical only. An active row means both claim rows are still active in the same slot and continue to match the guard; it is not a third truth value and does not choose between sources. Source removal retains the contradiction snapshot and marks it resolved so callers can answer that evidence conflicted without reading a deleted claim row.

Read one contradiction observation by id in the resolved agent scope. Returns 404 when the id belongs to another agent or does not exist.

CLI equivalent:

Terminal window
signet ontology contradictions --agent ant --status all
signet ontology contradictions --entity Signet --group architecture --claim current_value

Resolve a proposal’s evidence references against session transcripts and indexed memory artifacts. The endpoint never reads arbitrary filesystem paths.

Resolve evidence for already-applied claim values from stored attribute provenance. Applied rows include the applying proposal id and copied proposal evidence when the value was promoted through the proposal loop, so this endpoint returns exact proposal lineage before broader source fallback evidence. Query parameters: entity, aspect, group, claim, status, kind, limit, offset.

/api/ontology/claims/evidence?entity=Signet&aspect=architecture&group=ontology&claim=proposal_loop

Return one bounded, authorized claim trace over the existing ontology versions, linked epistemic assertions, proposal evidence, episodic sources, and derived_memory_sources reverse lineage. This endpoint is read-only and does not create a second provenance store or widen cross-agent recall.

Required query parameters are entity, aspect, group, and claim. Optional parameters are kind (attribute or constraint), version_limit (1–50, default 20), premise_limit (1–100, default 50), reverse_limit (1–100, default 50), max_depth (0–3, default 3), agent_id, and session_key.

The resolved agent follows the normal scoped-agent/recall permission path. Project-scoped tokens can only inspect linked claim memories, premises, and reverse dependents in their project. A supplied session key may also be sent as x-signet-session-key; conflicting values are rejected, and remote calls must bind the session to the resolved agent.

Premises must resolve to an existing same-agent canonical episodic source (memory, artifact, transcript, or summary). When a premise includes an exact quote, the quote must occur in the immutable source content. Fabricated or mismatched references return 409; cross-agent, cross-project, or cross-session references return 403. Session-scoped traces fail closed when the source session cannot be proven. Deleted, superseded, stale, and incomplete source records are reported as invalidated or unverified and are never returned as verified evidence.

The response includes current, versions, competing, assertions, premises, reverse, authorization, integrity, traversal, and latencyMs. versions, premises, and reverse each expose their bounded items and truncation state. integrity.status is verified, unverified, or invalidated so consumers cannot silently treat an old explanation as current truth.

CLI and MCP equivalents:

Terminal window
signet ontology explain-claim Signet architecture ontology proposal_loop
signet ontology explain-claim Signet architecture ontology proposal_loop --session-key session-123 --json

MCP clients call signet_explain_claim with the same selectors and bounds.

Resolve evidence for an already-applied ontology link from stored dependency provenance. Links applied through proposals include the applying proposal id and copied proposal evidence before broader source fallback evidence.

List source-attributed epistemic assertions. Assertions record who claimed, believed, observed, decided, preferred, denied, or questioned something about an entity without promoting that statement into current ontology truth. Query parameters: agent_id, observer_id, entity, entity_id, predicate, status, speaker, source_kind, source_id, query, limit, and offset.

observer_id is the explicit observer-scoped projection for directional reads. In the current agent-only model it must match the authorized agent_id; arbitrary peer observer identities are rejected. Omitting it preserves the existing agent-scoped query behavior.

Valid predicates are claims, believes, observed, decided, prefers, denies, and questions. Valid statuses are active, archived, superseded, and all for list reads.

/api/ontology/assertions?entity=Signet&observer_id=ant&predicate=believes&speaker=Nicholai

Return one epistemic assertion by id, scoped to the resolved agent_id. The optional observer_id query parameter must match that authorized agent scope. Returns 404 when the assertion does not exist in that agent scope.

/api/ontology/assertions/assertion_123?agent_id=ant&observer_id=ant

Create a source-attributed epistemic assertion. Body parameters: agent_id, observer_id, entity or entity_id, predicate, content, speaker, asserted_at, confidence, evidence, source_kind, source_id, source_path, source_root, claim_attribute_id, and created_by.

observer_id is optional and must match the authorized agent_id. It records the same agent-only observer projection returned by assertion queries; it does not authorize writing on behalf of another agent.

Every assertion must include either structured evidence or source provenance fields. If claim_attribute_id is supplied, the referenced applied claim value must be active and belong to the same agent and subject entity.

POST /api/ontology/assertions/:id/link-claim

Section titled “POST /api/ontology/assertions/:id/link-claim”

Link an existing assertion to an applied claim attribute. Body parameters: agent_id and attribute_id. The daemon rejects cross-agent and cross-entity links, and it only accepts active claim attribute rows.

Archive an assertion without deleting evidence. Body parameters: agent_id, actor, and reason.

POST /api/ontology/assertions/:id/supersede

Section titled “POST /api/ontology/assertions/:id/supersede”

Create a replacement assertion and mark the old assertion superseded. Body parameters match assertion creation plus agent_id. Omitting predicate preserves the old assertion predicate; pass a predicate only when the epistemic meaning is intentionally changing. Omitting source fields inherits source provenance from the old assertion, but replacement content is still required. Supersede keeps the old subject entity; use a new assertion when the subject entity changes.

CLI equivalents:

Terminal window
signet ontology assertions --entity Signet --predicate believes --speaker Nicholai
signet ontology assertion create --entity Signet --predicate believes --content "Signet should model attributed beliefs." --source-kind transcript
signet ontology assertion show <assertion-id>
signet ontology assertion link-claim <assertion-id> --attribute-id <claim-attribute-id>
signet ontology assertion archive <assertion-id> --reason "superseded by newer evidence"
signet ontology assertion supersede <assertion-id> --content "Updated attributed belief." --source-kind transcript
signet ontology assertion import --file assertions.json

Extract candidate ontology proposals and source-attributed assertions from an agent-scoped transcript or memory artifact. Body parameters: from, agent_id, write_proposals, write_assertions, created_by, limit, use_provider, provider_timeout_ms, and provider_max_tokens. from accepts refs such as transcript:<id>, artifact:<source_path>, or source:<source_path>.

The route dry-runs by default. It writes pending proposals only when write_proposals is true and writes epistemic assertions only when write_assertions is true. If both write flags are set, proposal and assertion inserts share one transaction and roll back together on invalid extracted items. When use_provider is true, the route uses the configured memory_extraction inference workload and falls back to deterministic extraction if no valid provider proposals are returned. Provider-returned questions are surfaced in the response for review; this route does not persist first-class question objects yet.

Consolidate pending ontology proposals into higher-confidence pending proposals. Body parameters: agent_id, status, limit, write_proposals, created_by, use_provider, provider_timeout_ms, and provider_max_tokens. The route dry-runs by default. Provider-backed consolidation uses the configured memory_extraction inference workload and never mutates ontology state directly; it writes only pending proposals when write_proposals is true.

Create one pending ontology proposal.

Create multiple pending proposals atomically.

Apply one pending proposal through its explicit operation handler.

Reject one pending proposal without mutating graph state.

POST /api/ontology/proposals/repair/duplicates

Section titled “POST /api/ontology/proposals/repair/duplicates”

Detect duplicate same-agent entities and optionally write merge proposals.

Dreaming is a periodic knowledge-graph consolidation process that uses a smart model to merge, prune, and enrich the entity graph.

Each pass type runs under a policy prompt: hygiene for incremental-hygiene passes, content for incremental-content passes, and combined for incremental and compact passes. Signet ships a default policy for each. To replace one, set it under memory.dreaming.policies in agent.yaml, or edit it under Settings → Advanced → Dreaming in the dashboard:

memory:
dreaming:
policies:
content: |
File claims only for decisions and shipped changes.
  • A configured policy replaces the default for its pass type. Pass types you do not set keep the default.
  • A blank value keeps the default. A value that is not text, or is longer than 64,000 characters, keeps the default. An unknown pass type key is ignored. The daemon logs a warning for each and reports it in config.policyProblems from GET /api/dream/status, which the dashboard shows next to the policy.
  • The daemon reads the policies and enabled when each pass starts, so an edit applies to the next pass without a restart. Other Dreaming settings, such as tokenThreshold, timeout, and maxConcurrentPasses, are read when the daemon starts and need a restart.
  • DREAMING.md and kind: dreaming identity entries are retired. The daemon ignores them and logs a warning at startup when identity.special still lists one.
  • A policy cannot change the tools, their descriptions, or the write gate. Citation, scope, and provenance checks apply to every pass.
  • After the policy, the daemon appends the pass’s agent scopes when there is more than one, the codemode note when codemode is on, a directed instruction when one was given, the pass history, pending attention, and the current time.
  • Each pass records the policy it ran under: policySource is default or custom, and policyHash is the SHA-256 of the policy text. The text is stored once per distinct policy and returned by GET /api/dream/passes/:passId/policy. The dashboard shows it in the pass details. Passes from before this record have null for both fields.

Return the current dreaming worker state, configuration, recent passes, quarantined evidence, and pending agent-scoped semantic attention. Attention is operational context for work such as due reviews, hygiene, contested claims, or an explicitly requeued evidence source; it never copies or replaces episodic evidence. Requires admin permission.

Query parameters

Parameter Type Required Description
agentId string no Agent ID (default: daemon configured agent)
agent_id string no Alias for agentId
measure string no 1 probes the episodic backlog now

episodicTokensPending normally reports the last measurement, which is null when none is fresh. With measure=1 the route runs the bounded backlog probe: an exact count when at most 50 sources are waiting, null when more are.

config.policies holds the policy each pass type runs under, and config.defaultPolicies holds the built-in ones. config.policyProblems maps each agent.yaml policy entry that is not in use, such as dreaming.policies.content, to the reason. It lists entries that are not text, are over 64,000 characters, or name an unknown pass type, and is empty when there are none. A null or blank entry keeps the default without a problem.

Response

{
"enabled": true,
"worker": {
"running": true,
"active": false,
"activeAgentId": null,
"activePasses": [
{ "passId": "pass-uuid", "mode": "incremental" }
]
},
"episodicTokensPending": 42000,
"state": {
"tokensSinceLastPass": 42000,
"lastPassAt": "2026-04-01T12:00:00.000Z",
"lastPassId": "abc-123",
"lastPassMode": "incremental"
},
"config": {
"tokenThreshold": 100000,
"maxPassTokens": 200000,
"backfillOnFirstRun": true,
"maxInputTokens": 128000,
"maxOutputTokens": null,
"maxConcurrentPasses": 2,
"codemode": false,
"timeout": 300000,
"policies": {
"hygiene": "You are a bounded Signet maintenance agent. ...",
"content": "File claims only for decisions and shipped changes.\n",
"combined": "You are a bounded Signet maintenance agent. ..."
},
"defaultPolicies": {
"hygiene": "You are a bounded Signet maintenance agent. ...",
"content": "You are a bounded Signet maintenance agent. ...",
"combined": "You are a bounded Signet maintenance agent. ..."
},
"policyProblems": {}
},
"passes": [
{
"id": "pass-uuid",
"mode": "incremental",
"status": "completed",
"startedAt": "2026-04-01T12:00:00.000Z",
"completedAt": "2026-04-01T12:05:00.000Z",
"tokensConsumed": 8000,
"mutationsApplied": 12,
"mutationsSkipped": 3,
"mutationsFailed": 1,
"summary": "Merged 3 duplicate entities, pruned 5 junk attributes",
"error": null,
"policyHash": "5be07c19a3d2f640…",
"policySource": "custom"
}
],
"exclusions": [
{
"sourceKind": "artifact",
"sourceId": "sources/notebook/large-export.md",
"reason": "semantic_operation_rejected",
"failureClass": "quote_mismatch",
"retryCount": 0,
"passId": "pass-uuid",
"excludedAt": "2026-04-01 12:00:00",
"requeueRequestedAt": null,
"resolvedAt": null
}
],
"attention": [
{
"id": "attention-uuid",
"kind": "review_due",
"subjectRef": "entity:aster",
"details": { "reason": "review_after reached" },
"priority": 90,
"createdAt": "2026-04-01 12:00:00"
}
]
}

The episodicTokensPending field is a number only when a recent exact backlog measurement is available for the resolved agent. It is null when the backlog has not been measured, the cached measurement was invalidated, or the measurement expired. The status endpoint does not perform an unbounded token scan to populate this field.

A pass’s tokensConsumed is the total token count its inference target reported for the pass. It is null when the target reported no usage. A pass recorded by an earlier release without reported usage holds an estimate of its prompt size instead.

The status response also includes reviewedEvidence, containing immutable source revisions that a completed pass fully inspected and intentionally found to contain no durable fact. These rows are excluded from scan-first backlog accounting but remain available to direct evidence lookup and recall. The reviewedEvidence rows include sourceCapturedAt, sourceEntryId, sourceRevision, reason, passId, and reviewedAt, so the terminal decision is tied to one exact source revision rather than to a mutable source ID.

An exclusion preserves only the source identity and processing status; it does not modify or discard the underlying episodic evidence. Current Dreaming passes record semantic_operation_rejected when the daemon rejects an agent’s cited semantic operation. Oversized immutable evidence is instead resumed at a safe boundary across passes and is not quarantined.

Transient exclusions are classified as incomplete_transcript, source_projection, scope_mismatch, or quote_mismatch. The worker compares the current canonical source fingerprint with the quarantined fingerprint and automatically requests a bounded retry when a repair is visible. Automatic retries use the repair cooldown and hourly budget, allow at most three attempts per exclusion, and mint the same scoped evidence_requeue attention as an explicit request. An unchanged source, an unknown failure, or a source outside the agent scope remains quarantined. The exclusion row stays auditable until a subsequent accepted citation resolves it.

An attention item is selected with the next scoped pass and rendered as non-evidentiary context. It resolves when the pass applies a hygiene operation citing it, or when the agent explicitly declines it (the decline_attention operation, used when the agent inspects the target and judges it should stay as is). Records the agent could not complete stay pending, and a failed pass leaves everything pending. The worker can run for pending attention even when no new episodic evidence has arrived, while normal failure backoff still applies.

List the currently running passes in the resolved agent scope. This is the selection endpoint used by signet dream attach: the CLI attaches implicitly only when this list contains exactly one item. Requires admin permission.

{
"agentId": "noam",
"items": [
{
"id": "pass-uuid",
"mode": "incremental",
"status": "running",
"startedAt": "2026-04-01 12:00:00",
"completedAt": null,
"summary": null,
"error": null
}
]
}

The response is always scoped to the daemon’s current agent context unless an agent selector is supplied through the existing scoped-agent headers/query parameters. A pass ID from another agent is never accepted by the live stream route.

Open a read-only Server-Sent Events (SSE) stream for one agent-scoped pass. Requires admin permission. The optional after query parameter, or the Last-Event-ID header, resumes after a non-negative event cursor:

GET /api/dream/passes/pass-uuid/events?after=42
Accept: text/event-stream

The snapshot event includes the current pass metadata, replay window, and persisted token/cache/cost and mutation counters. Counters may be null until the pass writes its final measurements.

Subsequent events carry a monotonic id and include visible assistant text, Pi lifecycle transitions, tool start/progress/end events, detailed tool_trace events, session metadata, and a terminal pass_completed or pass_failed event. Tool arguments, progress payloads, results, traces, session prompt data, full message frames, and provider-emitted reasoning deltas are available in the stream by default. The legacy verbose query value is accepted but does not change the event payload. In signet dream attach, reasoning deltas appear in the activity timeline as Model reasoning; Ctrl+V toggles the local raw event-data view without reconnecting. A provider may omit reasoning events or provide only partial summaries; the stream reports what it emits and does not promise a complete or faithful chain-of-thought transcript.

This admin-only diagnostic stream does not redact event content. Event payloads remain size-bounded; a truncated payload is marked as such. Tool traces and Pi events remain ephemeral; the durable dreaming_passes and dreaming_tool_calls rows are the audit source.

When the requested cursor is outside the bounded in-memory replay window, the stream sends a gap event with requestedCursor, availableFrom, availableTo, and reason. The snapshot is authoritative and the client can continue from the latest cursor. Heartbeats are sent as SSE comments so idle connections remain detectable. Slow viewers are disconnected once their bounded stream queue fills and can reconnect from the last delivered cursor.

Request one quarantined or reviewed evidence source be considered again after correcting the model or configuration issue that caused it to be rejected, or after deciding that a previously reviewed source deserves another look. Requires admin permission.

Request body

{
"sourceKind": "artifact",
"sourceId": "sources/notebook/large-export.md",
"agentId": "noam"
}

sourceKind must be one of memory, artifact, transcript, or summary. sourceId is the identifier returned by GET /api/dream/status. agentId uses the same scoped-agent resolution as Dreaming trigger requests.

For memory, artifact, and transcript, returns 404 when neither the scoped transient exclusion nor a reviewed revision is active. When both states exist for those kinds, both are cleared. Summary sources retain their retired requeue behavior: a transient summary exclusion returns 410, and a reviewed summary can be reopened only when no transient summary exclusion is active. Requeueing also records an evidence_requeue attention item, so it can wake a scoped Dreaming pass without waiting for unrelated new evidence. The same endpoint reopens a reviewedEvidence disposition for the requested source; the response includes reviewedExcluded: true when that state was cleared.

Apply a batch of cited ontology operations for an external Dreaming agent. Requires modify permission. This is the daemon-owned semantic apply seam: the caller supplies operations and evidence, but the daemon resolves every episodic source in the credential’s agent scope before it writes graph state.

Request body

{
"agentId": "noam",
"actor": "dreaming-agent",
"operations": [
{
"operation": "set_claim_value",
"payload": { "entityId": "entity-id", "aspect": "role", "value": "Engineer" },
"reason": "The cited note explicitly identifies this role.",
"evidence": [{ "sourceKind": "artifact", "sourceId": "note.md", "quote": "..." }],
"confidence": 0.9
}
]
}

operations must contain 1–100 entries. Each entry must use one of the same closed, payload-validated ontology operation schemas exposed by apply_ontology_ops from GET /api/dream/tools; a write requires a canonical episodic source and an exact supporting quote. The daemon validates every input, citation, and resolvable target before it mints hygiene attention or writes graph state. It then applies operations in order through bounded, yielding write transactions. Each operation’s savepoint, provenance, and attention resolution are atomic, while an application failure is reported without blocking later operations. The whole request is not an all-or-nothing transaction. If writer admission fails after earlier chunks committed, the response is 503 with the committed items, retryable: true, and retryFrom. Retry only the uncommitted suffix, never the returned prefix; replace any earlier attention:$<index> reference with attention:<uuid> built from the flag item’s returned result.attentionId. Other validation failures return 400; a fully handled request returns 200. agentId uses scoped-agent resolution and cannot cross the credential’s agent scope.

Provenance by operation. Content operations (claims, entities, links) require exact-quote evidence. Archives and entity merges require hygiene attention provenance (attention:$<index> or attention:<uuid>). merge_aspects and rename_aspect restructure an entity’s existing aspects without adding facts, so any pass may apply them with a reason and no evidence or attention; a merge_aspects that cites a hygiene flag still resolves that flag. An entity holds at most memory.pipelineV2.traversal.maxWriteAspectsPerEntity aspects (default 20). Creating one past the cap fails with the entity’s existing aspects listed, so the pass can file under one of them or merge or rename to make room.

Claim time. add_claim_value, set_claim_value, and supersede_claim_value accept occurredAt and occurredUntil for an event, validFrom and validUntil for a state, and timePrecision (day, week, month, year, or approximate). Values are ISO dates or timestamps resolved against the cited source’s capture time; a date-only value defaults to day precision. supersede_claim_value also accepts reviewAfter. The time is stored on the claim and returned in its version history, and the claim’s semantic memory gets matching occurred and valid temporal edges, so temporal recall finds claims by when the event happened rather than when it was filed. An occurred edge without occurredUntil spans the precision: a day for day and approximate, a week, month, or year otherwise. Edges are derived from the claim and removed when its memory is purged.

When a claim arrives for a slot whose active claim has a later evidence time (validFrom, else occurredAt), the incoming claim is recorded as already superseded by the active one and the result names it in supersededByNewerEvidence. When the evidence times are equal (two updates on the same day) or neither claim has one, the claim whose cited source was captured later stays current, so the order Dreaming happens to file sources in does not decide the current value. A claim whose source has no capture time falls back to the newest write.

Claim text that contains a relative time such as “yesterday”, “last weekend”, or “three weeks ago” and no absolute date is rejected before any write, with an error asking for the absolute date and the matching time field. A relative phrase kept next to its resolved date (“the next week (week of 2023-06-05)”) is allowed, as are durations (“in one day”) and vague times with no anchor (“recently”).

Claim text that names an ISO date (2023-04-15) must also set a claim time (occurredAt, validFrom, validUntil, or reviewAfter); otherwise that operation is rejected with an error asking for the time field, using timePrecision: approximate when the source is vague (“shortly before 2023-04-15”). Without a stored time, date-filtered recall cannot find the claim.

Return the local, ordered Pi capability trace for one Dreaming pass: every tool’s input, output, success result, and latency. The route is agent-scoped and requires admin permission. It is intended for reviewing whether the agent searched graph or episodic evidence before proposing semantic writes.

Return the policy one Dreaming pass ran under. The route is agent-scoped and requires admin permission. It returns 404 when the pass does not exist for the resolved agent, and policy: null for a pass recorded before policies were.

{
"agentId": "default",
"passId": "pass-uuid",
"policy": {
"hash": "5be07c19a3d2f640…",
"source": "custom",
"text": "File claims only for decisions and shipped changes.\n"
}
}

Return deterministic, agent-scoped semantic quality measures for the current Dreaming graph. citationCoverage counts active claim values that retain an exact quote in canonical proposal evidence plus a resolvable episodic source; a source pointer without a quote is not citation coverage. graphGarbageRate applies the shared entity-quality classifier and detects possessive duplicates, excluding source-native topology. structureQuality reports the unknown entity-type rate, exact profile aspect rate, and generic-aspect rate (profile, details, general, and information) for model-ablation comparisons. Requires admin permission.

List the canonical Dreaming capability registry, including each capability’s JSON Schema. Pi sessions, restricted Dreaming MCP, and signet dream bind this same registry; clients must not reproduce a separate tool list. Requires modify permission.

list_aspect_claims returns each active claim with its evidence quote and source_ref; include: ["contradictions"] adds the aspect’s persisted competing-claim observations, exposing claim snapshots and their source and evidence metadata without selecting a winner. Correction still goes through apply_ontology_ops and the normal proposal governance path. Dependency links come from get_entity with include: ["links"]. walk_links, get_evidence, and list_contradictions were removed from the registry; callers use these options instead.

Each pass prompt also carries the pending attention for the pass’s scopes (hygiene, review_due, contested_claim, evidence_requeue, and surprisal, as fits the pass mode), up to 20 records per kind with long text bounded, so a pass works its queue without polling attention_list. attention_list remains for kinds marked "more": true and for re-checking after the pass flags something. The prompt ends with the current date and time in the daemon’s local timezone, for judging what is current, upcoming, or past due; relative times inside evidence still resolve against each source’s capturedAt.

A contested_claim record with reason source_changed names a claim whose source was edited after the claim was filed and no longer contains the cited quote. Source re-indexing writes it instead of deleting the claim. A content pass reads the source’s current text and keeps the claim (decline_attention), supersedes it with a quote from the new text, or archives it with archive_claim_value citing the record as attention:<id>, the one archive a content pass may make. Deleting a synced file or provider item writes the same record with reason source_removed, and the pass archives the claim unless other evidence still states it. Removing a whole source still purges its Dreaming rows.

memory_head_commit is the sole working-memory publication capability. Submit its complete retained entry set with exact source/quote support and the revision and hash from memory_head_read, under the active content pass. The owner renders the body and records removals for omitted entries. The rendered body, one - text line per entry, must be at most 1000 tokens. memory_head_read reports the head’s tokens and maxTokens, plus committedTokens for the committed entries during a content pass. An over-budget commit returns INVALID_HEAD with its tokens and maxTokens and is not staged, so the pass can shorten the entries and commit again. curate_memory_head is retired and returns 404; historical freeform audit rows remain intact. Every content pass stages exactly one commit, even when nothing changes: resubmit the current entries, or an empty entry set while the head is still empty. An empty set never clears a published head. Record deferrals and no-change explanations with runbook_write.

Invoke one canonical Dreaming capability through the daemon. This is the transport binding for restricted MCP and shell-driven harnesses; the daemon validates the registry schema and pins all reads and writes to the credential’s agent scope. Requires modify permission.

Request body

{
"agentId": "noam",
"input": { "query": "deployment target" }
}

passId is optional. A request that names a pass is served by that running pass’s own tools: the same capability set, agent scopes, write caps, evidence cursor, and tool-call trace an in-process agent gets. The daemon binds those tools while an ACPX agent runs the pass, and only for the pass’s own agent. The response is 409 when the pass is not accepting tool calls, 404 for a capability the pass does not expose, and 403 for another agent’s credential or a scope the pass does not allow. A passId that is not a non-empty string is rejected with 400. A request without passId runs outside any pass and cannot use review_evidence, runbook_write, or memory_head_commit.

input must satisfy the selected capability’s schema from GET /api/dream/tools. For example, search_entities accepts query, type, limit, and offset; apply_ontology_ops accepts a cited operations batch. Its schema is a closed union of the 19 audited ontology operations and each operation’s payload fields, so clients can validate an operation before attempting a write. The daemon bounds each write transaction by operation count and elapsed processing time, yielding between chunks while preserving request order. check_entity_label, find_duplicate_entities, and check_contradiction expose the daemon’s read-only deterministic guards so a reasoner can consult them before proposing a write; cited operation validation and semantic writes remain daemon-owned. The request body cannot supply a second agent scope inside input. A writer failure after a committed prefix returns 503 with retryable: true, retryFrom, and the committed items; retry only operations.slice(retryFrom), never the returned prefix. runbook_write stores one short structured note on a currently running pass. zoom_history opens a line of the scope’s pass history (see Pass history below): zoom_history(id, n) returns the two lines it was merged from, and n = 1 returns that pass’s record (note, operation counts and failures, evidence window, unresolved quarantines). CLI callers supply that pass with --pass-id; the Pi and restricted ACPX bindings receive it from the daemon-owned pass context.

Pass history. Each Dreaming pass starts with the scope’s pass history in its prompt instead of reading recent pass logs: one line per earlier pass, oldest first, with older passes folded pairwise into coarser lines so the history stays within a fixed budget (about 24 KB) however many passes have run. Lines read id+n|text, covering passes id through id+n-1. After a pass finishes, while it still holds its slot, the daemon asks the same Dreaming model, in a fresh request with no tools and no pass context, to compress that pass’s stored record into one line of at most 512 bytes, and to merge the oldest pair of lines when the history outgrows its budget. Lines are stored in dreaming_history_nodes and derived from the pass records, which stay the verbatim source; a pass whose line could not be built is shown as not yet summarized and is retried after the next pass. History is kept per scope set: a pass sees only the history of passes whose scopes are all within its own, each shown under a scopes= heading when there is more than one, and zoom_history refuses lines outside the pass’s scopes.

Manually trigger a dreaming pass. Requires admin permission. Returns 202 Accepted immediately and runs the pass in the background (passes can take up to several minutes on large graphs). The daemon keeps the worker available for manual triggers when automatic Dreaming is disabled; scheduled sweeps remain idle. The pipeline must be enabled, must not be paused, and mutations must not be frozen. Returns 409 when no pass can start, 503 if the pipeline prevents worker startup, and 503 with "No inference provider is connected" when no inference route resolves.

An incremental trigger may start several passes. The daemon splits the agents that are not already in a running pass into up to memory.dreaming.maxConcurrentPasses groups (default 2), balanced by evidence backlog, and runs one pass per group. A group holds at most memory.dreaming.maxPassTokens of measured backlog (default 200,000 tokens, range 10,000-2,000,000); an agent whose backlog alone exceeds it gets a group to itself. The same budget caps the evidence one pass is delivered: once the delivery queue has served about maxPassTokens of evidence (estimated at four characters per token), it closes (deliveryClosed: true) and the rest waits for the next pass, so even one agent with a very large backlog works through it in passes that can finish. Agents that do not fit wait for a later trigger or sweep, so every pass stays small enough to finish and commit before its timeout. Scheduled content sweeps use the same budget for their one pass and leave out agents with no backlog. It never starts more passes than worker.maxLlmConcurrency allows, because a pass waiting for a shared LLM permit would spend its own timeout waiting. The daemon allows that many Pi agent workers plus three for retained dashboard chats. Each pass may read and write only its own group’s agents, and an agent is in at most one running pass. The first pass starts immediately; the other groups start only after it completes a tool call, so an unavailable provider is not called once per group. The response’s passId is the first pass. worker.activePasses in GET /api/dream/status lists every running pass that includes the requested agent, as passId and mode only (no other agent’s id or scopes), and worker.activeAgentId is the requested agent while it is dreaming, otherwise null; the trigger is complete when it is empty. Compact passes, directed passes, and scheduled content and hygiene passes run alone. maxOutputTokens is unset by default, so each reply may use the model’s own output limit. maxInputTokens (default 128,000) sizes evidence reads: a delivery-queue page holds up to a sixteenth of it (32,000 characters by default, at least 16,000), so most sessions arrive whole instead of in 2,000-character fragments. Lower it for a model with a small context window. A Dreaming pass retries provider throttling and transient provider errors up to eight times with exponential backoff capped at 60 seconds (about four minutes in total) before the pass fails; interactive chat keeps the shorter default. memory.dreaming.codemode (default false) moves Dreaming’s read-only lookups (search_entities, get_entity, list_aspect_claims, validate_proposal, attention_list, zoom_history) behind Pi’s codemode tool, so a pass can batch them in one script. Evidence reads and writes stay direct calls, and scripts cannot call them. Nested calls run through the same audited tools and are traced like direct calls.

Poll GET /api/dream/status and check passes[0].status for completion, or use GET /api/dream/passes/:passId/events for a live read-only view.

Request body

{
"mode": "incremental",
"agentId": "noam"
}

mode is "incremental" (default) or "compact". agentId is optional and defaults to the daemon configured agent; agent_id, the agentId query parameter, the agent_id query parameter, and x-signet-agent-id are also accepted.

Optional instructionSourceRef identifies already-recorded evidence in the resolved agent scope. The daemon retrieves the complete instruction from that evidence; inaccessible, missing, or fragmented instructions fail explicitly. A directed pass stays within that agent scope and runs even if its normal backlog is empty. The instruction uses the existing audited Dreaming tools and citation gates.

Explicit triggers always run the combined incremental runbook (hygiene queue first, then content ingestion). The worker’s scheduled sweep passes, in contrast, alternate between two focused runbooks when both kinds of work are pending — incremental-hygiene (attention queue only) and incremental-content (new evidence only) — so content ingestion gets a guaranteed turn even while the hygiene queue stays full (#1098). The pass row’s mode column and the status response’s state.lastPassMode record the runbook that actually ran.

Response — 202 Accepted

{
"accepted": true,
"passId": "pass-uuid",
"status": "running",
"mode": "incremental",
"agentId": "noam"
}

Session checkpoints track continuity state at compaction boundaries.

List session checkpoints for a project.

Query parameters

Parameter Type Required Description
project string yes Project path to filter by
limit integer no Max results (default: 10, max: 100)

Response

{
"checkpoints": [
{
"session_key": "abc-123",
"project": "/path/to/project",
"trigger": "periodic",
"created_at": "2026-02-21T10:00:00.000Z"
}
],
"count": 1
}

Get all checkpoints for a specific session.

Response

{
"checkpoints": [ ... ],
"count": 3
}