Knowledge Graph Engine

interface GraphNode {
  id: string;                      // Unique entity identifier (e.g. "auth_jwt")
  type: GraphNodeType;             // Standard or custom entity type
  label: string;                   // Canonical human-readable name
  aliases?: string[];              // Synonyms (used for duplicate detection)
  summary?: string;                // Condensed description of the entity
  confidence?: number;             // Confidence score (0.0 to 1.0)
  importance?: number;             // Relative importance weight
  status?: GraphFactStatus;        // "active" | "deprecated" | "stale" | etc.
  disputed?: boolean;              // True if contested by conflicting facts
  stale?: boolean;                 // True if anchored code drifted
  unverified?: boolean;            // True if age > EXPIRY_DAYS
  sourceRefs?: GraphSourceRef[];   // Provenance references
  metadata?: GraphMetadata;        // Custom JSON metadata
}

interface GraphEdge {
  id?: string;                     // Unique edge ID (auto-generated if omitted)
  from: string;                    // Source node ID
  to: string;                      // Target node ID
  type: GraphEdgeType;             // Relationship type (e.g. "depends_on")
  directed?: boolean;              // True for directional relationships (default: true)
  weight?: number;                 // Pathfinding traversal weight (default: 1.0)
  confidence?: number;             // Edge confidence score
  dedupeKey?: string;              // Salt for preserving parallel facts
  status?: GraphFactStatus;        // "active" | "deprecated" | etc.
  disputed?: boolean;              // True if contested
  sourceRefs?: GraphSourceRef[];   // Provenance references
  metadata?: GraphMetadata;        // Custom JSON metadata
}

// Upsert nodes
await memofs.graph.upsertNodes({
  nodes: [
    { id: "oauth2", type: "concept", label: "OAuth 2.0 Auth" },
    { id: "jwt", type: "concept", label: "JSON Web Token", aliases: ["JWT", "jwt-token"] },
    { id: "api_gateway", type: "tool", label: "API Gateway" },
  ],
});

// Upsert relationship edges
await memofs.graph.upsertEdges({
  edges: [
    { from: "api_gateway", to: "oauth2", type: "uses" },
    { from: "oauth2", to: "jwt", type: "depends_on" },
  ],
});

const result = await memofs.graph.neighbors({
  nodeId: "api_gateway",
  direction: "out", // "in" | "out" | "both"
  edgeTypes: ["uses", "depends_on"],
});

for (const { node, edge, direction } of result.items) {
  console.log(`[${direction}] -> ${edge.type} -> ${node.label} (${node.id})`);
}

const path = await memofs.graph.path({
  from: "api_gateway",
  to: "jwt",
  weighted: true,
  maxDepth: 5,
});

if (path.found) {
  console.log(`Found path with ${path.nodes.length} nodes (total cost: ${path.totalCost})`);
  for (const node of path.nodes) {
    console.log(` -> ${node.label}`);
  }
}

const nodesPage = await memofs.graph.listNodes({ limit: 50 });
const edgesPage = await memofs.graph.listEdges({ limit: 50 });

import { createRuleBasedExtractor } from "@memofs/core";

const extractor = createRuleBasedExtractor();
const result = await extractor.extract({
  text: "The payment service depends on Stripe API and uses Redis for idempotency caching.",
});

console.log(result.nodes); // Extracted entities: payment service, Stripe API, Redis
console.log(result.edges); // Extracted edges: depends_on, uses

// Dry run preview (plan only)
const preview = await memofs.consolidate({ apply: false });
console.log(`Proposed merges: ${preview.plan.merges}`);
console.log(`Proposed retirements: ${preview.plan.retiredNodes}`);

// Apply consolidation plan
const applied = await memofs.consolidate({ apply: true });
console.log(`Merges applied: ${applied.mergesApplied}`);
console.log(`Retirements applied: ${applied.retirementsApplied}`);