Knowledge and ontology API
Knowledge navigation, ontology proposal, dreaming, and checkpoint endpoints.
Knowledge graph navigation
Section titled “Knowledge graph navigation”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 -> AttributesThe 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.
GET /api/knowledge/navigation/entities
Section titled “GET /api/knowledge/navigation/entities”List entities with structural counts. Query parameters: q, type, limit,
offset.
GET /api/knowledge/navigation/entity
Section titled “GET /api/knowledge/navigation/entity”Resolve one entity by name.
/api/knowledge/navigation/entity?name=NicholaiGET /api/knowledge/navigation/tree
Section titled “GET /api/knowledge/navigation/tree”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=3GET /api/knowledge/navigation/aspects
Section titled “GET /api/knowledge/navigation/aspects”List aspects for an entity.
/api/knowledge/navigation/aspects?entity=NicholaiGET /api/knowledge/navigation/groups
Section titled “GET /api/knowledge/navigation/groups”List groups under an entity aspect. Attributes without group_key appear under
general for backward compatibility.
/api/knowledge/navigation/groups?entity=Nicholai&aspect=foodGET /api/knowledge/navigation/claims
Section titled “GET /api/knowledge/navigation/claims”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=0GET /api/knowledge/navigation/attributes
Section titled “GET /api/knowledge/navigation/attributes”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_restaurantCLI equivalents:
signet knowledge tree Nicholaisignet knowledge tree Nicholai --max-total-claims 1000signet knowledge entities --query Nicholaisignet knowledge entity Nicholaisignet knowledge aspects Nicholaisignet knowledge groups Nicholai foodsignet knowledge claims Nicholai food restaurants --limit 50 --offset 0signet knowledge attributes Nicholai food restaurants favorite_restaurantsignet knowledge attributes Nicholai food restaurants favorite_restaurant --status allsignet knowledge hygieneGET /api/knowledge/constellation
Section titled “GET /api/knowledge/constellation”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.
GET /api/knowledge/hygiene
Section titled “GET /api/knowledge/hygiene”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
Section titled “Entity aliases”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.
GET /api/ontology/entities/:id/aliases
Section titled “GET /api/ontology/entities/:id/aliases”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=allPOST /api/ontology/entities/:id/aliases
Section titled “POST /api/ontology/entities/:id/aliases”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:
signet ontology entity alias list entity_signet --status allsignet ontology entity alias add entity_signet SignetAI --confidence 0.95 --source operatorsignet ontology entity alias archive entity_signet alias_123Ontology proposal loop
Section titled “Ontology proposal loop”Ontology maintenance writes reviewable proposals before mutating semantic graph
state. Read routes require recall; mutation routes require modify. All
routes accept optional agent_id.
GET /api/ontology/proposals
Section titled “GET /api/ontology/proposals”List proposal records. Query parameters: status, operation, limit,
offset.
GET /api/ontology/proposals/:id
Section titled “GET /api/ontology/proposals/:id”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=antGET /api/ontology/proposals/conflicts
Section titled “GET /api/ontology/proposals/conflicts”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=100GET /api/ontology/contradictions
Section titled “GET /api/ontology/contradictions”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=allThe 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.
GET /api/ontology/contradictions/:id
Section titled “GET /api/ontology/contradictions/:id”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:
signet ontology contradictions --agent ant --status allsignet ontology contradictions --entity Signet --group architecture --claim current_valueGET /api/ontology/proposals/:id/evidence
Section titled “GET /api/ontology/proposals/:id/evidence”Resolve a proposal’s evidence references against session transcripts and indexed memory artifacts. The endpoint never reads arbitrary filesystem paths.
GET /api/ontology/claims/evidence
Section titled “GET /api/ontology/claims/evidence”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_loopGET /api/ontology/claims/explain
Section titled “GET /api/ontology/claims/explain”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:
signet ontology explain-claim Signet architecture ontology proposal_loopsignet ontology explain-claim Signet architecture ontology proposal_loop --session-key session-123 --jsonMCP clients call signet_explain_claim with the same selectors and bounds.
GET /api/ontology/links/:id/evidence
Section titled “GET /api/ontology/links/:id/evidence”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.
GET /api/ontology/assertions
Section titled “GET /api/ontology/assertions”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=NicholaiGET /api/ontology/assertions/:id
Section titled “GET /api/ontology/assertions/:id”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=antPOST /api/ontology/assertions
Section titled “POST /api/ontology/assertions”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.
POST /api/ontology/assertions/:id/archive
Section titled “POST /api/ontology/assertions/:id/archive”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:
signet ontology assertions --entity Signet --predicate believes --speaker Nicholaisignet ontology assertion create --entity Signet --predicate believes --content "Signet should model attributed beliefs." --source-kind transcriptsignet 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 transcriptsignet ontology assertion import --file assertions.jsonPOST /api/ontology/extract
Section titled “POST /api/ontology/extract”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.
POST /api/ontology/consolidate
Section titled “POST /api/ontology/consolidate”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.
POST /api/ontology/proposals
Section titled “POST /api/ontology/proposals”Create one pending ontology proposal.
POST /api/ontology/proposals/batch
Section titled “POST /api/ontology/proposals/batch”Create multiple pending proposals atomically.
POST /api/ontology/proposals/:id/apply
Section titled “POST /api/ontology/proposals/:id/apply”Apply one pending proposal through its explicit operation handler.
POST /api/ontology/proposals/:id/reject
Section titled “POST /api/ontology/proposals/:id/reject”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
Section titled “Dreaming”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.policyProblemsfromGET /api/dream/status, which the dashboard shows next to the policy. - The daemon reads the policies and
enabledwhen each pass starts, so an edit applies to the next pass without a restart. Other Dreaming settings, such astokenThreshold,timeout, andmaxConcurrentPasses, are read when the daemon starts and need a restart. DREAMING.mdandkind: dreamingidentity entries are retired. The daemon ignores them and logs a warning at startup whenidentity.specialstill 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
codemodeis 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:
policySourceisdefaultorcustom, andpolicyHashis the SHA-256 of the policy text. The text is stored once per distinct policy and returned byGET /api/dream/passes/:passId/policy. The dashboard shows it in the pass details. Passes from before this record havenullfor both fields.
GET /api/dream/status
Section titled “GET /api/dream/status”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.
GET /api/dream/passes/active
Section titled “GET /api/dream/passes/active”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.
GET /api/dream/passes/:passId/events
Section titled “GET /api/dream/passes/:passId/events”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=42Accept: text/event-streamThe 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.
POST /api/dream/exclusions/requeue
Section titled “POST /api/dream/exclusions/requeue”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.
POST /api/dream/operations
Section titled “POST /api/dream/operations”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.
GET /api/dream/passes/:passId/tools
Section titled “GET /api/dream/passes/:passId/tools”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.
GET /api/dream/passes/:passId/policy
Section titled “GET /api/dream/passes/:passId/policy”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" }}GET /api/dream/quality
Section titled “GET /api/dream/quality”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.
GET /api/dream/tools
Section titled “GET /api/dream/tools”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.
POST /api/dream/tools/:capability
Section titled “POST /api/dream/tools/:capability”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.
POST /api/dream/trigger
Section titled “POST /api/dream/trigger”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"}Checkpoints
Section titled “Checkpoints”Session checkpoints track continuity state at compaction boundaries.
GET /api/checkpoints
Section titled “GET /api/checkpoints”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 /api/checkpoints/:sessionKey
Section titled “GET /api/checkpoints/:sessionKey”Get all checkpoints for a specific session.
Response
{ "checkpoints": [ ... ], "count": 3}
