cognitive-core 0.2.5 → 0.3.1

package/dist/experimental/healing-orchestrator.js

@@ -0,0 +1,250 @@
+/**
+ * HealingOrchestrator — Plug-in anomaly detection and repair pattern.
+ *
+ * Inspired by ruvector's HealingOrchestrator (ruvector-dag/healing/orchestrator.rs).
+ * Runs registered anomaly detectors and repair strategies in each maintenance
+ * cycle. Detectors and strategies are push-registered via add methods.
+ *
+ * The orchestrator itself has no internal timer — `runCycle()` is called
+ * explicitly by the MaintenanceScheduler or manually by the caller.
+ */
+/**
+ * HealingOrchestrator — coordinates anomaly detection and repair.
+ */
+export class HealingOrchestrator {
+    detectors = [];
+    strategies = [];
+    cycleHistory = [];
+    maxHistorySize;
+    constructor(options) {
+        this.maxHistorySize = options?.maxHistorySize ?? 20;
+    }
+    /**
+     * Register an anomaly detector.
+     */
+    addDetector(detector) {
+        // Replace existing detector with same name
+        this.detectors = this.detectors.filter((d) => d.name !== detector.name);
+        this.detectors.push(detector);
+    }
+    /**
+     * Unregister an anomaly detector by name.
+     */
+    removeDetector(name) {
+        this.detectors = this.detectors.filter((d) => d.name !== name);
+    }
+    /**
+     * Register a repair strategy.
+     */
+    addRepairStrategy(strategy) {
+        this.strategies = this.strategies.filter((s) => s.name !== strategy.name);
+        this.strategies.push(strategy);
+    }
+    /**
+     * Unregister a repair strategy by name.
+     */
+    removeRepairStrategy(name) {
+        this.strategies = this.strategies.filter((s) => s.name !== name);
+    }
+    /**
+     * Run a healing cycle.
+     *
+     * 1. Runs all registered detectors to find anomalies
+     * 2. For each anomaly, finds the first matching repair strategy
+     * 3. Executes the repair
+     */
+    async runCycle(context) {
+        const start = Date.now();
+        const anomalies = [];
+        const repairs = [];
+        // Phase 1: Detection
+        for (const detector of this.detectors) {
+            try {
+                const detected = await detector.detect(context);
+                anomalies.push(...detected);
+            }
+            catch (error) {
+                // Non-critical — log but continue
+                anomalies.push({
+                    type: 'detector-error',
+                    severity: 'low',
+                    description: `Detector '${detector.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
+                    detectorName: detector.name,
+                });
+            }
+        }
+        // Sort by severity (high first)
+        const severityOrder = { high: 0, medium: 1, low: 2 };
+        anomalies.sort((a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3));
+        // Phase 2: Repair
+        for (const anomaly of anomalies) {
+            // Skip detector errors (not repairable)
+            if (anomaly.type === 'detector-error')
+                continue;
+            for (const strategy of this.strategies) {
+                if (!strategy.canRepair(anomaly))
+                    continue;
+                const repairStart = Date.now();
+                try {
+                    const result = await strategy.repair(anomaly, context);
+                    repairs.push(result);
+                }
+                catch (error) {
+                    repairs.push({
+                        success: false,
+                        action: `Failed: ${error instanceof Error ? error.message : String(error)}`,
+                        strategyName: strategy.name,
+                        durationMs: Date.now() - repairStart,
+                    });
+                }
+                // Only apply first matching strategy per anomaly
+                break;
+            }
+        }
+        const result = {
+            anomaliesDetected: anomalies,
+            repairs,
+            durationMs: Date.now() - start,
+            timestamp: new Date(),
+        };
+        this.cycleHistory.push(result);
+        if (this.cycleHistory.length > this.maxHistorySize) {
+            this.cycleHistory.shift();
+        }
+        return result;
+    }
+    /**
+     * Get cycle history for diagnostics.
+     */
+    getCycleHistory() {
+        return this.cycleHistory;
+    }
+    /**
+     * Get registered detectors.
+     */
+    getDetectors() {
+        return this.detectors;
+    }
+    /**
+     * Get registered repair strategies.
+     */
+    getRepairStrategies() {
+        return this.strategies;
+    }
+}
+/**
+ * Create a HealingOrchestrator.
+ */
+export function createHealingOrchestrator(options) {
+    return new HealingOrchestrator(options);
+}
+// =========================================================================
+// Built-in Detectors
+// =========================================================================
+/**
+ * Detects when playbook success rates are consistently low,
+ * suggesting playbook drift.
+ */
+export class PlaybookDriftDetector {
+    name = 'playbook-drift';
+    threshold;
+    constructor(threshold = 0.3) {
+        this.threshold = threshold;
+    }
+    async detect(context) {
+        const anomalies = [];
+        if (context.recentSuccessRate < this.threshold &&
+            context.playbookCount > 0 &&
+            context.trajectoriesProcessed >= 5) {
+            anomalies.push({
+                type: 'playbook-drift',
+                severity: 'medium',
+                description: `Recent success rate (${(context.recentSuccessRate * 100).toFixed(0)}%) is below threshold (${(this.threshold * 100).toFixed(0)}%) with ${context.playbookCount} playbooks available`,
+                detectorName: this.name,
+                data: {
+                    successRate: context.recentSuccessRate,
+                    playbookCount: context.playbookCount,
+                },
+            });
+        }
+        return anomalies;
+    }
+}
+/**
+ * Detects when the experience store is growing beyond capacity,
+ * suggesting aggressive pruning is needed.
+ */
+export class MemoryBloatDetector {
+    name = 'memory-bloat';
+    maxExperiences;
+    warningRatio;
+    constructor(maxExperiences = 1000, warningRatio = 0.9) {
+        this.maxExperiences = maxExperiences;
+        this.warningRatio = warningRatio;
+    }
+    async detect(context) {
+        const anomalies = [];
+        if (this.maxExperiences > 0 &&
+            context.experienceCount >= this.maxExperiences * this.warningRatio) {
+            const severity = context.experienceCount >= this.maxExperiences ? 'high' : 'medium';
+            anomalies.push({
+                type: 'memory-bloat',
+                severity,
+                description: `Experience count (${context.experienceCount}) is ${severity === 'high' ? 'at' : 'approaching'} capacity (${this.maxExperiences})`,
+                detectorName: this.name,
+                data: {
+                    experienceCount: context.experienceCount,
+                    maxExperiences: this.maxExperiences,
+                },
+            });
+        }
+        return anomalies;
+    }
+}
+/**
+ * Detects when a custom metric exceeds a Z-score threshold,
+ * inspired by ruvector's Z-score-based outlier detection.
+ */
+export class MetricDriftDetector {
+    name;
+    metricKey;
+    history = [];
+    windowSize;
+    zThreshold;
+    constructor(metricKey, options) {
+        this.name = `metric-drift:${metricKey}`;
+        this.metricKey = metricKey;
+        this.windowSize = options?.windowSize ?? 20;
+        this.zThreshold = options?.zThreshold ?? 2.0;
+    }
+    async detect(context) {
+        const value = context.metrics[this.metricKey];
+        if (value === undefined)
+            return [];
+        this.history.push(value);
+        if (this.history.length > this.windowSize) {
+            this.history.shift();
+        }
+        if (this.history.length < 3)
+            return [];
+        const mean = this.history.reduce((s, v) => s + v, 0) / this.history.length;
+        const variance = this.history.reduce((s, v) => s + (v - mean) ** 2, 0) / this.history.length;
+        const std = Math.sqrt(variance);
+        if (std === 0)
+            return [];
+        const zScore = Math.abs(value - mean) / std;
+        if (zScore >= this.zThreshold) {
+            return [
+                {
+                    type: 'metric-drift',
+                    severity: zScore >= this.zThreshold * 1.5 ? 'high' : 'medium',
+                    description: `Metric '${this.metricKey}' value ${value.toFixed(2)} has z-score ${zScore.toFixed(2)} (threshold: ${this.zThreshold})`,
+                    detectorName: this.name,
+                    data: { metricKey: this.metricKey, value, zScore, mean, std },
+                },
+            ];
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=healing-orchestrator.js.map

package/dist/experimental/healing-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healing-orchestrator.js","sourceRoot":"","sources":["../../src/experimental/healing-orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/experimental/knowledge-graph-types.d.ts

@@ -0,0 +1,148 @@
+import type { GraphLayerName, KnowledgeNote, LinkRelation } from '../types/knowledge.js';
+export interface GraphNode {
+    /** Knowledge note ID */
+    id: string;
+    /** Relative file path from memory root */
+    file: string;
+    /** Note type */
+    type: 'observation' | 'entity' | 'domain-summary' | 'convention';
+    /** 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;
+}
+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;
+}
+export interface GraphLayer {
+    /** Layer identifier */
+    name: GraphLayerName;
+    /** Whether this layer is currently enabled */
+    enabled: boolean;
+    /** Edges in this layer */
+    edges: GraphEdge[];
+}
+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>;
+}
+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;
+}
+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[];
+    };
+}
+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 declare const DEFAULT_GRAPH_CONFIG: GraphConfig;
+export declare const SEMANTIC_RELATIONS: readonly LinkRelation[];
+export declare const TEMPORAL_RELATIONS: readonly LinkRelation[];
+export declare const CAUSAL_RELATIONS: readonly LinkRelation[];
+export declare const ENTITY_RELATIONS: readonly LinkRelation[];
+//# sourceMappingURL=knowledge-graph-types.d.ts.map

package/dist/experimental/knowledge-graph-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph-types.d.ts","sourceRoot":"","sources":["../../src/experimental/knowledge-graph-types.ts"],"names":[],"mappings":"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"}

package/dist/experimental/knowledge-graph-types.js

@@ -0,0 +1,40 @@
+/** Default graph configuration */
+export const DEFAULT_GRAPH_CONFIG = {
+    enabledLayers: ['semantic'],
+    inferTemporalEdges: true,
+    inferCausalEdges: true,
+    inferEntityEdges: true,
+    domainSplitThreshold: 500,
+    sqlitePromotionThreshold: 10000,
+};
+// ============================================================================
+// Valid relation sets per layer (for layer implementations)
+// ============================================================================
+export const SEMANTIC_RELATIONS = [
+    'related-to',
+    'depends-on',
+    'specializes',
+    'generalizes',
+    'supports',
+];
+export const TEMPORAL_RELATIONS = [
+    'observed-before',
+    'observed-after',
+    'co-occurred',
+    'supersedes',
+];
+export const CAUSAL_RELATIONS = [
+    'caused-by',
+    'led-to',
+    'broke',
+    'enabled',
+    'prevented',
+];
+export const ENTITY_RELATIONS = [
+    'uses',
+    'part-of',
+    'interacts-with',
+    'contradicts',
+    'created-by',
+];
+//# sourceMappingURL=knowledge-graph-types.js.map

package/dist/experimental/knowledge-graph-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph-types.js","sourceRoot":"","sources":["../../src/experimental/knowledge-graph-types.ts"],"names":[],"mappings":"AAuMA,kCAAkC;AAClC,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,aAAa,EAAE,CAAC,UAAU,CAAC;IAC3B,kBAAkB,EAAE,IAAI;IACxB,gBAAgB,EAAE,IAAI;IACtB,gBAAgB,EAAE,IAAI;IACtB,oBAAoB,EAAE,GAAG;IACzB,wBAAwB,EAAE,KAAK;CAChC,CAAC;AAEF,+EAA+E;AAC/E,4DAA4D;AAC5D,+EAA+E;AAE/E,MAAM,CAAC,MAAM,kBAAkB,GAA4B;IACzD,YAAY;IACZ,YAAY;IACZ,aAAa;IACb,aAAa;IACb,UAAU;CACX,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAA4B;IACzD,iBAAiB;IACjB,gBAAgB;IAChB,aAAa;IACb,YAAY;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAA4B;IACvD,WAAW;IACX,QAAQ;IACR,OAAO;IACP,SAAS;IACT,WAAW;CACZ,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAA4B;IACvD,MAAM;IACN,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;CACb,CAAC"}

package/dist/experimental/knowledge-graph.d.ts

@@ -0,0 +1,41 @@
+import type { GraphNode, GraphEdge, GraphLayerOperations, GraphNodeFilter, NeighborOptions, KnowledgeGraphManagerInterface, GraphConfig } from './knowledge-graph-types.js';
+import type { GraphLayerName, KnowledgeNote } from '../types/knowledge.js';
+/**
+ * KnowledgeGraphManager
+ *
+ * Manages a multi-layer graph overlay over the knowledge note filesystem.
+ * All layers share the same node set. Each layer maintains its own edges.
+ * The graph is a derived index — it can be rebuilt from frontmatter.
+ */
+export declare class KnowledgeGraphManager implements KnowledgeGraphManagerInterface {
+    private nodes;
+    private layers;
+    private config;
+    constructor(config?: Partial<GraphConfig>);
+    private initLayers;
+    getLayer(name: GraphLayerName): GraphLayerOperations | null;
+    addNode(node: GraphNode): void;
+    removeNode(nodeId: string): void;
+    getNode(nodeId: string): GraphNode | undefined;
+    getAllNodes(): GraphNode[];
+    neighbors(nodeId: string, options?: NeighborOptions): GraphNode[];
+    pathBetween(fromId: string, toId: string, options?: {
+        layers?: GraphLayerName[];
+    }): Array<{
+        node: GraphNode;
+        edge: GraphEdge;
+        layer: GraphLayerName;
+    }> | null;
+    filterNodes(filter: GraphNodeFilter): GraphNode[];
+    crossSystemLinks(nodeId: string): GraphEdge[];
+    rebuildAll(notes: KnowledgeNote[]): void;
+    private noteToGraphNode;
+    loadFromDisk(dir: string): Promise<void>;
+    saveToDisk(dir: string): Promise<void>;
+    getStats(): {
+        nodeCount: number;
+        edgeCountByLayer: Record<string, number>;
+        enabledLayers: string[];
+    };
+}
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/experimental/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../../src/experimental/knowledge-graph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,8BAA8B,EAC9B,WAAW,EACZ,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAQ3E;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,8BAA8B;IAC1E,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,MAAM,CAAmD;IACjE,OAAO,CAAC,MAAM,CAAc;gBAEhB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAKzC,OAAO,CAAC,UAAU;IAWlB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,GAAG,IAAI;IAQ3D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAWhC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI9C,WAAW,IAAI,SAAS,EAAE;IAM1B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,EAAE;IA0CjE,WAAW,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;KAAE,GACtC,KAAK,CAAC;QACP,IAAI,EAAE,SAAS,CAAC;QAChB,IAAI,EAAE,SAAS,CAAC;QAChB,KAAK,EAAE,cAAc,CAAC;KACvB,CAAC,GAAG,IAAI;IAgET,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,EAAE;IAejD,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IAc7C,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI;IAexC,OAAO,CAAC,eAAe;IAejB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB5C,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB;CAiBF"}