cognitive-core 0.1.0 → 0.2.0

package/dist/memory/candidate-retrieval.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared candidate retrieval helper for memory stores.
+ *
+ * Consolidates the "inverted index narrow → fallback to full scan" pattern
+ * used by ExperienceMemory, PlaybookLibrary, and CausalStore.
+ */
+import type { InvertedIndex } from '../embeddings/inverted-index.js';
+/**
+ * A store-like interface that can resolve items by ID or return all values.
+ */
+export interface ItemResolver<T> {
+    get(id: string): T | undefined;
+    values(): T[];
+}
+/**
+ * Options for candidate retrieval.
+ */
+export interface CandidateRetrievalOptions {
+    /** How many final results are desired */
+    k: number;
+    /** Multiplier for how many candidates to pull from the index (default: 10) */
+    candidateMultiplier?: number;
+    /** Minimum candidate pool from index (default: 50) */
+    minCandidates?: number;
+}
+/**
+ * Retrieve candidates using an inverted index with fallback to full scan.
+ *
+ * This pattern is shared across multiple memory stores:
+ * 1. Use the inverted index to narrow to a candidate set.
+ * 2. If enough candidates are found, resolve them by ID.
+ * 3. Otherwise, fall back to the provided fallback set (or full store scan).
+ *
+ * @param query - The text query to search with.
+ * @param index - The inverted index for candidate narrowing.
+ * @param resolver - Store that can resolve items by ID or return all values.
+ * @param options - Retrieval options.
+ * @param fallbackItems - Optional pre-filtered fallback items. If not provided,
+ *   `resolver.values()` is used.
+ * @returns The candidate items to score.
+ */
+export declare function getCandidates<T>(query: string, index: InvertedIndex, resolver: ItemResolver<T>, options: CandidateRetrievalOptions, fallbackItems?: T[]): T[];
+//# sourceMappingURL=candidate-retrieval.d.ts.map

package/dist/memory/candidate-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-retrieval.d.ts","sourceRoot":"","sources":["../../src/memory/candidate-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC/B,MAAM,IAAI,CAAC,EAAE,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,yCAAyC;IACzC,CAAC,EAAE,MAAM,CAAC;IACV,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,OAAO,EAAE,yBAAyB,EAClC,aAAa,CAAC,EAAE,CAAC,EAAE,GAClB,CAAC,EAAE,CAmBL"}

package/dist/memory/candidate-retrieval.js

@@ -0,0 +1,41 @@
+/**
+ * Shared candidate retrieval helper for memory stores.
+ *
+ * Consolidates the "inverted index narrow → fallback to full scan" pattern
+ * used by ExperienceMemory, PlaybookLibrary, and CausalStore.
+ */
+/**
+ * Retrieve candidates using an inverted index with fallback to full scan.
+ *
+ * This pattern is shared across multiple memory stores:
+ * 1. Use the inverted index to narrow to a candidate set.
+ * 2. If enough candidates are found, resolve them by ID.
+ * 3. Otherwise, fall back to the provided fallback set (or full store scan).
+ *
+ * @param query - The text query to search with.
+ * @param index - The inverted index for candidate narrowing.
+ * @param resolver - Store that can resolve items by ID or return all values.
+ * @param options - Retrieval options.
+ * @param fallbackItems - Optional pre-filtered fallback items. If not provided,
+ *   `resolver.values()` is used.
+ * @returns The candidate items to score.
+ */
+export function getCandidates(query, index, resolver, options, fallbackItems) {
+    const multiplier = options.candidateMultiplier ?? 10;
+    const minCandidates = options.minCandidates ?? 50;
+    const maxCandidates = Math.max(options.k * multiplier, minCandidates);
+    const candidateIds = index.getCandidates(query, maxCandidates);
+    if (candidateIds.length >= options.k) {
+        // Enough candidates from index — resolve them
+        const items = [];
+        for (const id of candidateIds) {
+            const item = resolver.get(id);
+            if (item)
+                items.push(item);
+        }
+        return items;
+    }
+    // Too few candidates — fall back
+    return fallbackItems ?? resolver.values();
+}
+//# sourceMappingURL=candidate-retrieval.js.map

