cognitive-core 0.1.0 → 0.1.2

package/src/types/knowledge-graph.ts

@@ -0,0 +1,246 @@
+import type { GraphLayerName, KnowledgeNote, LinkRelation } from './knowledge.js';
+
+// ============================================================================
+// Graph Node (shared across all layers)
+// ============================================================================
+
+export interface GraphNode {
+  /** Knowledge note ID */
+  id: string;
+  /** Relative file path from memory root */
+  file: string;
+  /** Note type */
+  type: 'observation' | 'entity' | 'domain-summary';
+  /** Domains for fast filtering */
+  domains: string[];
+  /** Entities for fast filtering */
+  entities: string[];
+  /** Tags for fast filtering */
+  tags: string[];
+  /** Current confidence */
+  confidence: number;
+  /** Last updated timestamp (ISO 8601) */
+  updated: string;
+}
+
+// ============================================================================
+// Graph Edge (within a specific layer)
+// ============================================================================
+
+export interface GraphEdge {
+  /** Source note ID */
+  from: string;
+  /** Target note ID */
+  to: string;
+  /** Relationship type */
+  relation: string;
+  /** Edge weight (0-1, for ranked traversal) */
+  weight: number;
+  /** When this edge was established (ISO 8601) */
+  created: string;
+  /** Whether this edge crosses into another system */
+  crossSystem?: 'playbook' | 'experience';
+  /** Source trajectory that produced this edge, if any */
+  sourceTrajectory?: string;
+}
+
+// ============================================================================
+// Graph Layer
+// ============================================================================
+
+export interface GraphLayer {
+  /** Layer identifier */
+  name: GraphLayerName;
+  /** Whether this layer is currently enabled */
+  enabled: boolean;
+  /** Edges in this layer */
+  edges: GraphEdge[];
+}
+
+// ============================================================================
+// Multi-Graph Structure (top-level persisted format)
+// ============================================================================
+
+export interface KnowledgeMultiGraph {
+  /** Schema version for migration */
+  version: number;
+  /** Last rebuild timestamp */
+  lastRebuilt: string;
+  /** Shared node registry */
+  nodes: Record<string, GraphNode>;
+  /** Graph layers — each independently toggleable */
+  layers: Record<GraphLayerName, GraphLayer>;
+}
+
+// ============================================================================
+// Layer Operations Interface
+// ============================================================================
+
+export interface GraphLayerOperations {
+  /** Layer name */
+  readonly name: GraphLayerName;
+
+  /** Whether this layer is enabled */
+  readonly enabled: boolean;
+
+  /** Get edges from/to a node in this layer */
+  getEdges(
+    nodeId: string,
+    direction?: 'outgoing' | 'incoming' | 'both'
+  ): GraphEdge[];
+
+  /** BFS neighbors within this layer */
+  neighbors(nodeId: string, depth?: number): string[];
+
+  /** Shortest path between two nodes within this layer */
+  pathBetween(fromId: string, toId: string): string[] | null;
+
+  /** Add an edge to this layer */
+  addEdge(edge: GraphEdge): void;
+
+  /** Remove an edge from this layer */
+  removeEdge(fromId: string, toId: string, relation: string): void;
+
+  /** Get all edges in this layer */
+  getAllEdges(): GraphEdge[];
+
+  /** Get edge count */
+  edgeCount(): number;
+
+  /** Rebuild this layer from knowledge notes */
+  rebuild(notes: KnowledgeNote[]): void;
+
+  /** Clear all edges */
+  clear(): void;
+}
+
+// ============================================================================
+// Graph Manager Interface
+// ============================================================================
+
+export interface GraphNodeFilter {
+  domains?: string[];
+  entities?: string[];
+  tags?: string[];
+  type?: GraphNode['type'];
+  minConfidence?: number;
+}
+
+export interface NeighborOptions {
+  depth?: number;
+  layers?: GraphLayerName[];
+  minWeight?: number;
+}
+
+export interface KnowledgeGraphManagerInterface {
+  /** Get a specific layer */
+  getLayer(name: GraphLayerName): GraphLayerOperations | null;
+
+  /** Query across all enabled layers (union of edges) */
+  neighbors(nodeId: string, options?: NeighborOptions): GraphNode[];
+
+  /** Cross-layer path: can traverse edges from any enabled layer */
+  pathBetween(
+    fromId: string,
+    toId: string,
+    options?: { layers?: GraphLayerName[] }
+  ): Array<{ node: GraphNode; edge: GraphEdge; layer: GraphLayerName }> | null;
+
+  /** Filter nodes by criteria */
+  filterNodes(filter: GraphNodeFilter): GraphNode[];
+
+  /** Get cross-system links (to playbooks/experiences) */
+  crossSystemLinks(nodeId: string): GraphEdge[];
+
+  /** Add a node to the shared registry */
+  addNode(node: GraphNode): void;
+
+  /** Remove a node from the shared registry and all layers */
+  removeNode(nodeId: string): void;
+
+  /** Get a node by ID */
+  getNode(nodeId: string): GraphNode | undefined;
+
+  /** Get all nodes */
+  getAllNodes(): GraphNode[];
+
+  /** Rebuild all enabled layers from notes */
+  rebuildAll(notes: KnowledgeNote[]): void;
+
+  /** Load graph from disk */
+  loadFromDisk(dir: string): Promise<void>;
+
+  /** Save graph to disk */
+  saveToDisk(dir: string): Promise<void>;
+
+  /** Get statistics */
+  getStats(): {
+    nodeCount: number;
+    edgeCountByLayer: Record<string, number>;
+    enabledLayers: string[];
+  };
+}
+
+// ============================================================================
+// Graph Configuration
+// ============================================================================
+
+export interface GraphConfig {
+  /** Which graph layers to enable */
+  enabledLayers: GraphLayerName[];
+  /** Whether to auto-infer temporal edges from timestamps */
+  inferTemporalEdges: boolean;
+  /** Whether to auto-infer causal edges from failure-recovery patterns */
+  inferCausalEdges: boolean;
+  /** Whether to auto-infer entity edges from shared entity tags */
+  inferEntityEdges: boolean;
+  /** Split layer files by domain when node count exceeds this */
+  domainSplitThreshold: number;
+  /** Promote to SQLite when total edge count exceeds this */
+  sqlitePromotionThreshold: number;
+}
+
+/** Default graph configuration */
+export const DEFAULT_GRAPH_CONFIG: GraphConfig = {
+  enabledLayers: ['semantic'],
+  inferTemporalEdges: true,
+  inferCausalEdges: true,
+  inferEntityEdges: true,
+  domainSplitThreshold: 500,
+  sqlitePromotionThreshold: 10000,
+};
+
+// ============================================================================
+// Valid relation sets per layer (for layer implementations)
+// ============================================================================
+
+export const SEMANTIC_RELATIONS: readonly LinkRelation[] = [
+  'related-to',
+  'depends-on',
+  'specializes',
+  'generalizes',
+  'supports',
+];
+
+export const TEMPORAL_RELATIONS: readonly LinkRelation[] = [
+  'observed-before',
+  'observed-after',
+  'co-occurred',
+  'supersedes',
+];
+
+export const CAUSAL_RELATIONS: readonly LinkRelation[] = [
+  'caused-by',
+  'led-to',
+  'broke',
+  'enabled',
+  'prevented',
+];
+
+export const ENTITY_RELATIONS: readonly LinkRelation[] = [
+  'uses',
+  'part-of',
+  'interacts-with',
+  'contradicts',
+  'created-by',
+];

