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

Structured Remember Payloads

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

txPersistStructured writes caller-provided structured data from the remember API. It:

1. persists extracted entity triples through txPersistEntities;
2. upserts mentioned entities;
3. upserts aspects by (entity_id, canonical_name);
4. inserts attributes with optional groupKey and claimKey;
5. links rows to the source memory through memory_id and memory_entity_mentions;
6. supersedes likely conflicting sibling attributes in the same aspect_id + group_key + claim_key slot;
7. creates low-strength related_to dependencies between co-occurring structured entities.

If the source memory is decision-like, structured attributes are promoted to kind = 'constraint'; otherwise they are normal attributes.

Extracted Entity Mentions

txPersistEntities persists extracted source/relationship/target triples into entities, the older relations table, and memory_entity_mentions.

This path links memories to entities and maintains mention counts. It does not create aspect or attribute rows by itself.

Pipeline Graph Writes

Background extraction graph writes are controlled by memory.pipelineV2.graph.extractionWritesEnabled, which defaults to true. Set it to false when graph traversal should stay enabled but the async extractor should not author ontology structure. When graph reads are enabled but extraction writes remain disabled, the daemon emits a startup warning and /api/diagnostics exposes the disabled write gate as graph.extractionWritesEnabled: false.

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
• 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:

1. pinned entities, unless disabled;
2. checkpoint entity IDs, when supplied;
3. project-path matches against project entities;
4. query-token matches using entities_fts when available, with LIKE fallback;
5. 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:

Collection Rules

For each entity, traversal:

1. collects active constraints across all active aspects;
2. fetches top active aspects by weight DESC;
3. collects active attribute memory_id values by importance DESC;
4. falls back to memory_entity_mentions if attributes do not yield enough memory IDs;
5. follows qualifying outgoing dependencies from the focal entity set;
6. 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/supersession.ts

Retroactive Supersession

Supersession detects and marks conflicting active sibling attributes. Structured remember does this at write time for matching claim slots. Maintenance can also catch older contradictions. Constraints are not automatically superseded by this heuristic.

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.

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

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

Recall-related endpoints also use graph data:

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.

See Also

• KNOWLEDGE-ARCHITECTURE.md
• PIPELINE.md
• API.md
• dreaming-skill-runbook.md
• knowledge-graph-control-plane.md