Knowledge Graph

The knowledge graph is Signet’s scoped ontology storage and traversal layer. It organizes raw memories, structured remember payloads, source artifacts, and reviewed ontology operations into entities, aspects, grouped claim slots, attributes, dependencies, proposals, and assertions.

For the conceptual model, see KNOWLEDGE-ARCHITECTURE.md. This document is the implementation reference.

Core Tables

The base graph schema starts in migration 019 and is extended by later migrations.

`entities`

Top-level graph nodes. Important fields include:

id
name
canonical_name
entity_type
agent_id
description
mentions
pinned
pinned_at
status
archived_at, archived_by, archive_reason
proposal_id
proposal_evidence
last_synthesized_at
timestamps

ENTITY_TYPES is defined in platform/core/src/types.ts and currently includes people, projects, systems, tools, concepts, skills, tasks, sources, artifacts, agents, policies, actions, workflows, events, object types, interfaces, observations, claim slots, claim values, and unknown.

List queries filter to agent_id and active rows, then sort pinned entities first:

ORDER BY e.pinned DESC, e.pinned_at DESC, e.mentions DESC, e.updated_at DESC, e.name ASC

`entity_aspects`

Named dimensions under an entity. Important fields include:

id
entity_id
agent_id
name
canonical_name
weight
status
archive fields
proposal fields
timestamps

Aspects are unique on (entity_id, canonical_name). Traversal reads active aspects ordered by weight DESC.

`entity_attributes`

Stored facts and constraints under an aspect. Important fields include:

id
aspect_id
agent_id
memory_id
kind: attribute or constraint
content
normalized_content
group_key
claim_key
confidence
importance
status: active, superseded, or deleted
superseded_by
version
version_root_id
previous_attribute_id
archive fields
source provenance fields
proposal fields
timestamps

group_key and claim_key are the navigation and update identity layer:

entity -> aspect -> group_key -> claim_key -> attribute versions

When group_key is missing, navigation treats the row as part of general. When claim_key is present, claim history and supersession are scoped to that specific claim slot instead of the whole aspect.

`entity_dependencies`

Directed cross-entity edges. Important fields include:

id
source_entity_id
target_entity_id
agent_id
aspect_id
dependency_type
strength
confidence
reason
status
archive fields
source provenance fields
proposal fields
timestamps

DependencyType is defined in platform/core/src/types.ts. Traversal currently uses outgoing dependency edges and gates them by both:

confidence * strength >= minDependencyStrength
confidence >= minConfidence

related_to edges require a non-empty reason. Migration 050 adds entity_dependency_history, an append-only audit table populated by triggers for dependency insert, update, and delete events.

`task_meta`

Task lifecycle metadata keyed by entity_id. It stores status, expires_at, retention_until, and completed_at for entities whose lifecycle should behave like a task rather than durable background knowledge.

Audit and Control Tables

`ontology_proposals`

Proposal and operation history. Pending proposals are review queues; applied rows are audit records for direct operation handlers. Fields include:

operation
status: pending, applied, rejected, or failed
payload
confidence
rationale
evidence
risk
source provenance
created_by, applied_by, rejected_by
result
timestamps

The daemon operation handlers can run in three modes:

dry-run: validate and preview without mutation
apply: mutate graph rows and write an applied proposal row
propose: write pending proposal rows for later review

`epistemic_assertions`

Attribution records for statements that should not automatically become current ontology truth. Fields include:

subject_entity_id
optional claim_attribute_id
predicate: claims, believes, observed, decided, prefers, denies, or questions
content
speaker
asserted_at
confidence
evidence
source provenance
status: active, archived, or superseded
supersedes_assertion_id
archive fields
timestamps

Assertions can be linked to current claim attributes, but they remain a separate evidence/attribution layer.

Write Paths