package/src/types/knowledge.ts

@@ -0,0 +1,388 @@
+import { z } from 'zod';
+
+// ============================================================================
+// Link Relations (organized by graph layer)
+// ============================================================================
+
+/** Semantic layer relations */
+const SemanticRelations = [
+  'related-to',
+  'depends-on',
+  'specializes',
+  'generalizes',
+  'supports',
+] as const;
+
+/** Temporal layer relations */
+const TemporalRelations = [
+  'observed-before',
+  'observed-after',
+  'co-occurred',
+  'supersedes',
+] as const;
+
+/** Causal layer relations */
+const CausalRelations = [
+  'caused-by',
+  'led-to',
+  'broke',
+  'enabled',
+  'prevented',
+] as const;
+
+/** Entity layer relations */
+const EntityRelations = [
+  'uses',
+  'part-of',
+  'interacts-with',
+  'contradicts',
+  'created-by',
+] as const;
+
+export const AllLinkRelations = [
+  ...SemanticRelations,
+  ...TemporalRelations,
+  ...CausalRelations,
+  ...EntityRelations,
+] as const;
+
+export const LinkRelationSchema = z.enum(AllLinkRelations);
+export type LinkRelation = z.infer<typeof LinkRelationSchema>;
+
+/** Map relation to its natural graph layer */
+export function inferLayerFromRelation(
+  relation: LinkRelation
+): 'semantic' | 'temporal' | 'causal' | 'entity' {
+  if ((SemanticRelations as readonly string[]).includes(relation))
+    return 'semantic';
+  if ((TemporalRelations as readonly string[]).includes(relation))
+    return 'temporal';
+  if ((CausalRelations as readonly string[]).includes(relation))
+    return 'causal';
+  return 'entity';
+}
+
+// ============================================================================
+// Note Types
+// ============================================================================
+
+export const NoteTypeSchema = z.enum([
+  'observation',
+  'entity',
+  'domain-summary',
+]);
+export type NoteType = z.infer<typeof NoteTypeSchema>;
+
+export const SourceOriginSchema = z.enum([
+  'extracted',
+  'agent-authored',
+  'imported',
+]);
+export type SourceOrigin = z.infer<typeof SourceOriginSchema>;
+
+export const GraphLayerNameSchema = z.enum([
+  'semantic',
+  'temporal',
+  'causal',
+  'entity',
+]);
+export type GraphLayerName = z.infer<typeof GraphLayerNameSchema>;
+
+// ============================================================================
+// Knowledge Note Frontmatter Schema
+// ============================================================================
+
+export const KnowledgeLinkSchema = z.object({
+  target: z.string(),
+  relation: LinkRelationSchema,
+  layer: GraphLayerNameSchema.optional(),
+});
+export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>;
+
+export const KnowledgeSourceSchema = z.object({
+  origin: SourceOriginSchema,
+  trajectories: z.array(z.string()).optional(),
+  playbooks: z.array(z.string()).optional(),
+  agentId: z.string().optional(),
+});
+export type KnowledgeSource = z.infer<typeof KnowledgeSourceSchema>;
+
+export const KnowledgeNoteFrontmatterSchema = z.object({
+  /** Unique identifier (kebab-case, prefixed with k- for observations) */
+  id: z.string(),
+  /** Note type determines organization and lifecycle */
+  type: NoteTypeSchema,
+  /** Knowledge domains this note belongs to */
+  domain: z.array(z.string()).default([]),
+  /** Specific entities (tools, libraries, patterns) referenced */
+  entities: z.array(z.string()).default([]),
+  /** Freeform tags for additional categorization */
+  tags: z.array(z.string()).default([]),
+  /** Confidence in this knowledge (0-1) */
+  confidence: z.number().min(0).max(1).default(0.5),
+  /** Where this knowledge came from */
+  source: KnowledgeSourceSchema,
+  /** Explicit links to other knowledge notes */
+  links: z.array(KnowledgeLinkSchema).default([]),
+  /** ISO 8601 creation timestamp */
+  created: z.string(),
+  /** ISO 8601 last updated timestamp */
+  updated: z.string(),
+  /** If this note replaces a previous one (contradiction resolution) */
+  supersedes: z.string().nullable().optional(),
+});
+
+export type KnowledgeNoteFrontmatter = z.infer<
+  typeof KnowledgeNoteFrontmatterSchema
+>;
+
+// ============================================================================
+// Knowledge Note (frontmatter + body + file path)
+// ============================================================================
+
+export interface KnowledgeNote {
+  /** Parsed frontmatter */
+  frontmatter: KnowledgeNoteFrontmatter;
+  /** Markdown body content (after frontmatter) */
+  body: string;
+  /** Resolved file path (derived from type + name, not stored in frontmatter) */
+  filePath: string;
+}
+
+// ============================================================================
+// Search & Retrieval
+// ============================================================================
+
+export interface KnowledgeMatch {
+  note: KnowledgeNote;
+  score: number;
+  matchType?: 'domain' | 'entity' | 'semantic' | 'graph';
+}
+
+// ============================================================================
+// Extraction & Evolution Types (used in Phase 2-3, defined now for stability)
+// ============================================================================
+
+export interface EntityUpdate {
+  /** Entity note ID to update */
+  entityId: string;
+  /** Section to append */
+  section: string;
+  /** Evidence source trajectory ID */
+  trajectoryId: string;
+}
+
+export interface Contradiction {
+  /** Existing note that is contradicted */
+  existingNoteId: string;
+  /** New observation that contradicts it */
+  newObservation: KnowledgeNote;
+  /** How they conflict */
+  conflictDescription: string;
+  /** Recommendation */
+  resolution: 'supersede' | 'coexist' | 'review';
+}
+
+export interface PlaybookLink {
+  /** Knowledge note ID */
+  noteId: string;
+  /** Playbook ID */
+  playbookId: string;
+  /** Relationship direction */
+  relation: 'supports' | 'contradicts' | 'contextualizes';
+}
+
+export interface NewLink {
+  from: string;
+  to: string;
+  relation: LinkRelation;
+  layer?: GraphLayerName;
+  weight?: number;
+}
+
+export interface ExtractedKnowledge {
+  /** New observations to create */
+  observations: KnowledgeNote[];
+  /** Updates to existing entity notes (append sections) */
+  entityUpdates: EntityUpdate[];
+  /** Contradictions detected with existing knowledge */
+  contradictions: Contradiction[];
+  /** New links to add to the graph */
+  links: NewLink[];
+  /** Cross-references to playbooks */
+  playbookLinks: PlaybookLink[];
+}
+
+// ============================================================================
+// Lifecycle Result Types
+// ============================================================================
+
+export interface InboxResult {
+  /** Total files processed */
+  processed: number;
+  /** Files that failed to parse/move */
+  failed: number;
+  /** Files moved to observations/ */
+  movedToObservations: number;
+  /** Files moved to entities/ */
+  movedToEntities: number;
+  /** Files moved to domains/ */
+  movedToDomains: number;
+}
+
+export interface DefragResult {
+  /** Inbox processing results */
+  inbox: InboxResult;
+  /** Number of observations consolidated into entity notes */
+  consolidated: number;
+  /** Number of contradictions detected */
+  contradictions: number;
+  /** Whether the graph was rebuilt */
+  graphRebuilt: boolean;
+  /** Number of domain summaries regenerated */
+  domainSummariesRegenerated: number;
+  /** Decay results */
+  decay: DecayResult;
+}
+
+export interface DecayResult {
+  /** Notes with reduced confidence */
+  decayed: number;
+  /** Notes newly marked as stale */
+  newlyStale: number;
+  /** Notes already marked stale */
+  alreadyStale: number;
+}
+
+// ============================================================================
+// Knowledge Bank Stats
+// ============================================================================
+
+export interface KnowledgeStats {
+  observationCount: number;
+  entityCount: number;
+  domainCount: number;
+  inboxCount: number;
+  graph: {
+    nodeCount: number;
+    edgeCountByLayer: Record<string, number>;
+    enabledLayers: string[];
+  };
+  avgConfidence: number;
+  staleCount: number;
+  domainBreakdown: Record<string, number>;
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+let noteCounter = 0;
+
+function generateNoteId(prefix: string): string {
+  const timestamp = Date.now().toString(36);
+  const counter = (noteCounter++).toString(36);
+  return `${prefix}-${timestamp}-${counter}`;
+}
+
+/**
+ * Create a new observation note
+ */
+export function createObservation(input: {
+  id?: string;
+  title: string;
+  body: string;
+  domain: string[];
+  entities: string[];
+  tags?: string[];
+  confidence?: number;
+  source: KnowledgeSource;
+  links?: KnowledgeLink[];
+}): KnowledgeNote {
+  const now = new Date().toISOString();
+  const id = input.id ?? generateNoteId('k');
+
+  return {
+    frontmatter: {
+      id,
+      type: 'observation',
+      domain: input.domain,
+      entities: input.entities,
+      tags: input.tags ?? [],
+      confidence: input.confidence ?? 0.3,
+      source: input.source,
+      links: input.links ?? [],
+      created: now,
+      updated: now,
+      supersedes: null,
+    },
+    body: `# ${input.title}\n\n${input.body}`,
+    filePath: `knowledge/observations/${id}.md`,
+  };
+}
+
+/**
+ * Create a new entity note
+ */
+export function createEntityNote(input: {
+  entityName: string;
+  body: string;
+  domain: string[];
+  tags?: string[];
+  confidence?: number;
+  source: KnowledgeSource;
+  links?: KnowledgeLink[];
+}): KnowledgeNote {
+  const now = new Date().toISOString();
+  const slug = input.entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+
+  return {
+    frontmatter: {
+      id: slug,
+      type: 'entity',
+      domain: input.domain,
+      entities: [input.entityName],
+      tags: input.tags ?? [],
+      confidence: input.confidence ?? 0.5,
+      source: input.source,
+      links: input.links ?? [],
+      created: now,
+      updated: now,
+      supersedes: null,
+    },
+    body: `# ${input.entityName}\n\n${input.body}`,
+    filePath: `knowledge/entities/${slug}.md`,
+  };
+}
+
+/**
+ * Create a new domain summary note
+ */
+export function createDomainSummary(input: {
+  domainName: string;
+  body: string;
+  entities?: string[];
+  tags?: string[];
+  source: KnowledgeSource;
+}): KnowledgeNote {
+  const now = new Date().toISOString();
+  const slug = input.domainName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+
+  return {
+    frontmatter: {
+      id: slug,
+      type: 'domain-summary',
+      domain: [input.domainName],
+      entities: input.entities ?? [],
+      tags: input.tags ?? [],
+      confidence: 1.0,
+      source: input.source,
+      links: [],
+      created: now,
+      updated: now,
+      supersedes: null,
+    },
+    body: `# ${input.domainName}\n\n${input.body}`,
+    filePath: `knowledge/domains/${slug}.md`,
+  };
+}