Skip to content

KNOWLEDGE-GRAPH.md

Latest commit

 

History

History
450 lines (351 loc) · 14.3 KB

KNOWLEDGE-GRAPH.md

File metadata and controls

450 lines (351 loc) · 14.3 KB
title Knowledge Graph
description Implementation reference for Signet's scoped ontology and graph traversal layer.
order 3
section Core Concepts

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 false. Keeping graph traversal enabled does not necessarily mean the async extractor is allowed to author ontology structure.

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:

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:

  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.

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.

Agent Scope

Every graph read or write must be scoped by agent_id. Existing route defaults to "default" are compatibility defaults at the boundary; internal logic should thread the resolved agent ID through queries and mutations rather than relying on a global graph.

See Also