package/dist/memory/candidate-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-retrieval.js","sourceRoot":"","sources":["../../src/memory/candidate-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,KAAoB,EACpB,QAAyB,EACzB,OAAkC,EAClC,aAAmB;IAEnB,MAAM,UAAU,GAAG,OAAO,CAAC,mBAAmB,IAAI,EAAE,CAAC;IACrD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAClD,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,UAAU,EAAE,aAAa,CAAC,CAAC;IAEtE,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAE/D,IAAI,YAAY,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;QACrC,8CAA8C;QAC9C,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iCAAiC;IACjC,OAAO,aAAa,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC5C,CAAC"}

package/dist/memory/causal-store.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CausalStore — First-class queryable store for causal relationships.
+ *
+ * Promotes causal edges (cause → effect) extracted from trajectories
+ * to a searchable store backed by SqlitePersistence + InvertedIndex.
+ *
+ * Supports:
+ * - Similarity search on cause/effect descriptions
+ * - Chain traversal (walk from one edge to connected edges)
+ * - Domain-scoped retrieval
+ * - Confidence-weighted deduplication (same pattern seen multiple times)
+ */
+import type { SqlitePersistence } from '../persistence/index.js';
+/**
+ * A causal edge: cause → effect with evidence
+ */
+export interface CausalEdge {
+    id: string;
+    /** Description of the cause */
+    cause: string;
+    /** Description of the effect */
+    effect: string;
+    /** Confidence in this causal relationship (0-1) */
+    confidence: number;
+    /** Domain this edge belongs to */
+    domain: string;
+    /** Trajectory IDs that provide evidence for this edge */
+    sourceTrajectoryIds: string[];
+    /** How many times this pattern was observed */
+    observedCount: number;
+    /** When this edge was first created */
+    createdAt: Date;
+    /** When this edge was last updated */
+    updatedAt: Date;
+}
+/**
+ * CausalStore — queryable store for causal relationships
+ */
+export declare class CausalStore {
+    private persistence;
+    private index;
+    private initialized;
+    private _resolver;
+    constructor(persistence: SqlitePersistence);
+    init(): Promise<void>;
+    /**
+     * Add a causal edge. If a similar edge already exists (same cause+effect
+     * pattern above similarity threshold), merge by incrementing observedCount
+     * and boosting confidence.
+     */
+    add(edge: CausalEdge): Promise<void>;
+    /**
+     * Find causal edges similar to a query string.
+     */
+    findSimilar(query: string, options?: {
+        k?: number;
+    }): Promise<CausalEdge[]>;
+    /**
+     * Get a chain of causal edges starting from a given edge ID.
+     * Follows effect → cause links by text similarity.
+     */
+    getChain(startId: string, maxDepth?: number): Promise<CausalEdge[]>;
+    /**
+     * Get all causal edges for a domain.
+     */
+    getByDomain(domain: string): Promise<CausalEdge[]>;
+    /**
+     * Get a single edge by ID.
+     */
+    get(id: string): Promise<CausalEdge | undefined>;
+    /**
+     * Get all edges.
+     */
+    getAll(): Promise<CausalEdge[]>;
+    /**
+     * Get total count.
+     */
+    count(): Promise<number>;
+    /**
+     * Close the store (no-op — SqlitePersistence lifecycle is managed externally).
+     */
+    close(): Promise<void>;
+    /**
+     * Find an existing edge that matches the new one (for merging).
+     * Uses high similarity threshold on both cause AND effect.
+     */
+    private findExistingMatch;
+    /**
+     * Synchronous helper: get all edges from SQLite.
+     */
+    private getAllSync;
+}
+/**
+ * Create a CausalStore instance
+ */
+export declare function createCausalStore(persistence: SqlitePersistence): CausalStore;
+//# sourceMappingURL=causal-store.d.ts.map

package/dist/memory/causal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-store.d.ts","sourceRoot":"","sources":["../../src/memory/causal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,yBAAyB,CAAC;AAMhF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,IAAI,CAAC;CACjB;AAmBD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAA2B;gBAEhC,WAAW,EAAE,iBAAiB;IAWpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;;;OAIG;IACG,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B1C;;OAEG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GACvB,OAAO,CAAC,UAAU,EAAE,CAAC;IA0BxB;;;OAGG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,QAAQ,SAAI,GACX,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCxB;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAKxD;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAMtD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAKrC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,iBAAiB,GAAG,WAAW,CAE7E"}

package/dist/memory/causal-store.js