Semantic graph authorship (entities, aspects, attributes, dependencies) flows through the audited ontology apply path. The retired txPersistStructured / txPersistEntities transaction closures and the inline LLM extraction chain (extractFactsAndEntities) were removed under the Dreaming cutover (#946); remember and ingest no longer author graph structure directly.

The only retained write closure in platform/daemon/src/pipeline/graph-transactions.ts is txDecrementEntityMentions, used by the retention worker to decrement mention counts and delete orphaned entities (plus their dangling relations) after a memory purge.

Ontology Operation Handlers

Source: platform/daemon/src/ontology-proposals.ts

The control plane applies or proposes graph operations such as:

create_entity
add_claim_value
set_claim_value
rename_entity
archive_entity
create_aspect
rename_aspect
archive_aspect
archive_claim_value
restore_claim_version
create_link
update_link
archive_link
merge_entities
merge_aspects
supersede_claim_value
policy, action type, and interface operations

These handlers are the preferred path for explicit ontology maintenance because they validate inputs, preserve provenance, update version lineage, and leave an audit row.

Traversal

Source: platform/daemon/src/pipeline/graph-traversal.ts

Traversal resolves focal entities, walks a bounded subgraph, and returns memory IDs plus structural metadata for recall.

Focal Resolution

resolveFocalEntities gathers entities in this order:

pinned entities, unless disabled;
checkpoint entity IDs, when supplied;
project-path matches against project entities;
query-token matches using entities_fts when available, with LIKE fallback;
session-key fallback as source metadata when no entity resolves.

Pinned entities are merged into the focal set, not used as a replacement for query or project matches.

Walk Budget

TraversalConfig controls the walk:

Field	Meaning
`scope`	Optional memory scope filter
`maxAspectsPerEntity`	Active aspects per entity, ordered by weight
`maxAttributesPerAspect`	Attribute memory IDs per aspect
`maxDependencyHops`	Historical config field; current walk uses branching and path budgets
`minDependencyStrength`	Minimum combined `confidence * strength`
`maxBranching`	Max outgoing edges per focal entity
`maxTraversalPaths`	Total memory ID budget
`minConfidence`	Minimum edge confidence
`timeoutMs`	Hard deadline
`aspectFilter`	Optional aspect-name filter for on-demand expansion

Collection Rules

For each entity, traversal:

collects active constraints across all active aspects;
fetches top active aspects by weight DESC;
collects active attribute memory_id values by importance DESC;
falls back to memory_entity_mentions if attributes do not yield enough memory IDs;
follows qualifying outgoing dependencies from the focal entity set;
records memory paths for feedback propagation and telemetry.

The result includes:

memoryIds
memoryScores
memoryPaths
constraints
entityCount
timedOut
activeAspectIds
focalEntityIds

Recall merges this graph result with vector, FTS, hint, structured-evidence, reranker, dampening, and context-construction stages.

Feedback and Maintenance

Source: platform/daemon/src/pipeline/aspect-feedback.ts

Aspect feedback is driven by session outcomes. FTS overlap can increase aspect weights when previously injected memories later match full-text searches. Aspect decay lowers stale weights toward a configured floor.

Source: platform/daemon/src/pipeline/graph-transactions.ts

Supersession

Conflicting sibling attributes in the same aspect_id + group_key + claim_key slot are superseded at write time by the audited structured apply path. The newer attribute wins when its content is a likely supersession of the older one; constraints are not auto-superseded by this write-time heuristic. Explicit, audited supersession flows through the supersede_claim_value ontology operation handler (see “Ontology Operation Handlers” above), which validates inputs, preserves provenance, updates version lineage, and leaves an audit row. The periodic retroactive supersession sweep was retired under the Dreaming cutover (#946); maintenance does not supersede semantic rows.

Source: platform/daemon/src/knowledge-graph-hygiene.ts

Hygiene reporting is read-only. It surfaces suspicious entities, duplicate canonical groups, missing group/claim/source fields, and safe known-entity mention candidates.

HTTP API

Read-oriented graph endpoints live in platform/daemon/src/routes/knowledge-routes.ts.

Endpoint	Method	Purpose
`/api/knowledge/entities`	GET	List active entities with structural counts
`/api/knowledge/navigation/entities`	GET	Alias for paginated entity navigation
`/api/knowledge/navigation/entity`	GET	Resolve an entity by name
`/api/knowledge/navigation/tree`	GET	Entity -> aspect -> group -> claim outline
`/api/knowledge/navigation/aspects`	GET	List aspects for an entity
`/api/knowledge/navigation/groups`	GET	List groups under an entity/aspect
`/api/knowledge/navigation/claims`	GET	List claims under an entity/aspect/group
`/api/knowledge/navigation/attributes`	GET	List attributes for a claim path
`/api/knowledge/entities/:id`	GET	Entity detail and counts
`/api/knowledge/entities/:id/aspects`	GET	Aspect counts
`/api/knowledge/entities/:id/aspects/:aspectId/attributes`	GET	Attributes for an aspect
`/api/knowledge/entities/:id/dependencies`	GET	Incoming and outgoing dependencies
`/api/knowledge/entities/:id/pin`	POST	Pin an entity, requires `modify`
`/api/knowledge/entities/:id/pin`	DELETE	Unpin an entity, requires `modify`
`/api/knowledge/entities/pinned`	GET	List pinned entities
`/api/knowledge/entities/health`	GET	Predictor comparison health by entity
`/api/knowledge/hygiene`	GET	Read-only hygiene report
`/api/knowledge/stats`	GET	Graph coverage and feedback stats
`/api/knowledge/communities`	GET	Community summaries
`/api/knowledge/traversal/status`	GET	Last traversal telemetry
`/api/knowledge/constellation`	GET	Dashboard graph payload
`/api/knowledge/expand`	POST	Entity expansion with related memory/session context
`/api/knowledge/expand/session`	POST	Session-summary expansion

Ontology-control endpoints live in platform/daemon/src/routes/ontology-routes.ts.

Endpoint family	Purpose
`/api/ontology/operations/*`	Apply, dry-run, or batch explicit ontology operations
`/api/ontology/proposals/*`	List, create, apply, reject, and inspect proposals
`/api/ontology/proposals/repair/*`	Duplicate and merge-plan helpers
`/api/ontology/claims/*`	Claim evidence, versions, and version reads
`/api/ontology/links/*`	Link evidence
`/api/ontology/assertions/*`	Epistemic assertion CRUD and lifecycle
`/api/ontology/extract`	Extract proposals/assertions from a source
`/api/ontology/consolidate`	Consolidate proposals with optional provider support

Mutation endpoints require modify permission. Read endpoints require recall permission when auth is enabled.

Recall-related endpoints also use graph data:

Endpoint	Method	Graph role
`/api/memory/recall`	POST	Merges traversal candidates with recall candidates
`/api/memory/search`	GET	Search with entity context
`/api/embeddings/projection`	GET	Dashboard memory projection; graph overlay comes from `/api/knowledge/constellation`

CLI Surfaces

Read navigation:

signet knowledge entities
signet knowledge tree <entity>
signet knowledge aspects <entity>
signet knowledge groups <entity> <aspect>
signet knowledge claims <entity> <aspect> <group>
signet knowledge attributes <entity> <aspect> <group> <claim>
signet knowledge hygiene

Control plane:

signet ontology entity ...
signet ontology claim ...
signet ontology aspect ...
signet ontology link ...
signet ontology stream apply ...
signet ontology assertion ...
signet ontology proposals ...
signet ontology extract ...
signet ontology consolidate ...

Use --json on either command family for automation.

Dashboard Payload

getKnowledgeGraphForConstellation in platform/daemon/src/knowledge-graph.ts builds the dashboard graph. It fetches active entities, aspects, attributes, dependencies, proposal overlays, and dreaming summaries within bounded limits. The dashboard then converts that payload into entity, aspect, attribute, memory, proposal, and relationship nodes.

When the request does not include agent_id, /api/knowledge/constellation uses the configured daemon agent ID (SIGNET_AGENT_ID, falling back to default). The constellation payload includes rows owned by the requested agent and rows owned by agents whose read_policy is shared, so the main dashboard can surface shared named-agent graphs instead of showing an empty default-agent view.

Agent Scope

Every graph read or write must be scoped by agent_id. Route defaults should resolve through the daemon’s configured agent ID where possible; internal logic should thread the resolved agent ID through queries and mutations rather than relying on a global graph.