@@ -0,0 +1,209 @@
+/**
+ * CausalStore — First-class queryable store for causal relationships.
+ *
+ * Promotes causal edges (cause → effect) extracted from trajectories
+ * to a searchable store backed by SqlitePersistence + InvertedIndex.
+ *
+ * Supports:
+ * - Similarity search on cause/effect descriptions
+ * - Chain traversal (walk from one edge to connected edges)
+ * - Domain-scoped retrieval
+ * - Confidence-weighted deduplication (same pattern seen multiple times)
+ */
+import { fromJSON, fromISO } from '../persistence/index.js';
+import { InvertedIndex } from '../embeddings/inverted-index.js';
+import { textSimilarity } from '../utils/similarity.js';
+import { getCandidates } from './candidate-retrieval.js';
+/**
+ * Convert a CausalEdgeRow to a CausalEdge.
+ */
+function rowToEdge(row) {
+    return {
+        id: row.id,
+        cause: row.cause,
+        effect: row.effect,
+        confidence: row.confidence,
+        domain: row.domain,
+        sourceTrajectoryIds: fromJSON(row.source_trajectory_ids, []),
+        observedCount: row.observed_count,
+        createdAt: fromISO(row.created_at) ?? new Date(),
+        updatedAt: fromISO(row.updated_at) ?? new Date(),
+    };
+}
+/**
+ * CausalStore — queryable store for causal relationships
+ */
+export class CausalStore {
+    persistence;
+    index = new InvertedIndex();
+    initialized = false;
+    _resolver;
+    constructor(persistence) {
+        this.persistence = persistence;
+        this._resolver = {
+            get: (id) => {
+                const row = this.persistence.getCausalEdge(id);
+                return row ? rowToEdge(row) : undefined;
+            },
+            values: () => this.getAllSync(),
+        };
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        // Build inverted index from all causal edges in DB
+        const ids = this.persistence.getCausalEdgeIds();
+        for (const { id, cause, effect } of ids) {
+            this.index.add(id, `${cause} ${effect}`);
+        }
+        this.initialized = true;
+    }
+    /**
+     * Add a causal edge. If a similar edge already exists (same cause+effect
+     * pattern above similarity threshold), merge by incrementing observedCount
+     * and boosting confidence.
+     */
+    async add(edge) {
+        await this.init();
+        // Check for existing similar edge to merge with
+        const existing = this.findExistingMatch(edge);
+        if (existing) {
+            // Merge: bump count, boost confidence, add trajectory evidence
+            existing.observedCount += 1;
+            existing.confidence = Math.min(1, existing.confidence + 0.05);
+            existing.updatedAt = new Date();
+            for (const tid of edge.sourceTrajectoryIds) {
+                if (!existing.sourceTrajectoryIds.includes(tid)) {
+                    existing.sourceTrajectoryIds.push(tid);
+                }
+            }
+            this.persistence.insertCausalEdge(existing); // Write-through
+        }
+        else {
+            // New edge
+            this.persistence.insertCausalEdge(edge);
+            this.index.add(edge.id, `${edge.cause} ${edge.effect}`);
+        }
+    }
+    /**
+     * Find causal edges similar to a query string.
+     */
+    async findSimilar(query, options) {
+        await this.init();
+        const k = options?.k ?? 5;
+        // Use shared candidate retrieval with inverted index
+        const candidates = getCandidates(query, this.index, this._resolver, { k, candidateMultiplier: 5, minCandidates: 30 });
+        // Score by similarity to both cause and effect
+        const scored = candidates.map((edge) => {
+            const causeSim = textSimilarity(query, edge.cause);
+            const effectSim = textSimilarity(query, edge.effect);
+            const combinedSim = textSimilarity(query, `${edge.cause} ${edge.effect}`);
+            return {
+                edge,
+                score: Math.max(causeSim, effectSim, combinedSim),
+            };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k).map((s) => s.edge);
+    }
+    /**
+     * Get a chain of causal edges starting from a given edge ID.
+     * Follows effect → cause links by text similarity.
+     */
+    async getChain(startId, maxDepth = 5) {
+        await this.init();
+        const startRow = this.persistence.getCausalEdge(startId);
+        if (!startRow)
+            return [];
+        const start = rowToEdge(startRow);
+        const chain = [start];
+        const visited = new Set([startId]);
+        let current = start;
+        for (let depth = 0; depth < maxDepth; depth++) {
+            // Find edges where cause is similar to current effect
+            const allEdges = this.getAllSync();
+            let bestMatch;
+            let bestScore = 0;
+            for (const edge of allEdges) {
+                if (visited.has(edge.id))
+                    continue;
+                const score = textSimilarity(current.effect, edge.cause);
+                if (score > bestScore && score > 0.4) {
+                    bestScore = score;
+                    bestMatch = edge;
+                }
+            }
+            if (!bestMatch)
+                break;
+            chain.push(bestMatch);
+            visited.add(bestMatch.id);
+            current = bestMatch;
+        }
+        return chain;
+    }
+    /**
+     * Get all causal edges for a domain.
+     */
+    async getByDomain(domain) {
+        await this.init();
+        return this.persistence.getCausalEdgesByDomain(domain).map(rowToEdge);
+    }
+    /**
+     * Get a single edge by ID.
+     */
+    async get(id) {
+        await this.init();
+        const row = this.persistence.getCausalEdge(id);
+        return row ? rowToEdge(row) : undefined;
+    }
+    /**
+     * Get all edges.
+     */
+    async getAll() {
+        await this.init();
+        return this.getAllSync();
+    }
+    /**
+     * Get total count.
+     */
+    async count() {
+        await this.init();
+        return this.persistence.getAllCausalEdges().length;
+    }
+    /**
+     * Close the store (no-op — SqlitePersistence lifecycle is managed externally).
+     */
+    async close() {
+        // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
+    }
+    /**
+     * Find an existing edge that matches the new one (for merging).
+     * Uses high similarity threshold on both cause AND effect.
+     */
+    findExistingMatch(newEdge) {
+        const MERGE_THRESHOLD = 0.7;
+        for (const edge of this.getAllSync()) {
+            if (edge.domain !== newEdge.domain)
+                continue;
+            const causeSim = textSimilarity(newEdge.cause, edge.cause);
+            const effectSim = textSimilarity(newEdge.effect, edge.effect);
+            if (causeSim >= MERGE_THRESHOLD && effectSim >= MERGE_THRESHOLD) {
+                return edge;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Synchronous helper: get all edges from SQLite.
+     */
+    getAllSync() {
+        return this.persistence.getAllCausalEdges().map(rowToEdge);
+    }
+}
+/**
+ * Create a CausalStore instance
+ */
+export function createCausalStore(persistence) {
+    return new CausalStore(persistence);
+}
+//# sourceMappingURL=causal-store.js.map

package/dist/memory/causal-store.js.map

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

package/dist/memory/coherence.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CoherenceChecker — Lightweight contradiction detection for knowledge insertion.
+ *
+ * Uses a simplified sheaf-inspired approach:
+ * 1. Filter existing notes to same entity/domain as new note
+ * 2. Compute text similarity between new and candidate notes
+ * 3. Detect sentiment conflicts using negation heuristics
+ * 4. residualEnergy = similarity × sentimentConflict
+ *
+ * This catches the common "note A says X, note B says not-X" failure mode
+ * without requiring full sheaf Laplacian math.
+ */
+import type { KnowledgeNote } from '../types/knowledge.js';
+/**
+ * Result of a coherence check
+ */
+export interface CoherenceResult {
+    isCoherent: boolean;
+    contradictions: Array<{
+        existingNoteId: string;
+        residualEnergy: number;
+        description: string;
+    }>;
+    globalEnergy: number;
+}
+/**
+ * Configuration for CoherenceChecker
+ */
+export interface CoherenceCheckerConfig {
+    /** Similarity threshold above which to check for contradictions (default: 0.4) */
+    contradictionThreshold?: number;
+    /** Max notes to compare against (default: 20) */
+    maxComparisons?: number;
+}
+/**
+ * CoherenceChecker — detects contradictions in accumulated knowledge
+ */
+export declare class CoherenceChecker {
+    private config;
+    constructor(config?: CoherenceCheckerConfig);
+    /**
+     * Check a new note against existing notes for contradictions.
+     */
+    check(newNote: KnowledgeNote, existingNotes: KnowledgeNote[]): Promise<CoherenceResult>;
+    /**
+     * Compute global coherence energy across a set of notes.
+     * Rising energy signals knowledge drift / growing contradictions.
+     *
+     * Energy = average pairwise sentimentConflict × similarity for same-domain notes.
+     */
+    computeGlobalEnergy(notes: KnowledgeNote[]): number;
+    /**
+     * Filter existing notes to those sharing entities or domains with the new note.
+     * Limits to maxComparisons most relevant candidates.
+     */
+    private filterCandidates;
+    /**
+     * Detect sentiment conflict between two texts using negation heuristics.
+     * Returns a score from 0 (no conflict) to 1 (direct contradiction).
+     */
+    private detectSentimentConflict;
+    /**
+     * Generate a human-readable description of the contradiction.
+     */
+    private describeContradiction;
+}
+/**
+ * Create a CoherenceChecker instance
+ */
+export declare function createCoherenceChecker(config?: CoherenceCheckerConfig): CoherenceChecker;
+//# sourceMappingURL=coherence.d.ts.map

package/dist/memory/coherence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coherence.d.ts","sourceRoot":"","sources":["../../src/memory/coherence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,KAAK,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAmC;gBAErC,MAAM,CAAC,EAAE,sBAAsB;IAO3C;;OAEG;IACG,KAAK,CACT,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,aAAa,EAAE,GAC7B,OAAO,CAAC,eAAe,CAAC;IA0C3B;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM;IAsCnD;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAkCxB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAuB/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAe9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,sBAAsB,GAC9B,gBAAgB,CAElB"}

package/dist/memory/coherence.js

@@ -0,0 +1,176 @@
+/**
+ * CoherenceChecker — Lightweight contradiction detection for knowledge insertion.
+ *
+ * Uses a simplified sheaf-inspired approach:
+ * 1. Filter existing notes to same entity/domain as new note
+ * 2. Compute text similarity between new and candidate notes
+ * 3. Detect sentiment conflicts using negation heuristics
+ * 4. residualEnergy = similarity × sentimentConflict
+ *
+ * This catches the common "note A says X, note B says not-X" failure mode
+ * without requiring full sheaf Laplacian math.
+ */
+import { textSimilarity } from '../utils/similarity.js';
+// Pairs of opposing patterns: [positive, negative]
+const NEGATION_PAIRS = [
+    [/\balways\b/i, /\bnever\b/i],
+    [/\bshould\b/i, /\bshould\s+not\b/i],
+    [/\buse\b/i, /\bavoid\b/i],
+    [/\bdo\b/i, /\bdon['']?t\b/i],
+    [/\benable\b/i, /\bdisable\b/i],
+    [/\binclude\b/i, /\bexclude\b/i],
+    [/\bprefer\b/i, /\bavoid\b/i],
+    [/\brequired\b/i, /\boptional\b/i],
+    [/\bsafe\b/i, /\bunsafe\b/i],
+    [/\bcorrect\b/i, /\bincorrect\b/i],
+    [/\bsuccessful\b/i, /\bfailed\b/i],
+];
+/**
+ * CoherenceChecker — detects contradictions in accumulated knowledge
+ */
+export class CoherenceChecker {
+    config;
+    constructor(config) {
+        this.config = {
+            contradictionThreshold: config?.contradictionThreshold ?? 0.4,
+            maxComparisons: config?.maxComparisons ?? 20,
+        };
+    }
+    /**
+     * Check a new note against existing notes for contradictions.
+     */
+    async check(newNote, existingNotes) {
+        // Filter to same entity/domain notes for scoped comparison
+        const candidates = this.filterCandidates(newNote, existingNotes);
+        const contradictions = [];
+        for (const existing of candidates) {
+            const similarity = textSimilarity(newNote.body, existing.body);
+            // Only check for contradictions when notes are topically similar
+            if (similarity < this.config.contradictionThreshold)
+                continue;
+            const sentimentConflict = this.detectSentimentConflict(newNote.body, existing.body);
+            if (sentimentConflict > 0) {
+                const residualEnergy = similarity * sentimentConflict;
+                if (residualEnergy > 0.2) {
+                    contradictions.push({
+                        existingNoteId: existing.frontmatter.id,
+                        residualEnergy,
+                        description: this.describeContradiction(newNote, existing),
+                    });
+                }
+            }
+        }
+        const globalEnergy = this.computeGlobalEnergy([
+            newNote,
+            ...candidates,
+        ]);
+        return {
+            isCoherent: contradictions.length === 0,
+            contradictions,
+            globalEnergy,
+        };
+    }
+    /**
+     * Compute global coherence energy across a set of notes.
+     * Rising energy signals knowledge drift / growing contradictions.
+     *
+     * Energy = average pairwise sentimentConflict × similarity for same-domain notes.
+     */
+    computeGlobalEnergy(notes) {
+        if (notes.length < 2)
+            return 0;
+        let totalEnergy = 0;
+        let pairCount = 0;
+        // Sample pairs to stay within performance budget
+        const maxPairs = 100;
+        const step = Math.max(1, Math.floor((notes.length * (notes.length - 1)) / (2 * maxPairs)));
+        for (let i = 0; i < notes.length; i += step) {
+            for (let j = i + 1; j < notes.length; j += step) {
+                if (pairCount >= maxPairs)
+                    break;
+                // Skip if no domain overlap
+                const domainOverlap = notes[i].frontmatter.domain.some((d) => notes[j].frontmatter.domain.includes(d));
+                if (!domainOverlap && notes[i].frontmatter.domain.length > 0 && notes[j].frontmatter.domain.length > 0) {
+                    continue;
+                }
+                const similarity = textSimilarity(notes[i].body, notes[j].body);
+                if (similarity < this.config.contradictionThreshold)
+                    continue;
+                const conflict = this.detectSentimentConflict(notes[i].body, notes[j].body);
+                totalEnergy += similarity * conflict;
+                pairCount++;
+            }
+            if (pairCount >= maxPairs)
+                break;
+        }
+        return pairCount > 0 ? totalEnergy / pairCount : 0;
+    }
+    /**
+     * Filter existing notes to those sharing entities or domains with the new note.
+     * Limits to maxComparisons most relevant candidates.
+     */
+    filterCandidates(newNote, existingNotes) {
+        const newEntities = new Set(newNote.frontmatter.entities);
+        const newDomains = new Set(newNote.frontmatter.domain);
+        // Prioritize entity overlap, then domain overlap
+        const withEntityOverlap = [];
+        const withDomainOverlap = [];
+        for (const note of existingNotes) {
+            // Skip same note
+            if (note.frontmatter.id === newNote.frontmatter.id)
+                continue;
+            const hasEntityOverlap = note.frontmatter.entities.some((e) => newEntities.has(e));
+            const hasDomainOverlap = note.frontmatter.domain.some((d) => newDomains.has(d));
+            if (hasEntityOverlap) {
+                withEntityOverlap.push(note);
+            }
+            else if (hasDomainOverlap) {
+                withDomainOverlap.push(note);
+            }
+        }
+        // Entity matches first, then domain matches
+        const candidates = [...withEntityOverlap, ...withDomainOverlap];
+        return candidates.slice(0, this.config.maxComparisons);
+    }
+    /**
+     * Detect sentiment conflict between two texts using negation heuristics.
+     * Returns a score from 0 (no conflict) to 1 (direct contradiction).
+     */
+    detectSentimentConflict(textA, textB) {
+        let conflictCount = 0;
+        for (const [positive, negative] of NEGATION_PAIRS) {
+            // Check if one text has the positive and the other has the negative
+            const aHasPositive = positive.test(textA);
+            const aHasNegative = negative.test(textA);
+            const bHasPositive = positive.test(textB);
+            const bHasNegative = negative.test(textB);
+            if ((aHasPositive && bHasNegative && !aHasNegative) ||
+                (aHasNegative && bHasPositive && !bHasNegative)) {
+                conflictCount++;
+            }
+        }
+        // Normalize: 1 match = moderate conflict, 2+ = strong
+        if (conflictCount === 0)
+            return 0;
+        return Math.min(1, conflictCount * 0.5);
+    }
+    /**
+     * Generate a human-readable description of the contradiction.
+     */
+    describeContradiction(newNote, existingNote) {
+        const newSummary = newNote.body.slice(0, 80).replace(/\n/g, ' ');
+        const existingSummary = existingNote.body.slice(0, 80).replace(/\n/g, ' ');
+        const entities = newNote.frontmatter.entities.length > 0
+            ? ` (entities: ${newNote.frontmatter.entities.join(', ')})`
+            : '';
+        return (`New note "${newSummary}..." contradicts ` +
+            `existing "${existingSummary}..."${entities}`);
+    }
+}
+/**
+ * Create a CoherenceChecker instance
+ */
+export function createCoherenceChecker(config) {
+    return new CoherenceChecker(config);
+}
+//# sourceMappingURL=coherence.js.map