cognitive-core 0.1.2 → 0.2.0

package/src/memory/experience.ts

@@ -1,6 +1,10 @@
 import type { Experience } from '../types/index.js';
-import { JsonStore } from '../utils/storage.js';
+import type { SqlitePersistence, ExperienceRow } from '../persistence/index.js';
+import { fromISO, fromInt, fromJSON, blobToEmbedding } from '../persistence/index.js';
+import { InvertedIndex } from '../embeddings/inverted-index.js';
 import { findTopK } from '../utils/similarity.js';
+import type { ReasoningBank } from './reasoning-bank.js';
+import { getCandidates, type ItemResolver } from './candidate-retrieval.js';
 
 /**
  * Result of pruning operation
@@ -22,34 +26,94 @@ export interface PruneResult {
   remainingCount: number;
 }
 
+/**
+ * Convert an ExperienceRow (SQLite representation) back to an Experience (domain type).
+ */
+function rowToExperience(row: ExperienceRow): Experience {
+  return {
+    id: row.id,
+    taskInput: row.task_input,
+    solutionOutput: row.solution_output,
+    feedback: row.feedback,
+    success: fromInt(row.success),
+    domain: row.domain,
+    embedding: blobToEmbedding(row.embedding),
+    trajectoryId: row.trajectory_id,
+    usageCount: row.usage_count,
+    accessScore: row.access_score,
+    retrievalCount: row.retrieval_count,
+    tier: row.tier as 'hot' | 'warm' | 'cold',
+    compressed: fromJSON(row.compressed),
+    metadata: fromJSON(row.metadata, {}),
+    createdAt: fromISO(row.created_at) ?? new Date(),
+    lastAccessedAt: fromISO(row.last_accessed_at),
+  };
+}
+
 /**
  * Experience Memory - ReMem-style task-level retrieval
  * Stores complete (task, solution, feedback) tuples
+ *
+ * Uses SqlitePersistence for storage and InvertedIndex
+ * for fast candidate narrowing before similarity scoring.
  */
 export class ExperienceMemory {
-  private _store: JsonStore<Experience>;
+  private persistence: SqlitePersistence;
+  private _index: InvertedIndex = new InvertedIndex();
   private initialized = false;
+  private _reasoningBank: ReasoningBank | null = null;
 
-  constructor(baseDir: string) {
-    this._store = new JsonStore<Experience>(baseDir, 'experiences', {
-      autoSaveInterval: 60000,
-      pretty: true,
-    });
+  /**
+   * ItemResolver adapter for getCandidates().
+   * Resolves items by ID from SQLite and returns all values.
+   */
+  private _resolver: ItemResolver<Experience>;
+
+  constructor(persistence: SqlitePersistence) {
+    this.persistence = persistence;
+    this._resolver = {
+      get: (id: string) => {
+        const row = this.persistence.getExperience(id);
+        return row ? rowToExperience(row) : undefined;
+      },
+      values: () => this.getAllSync(),
+    };
   }
 
   async init(): Promise<void> {
     if (this.initialized) return;
-    await this._store.init();
+
+    // Build inverted index from all experiences in DB
+    const ids = this.persistence.getExperienceIds();
+    for (const { id, task_input } of ids) {
+      this._index.add(id, task_input);
+    }
+
     this.initialized = true;
   }
 
+  /**
+   * Set the reasoning bank for cluster-augmented retrieval.
+   * Called externally when ReasoningBank is initialized.
+   */
+  setReasoningBank(bank: ReasoningBank): void {
+    this._reasoningBank = bank;
+  }
+
+  /**
+   * Get the reasoning bank (if set).
+   */
+  getReasoningBank(): ReasoningBank | null {
+    return this._reasoningBank;
+  }
+
   /**
    * Store a new experience
    */
   async add(experience: Experience): Promise<void> {
     await this.init();
-    this._store.set(experience.id, experience);
-    await this._store.save(experience.id);
+    this.persistence.insertExperience(experience);
+    this._index.add(experience.id, experience.taskInput);
   }
 
   /**
@@ -57,12 +121,14 @@ export class ExperienceMemory {
    */
   async get(id: string): Promise<Experience | undefined> {
     await this.init();
-    return this._store.get(id);
+    const row = this.persistence.getExperience(id);
+    return row ? rowToExperience(row) : undefined;
   }
 
   /**
    * Find similar experiences
-   * Uses embedding similarity if available, falls back to text similarity
+   * Uses inverted index for candidate narrowing, then embedding/text similarity scoring.
+   * Bumps accessScore on returned results.
    */
   async findSimilar(
     query: string | number[],
@@ -76,9 +142,26 @@ export class ExperienceMemory {
     await this.init();
 
     const k = options?.k ?? 4; // ReMem default
-    let experiences = this._store.values();
 
-    // Filter by domain if specified
+    // Get candidate pool
+    const domainFallback = options?.domain
+      ? [
+          ...this.persistence.getExperiencesByDomain(options.domain).map(rowToExperience),
+          // Include '_global' domain items too
+          ...this.persistence.getExperiencesByDomain('_global').map(rowToExperience),
+        ]
+      : undefined;
+
+    let experiences: Experience[];
+
+    if (typeof query === 'string') {
+      experiences = getCandidates(query, this._index, this._resolver, { k }, domainFallback);
+    } else {
+      // Embedding query — inverted index doesn't help, use fallback
+      experiences = domainFallback ?? this.getAllSync();
+    }
+
+    // Apply domain filter (for cases where inverted index returned cross-domain results)
     if (options?.domain) {
       experiences = experiences.filter((e) => e.domain === options.domain);
     }
@@ -100,11 +183,57 @@ export class ExperienceMemory {
     }));
 
     // Filter by minimum score
-    if (options?.minScore !== undefined) {
-      return results.filter((r) => r.score >= options.minScore!);
+    const filtered = options?.minScore !== undefined
+      ? results.filter((r) => r.score >= options.minScore!)
+      : results;
+
+    // Merge with ReasoningBank results if available (string queries only)
+    let merged = filtered;
+    if (this._reasoningBank && typeof query === 'string') {
+      const clusterResults = this._reasoningBank.findInCluster(query, {
+        k,
+        domain: options?.domain,
+      });
+
+      // Merge: deduplicate by experience ID, keep higher score
+      const seenIds = new Map<string, number>();
+      for (const r of merged) {
+        seenIds.set(r.experience.id, r.score);
+      }
+      for (const cr of clusterResults) {
+        const existing = seenIds.get(cr.experience.id);
+        if (existing === undefined) {
+          merged.push({ experience: cr.experience, score: cr.score });
+          seenIds.set(cr.experience.id, cr.score);
+        }
+        // If already present, keep the higher score — existing is already in merged
+      }
+
+      // Re-sort by score after merge
+      merged.sort((a, b) => b.score - a.score);
+      merged = merged.slice(0, k);
+    }
+
+    // Bump access scores on returned results
+    for (const result of merged) {
+      const exp = result.experience;
+      const newRetrievalCount = (exp.retrievalCount ?? 0) + 1;
+      const newAccessScore = (exp.accessScore ?? 0) * 0.95 + 0.1;
+      const newLastAccessedAt = new Date();
+
+      this.persistence.updateExperience(exp.id, {
+        retrievalCount: newRetrievalCount,
+        accessScore: newAccessScore,
+        lastAccessedAt: newLastAccessedAt,
+      });
+
+      // Update in-memory reference too so caller sees updated values
+      exp.retrievalCount = newRetrievalCount;
+      exp.accessScore = newAccessScore;
+      exp.lastAccessedAt = newLastAccessedAt;
     }
 
-    return results;
+    return merged;
   }
 
   /**
@@ -115,16 +244,24 @@ export class ExperienceMemory {
     updates: Partial<Experience>
   ): Promise<Experience | undefined> {
     await this.init();
-    const existing = this._store.get(id);
-    if (!existing) return undefined;
+    const row = this.persistence.getExperience(id);
+    if (!row) return undefined;
 
+    const existing = rowToExperience(row);
     const updated = {
       ...existing,
       ...updates,
       id: existing.id, // Preserve ID
     };
-    this._store.set(id, updated);
-    await this._store.save(id);
+
+    // Write-through: full replace via INSERT OR REPLACE
+    this.persistence.insertExperience(updated);
+
+    // Update inverted index if taskInput changed
+    if (updates.taskInput) {
+      this._index.add(id, updates.taskInput);
+    }
+
     return updated;
   }
 
@@ -133,11 +270,12 @@ export class ExperienceMemory {
    */
   async recordUsage(id: string): Promise<void> {
     await this.init();
-    const existing = this._store.get(id);
-    if (existing) {
-      existing.usageCount++;
-      existing.lastAccessedAt = new Date();
-      this._store.set(id, existing);
+    const row = this.persistence.getExperience(id);
+    if (row) {
+      this.persistence.updateExperience(id, {
+        usageCount: row.usage_count + 1,
+        lastAccessedAt: new Date(),
+      });
     }
   }
 
@@ -146,7 +284,16 @@ export class ExperienceMemory {
    */
   async getAll(): Promise<Experience[]> {
     await this.init();
-    return this._store.values();
+    return this.getAllSync();
+  }
+
+  /**
+   * Delete an experience by ID
+   */
+  async delete(id: string): Promise<boolean> {
+    await this.init();
+    this._index.remove(id);
+    return this.persistence.deleteExperience(id);
   }
 
   /**
@@ -154,11 +301,12 @@ export class ExperienceMemory {
    */
   async getByTrajectory(trajectoryId: string): Promise<Experience[]> {
     await this.init();
-    return this._store.values().filter((e) => e.trajectoryId === trajectoryId);
+    return this.persistence.getExperiencesByTrajectory(trajectoryId).map(rowToExperience);
   }
 
   /**
-   * Prune low-value experiences
+   * Prune low-value experiences.
+   * Uses accessScore as primary value signal when available.
    */
   async prune(options?: {
     maxCount?: number;
@@ -177,7 +325,7 @@ export class ExperienceMemory {
       redundancy: [],
       failedOld: [],
     };
-    let experiences = this._store.values();
+    let experiences = this.getAllSync();
 
     // 1. Prune by age
     if (options?.maxAgeDays) {
@@ -186,7 +334,8 @@ export class ExperienceMemory {
         (e) => e.createdAt.getTime() < cutoff
       );
       for (const exp of oldExperiences) {
-        this._store.delete(exp.id);
+        this.persistence.deleteExperience(exp.id);
+        this._index.remove(exp.id);
         pruned.push(exp.id);
         prunedByReason.age.push(exp.id);
       }
@@ -201,7 +350,8 @@ export class ExperienceMemory {
         (e) => !e.success && e.createdAt.getTime() < cutoff
       );
       for (const exp of failedOld) {
-        this._store.delete(exp.id);
+        this.persistence.deleteExperience(exp.id);
+        this._index.remove(exp.id);
         pruned.push(exp.id);
         prunedByReason.failedOld.push(exp.id);
       }
@@ -219,12 +369,13 @@ export class ExperienceMemory {
       const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
       for (const exp of lowUsage) {
         if (exp.createdAt.getTime() < sevenDaysAgo) {
-          this._store.delete(exp.id);
+          this.persistence.deleteExperience(exp.id);
+          this._index.remove(exp.id);
           pruned.push(exp.id);
           prunedByReason.usage.push(exp.id);
         }
       }
-      experiences = this._store.values(); // Refresh
+      experiences = this.getAllSync(); // Refresh
     }
 
     // 4. Prune redundant/similar experiences
@@ -235,16 +386,17 @@ export class ExperienceMemory {
         options.preserveDomainCoverage
       );
       for (const exp of redundant) {
-        this._store.delete(exp.id);
+        this.persistence.deleteExperience(exp.id);
+        this._index.remove(exp.id);
         pruned.push(exp.id);
         prunedByReason.redundancy.push(exp.id);
       }
-      experiences = this._store.values(); // Refresh
+      experiences = this.getAllSync(); // Refresh
     }
 
     // 5. Prune by count (keep most valuable)
     if (options?.maxCount && experiences.length > options.maxCount) {
-      // Sort by value
+      // Sort by value (uses accessScore when available)
       experiences.sort((a, b) => {
         const scoreA = this.computeValue(a);
         const scoreB = this.computeValue(b);
@@ -260,7 +412,8 @@ export class ExperienceMemory {
         const keptIds = new Set(kept.map((e) => e.id));
         for (const exp of experiences) {
           if (!keptIds.has(exp.id)) {
-            this._store.delete(exp.id);
+            this.persistence.deleteExperience(exp.id);
+            this._index.remove(exp.id);
             pruned.push(exp.id);
             prunedByReason.capacity.push(exp.id);
           }
@@ -268,23 +421,19 @@ export class ExperienceMemory {
       } else {
         const toRemove = experiences.slice(options.maxCount);
         for (const exp of toRemove) {
-          this._store.delete(exp.id);
+          this.persistence.deleteExperience(exp.id);
+          this._index.remove(exp.id);
           pruned.push(exp.id);
           prunedByReason.capacity.push(exp.id);
         }
       }
     }
 
-    // Save changes
-    if (pruned.length > 0) {
-      await this._store.flush();
-    }
-
     return {
       prunedIds: pruned,
       prunedByReason,
       totalPruned: pruned.length,
-      remainingCount: this._store.size(),
+      remainingCount: this.persistence.getExperienceCount(),
     };
   }
 
@@ -403,9 +552,20 @@ export class ExperienceMemory {
   }
 
   /**
-   * Compute value score for an experience
+   * Compute value score for an experience.
+   * Uses accessScore as primary signal when available, falls back to
+   * the original recency + usage heuristic for backward compatibility.
    */
   private computeValue(exp: Experience): number {
+    // If accessScore is populated (> 0), use it as primary signal
+    if (exp.accessScore && exp.accessScore > 0) {
+      return (
+        exp.accessScore *
+        (exp.success ? 1 : 0.3)
+      );
+    }
+
+    // Backward compat: original heuristic for experiences without accessScore
     const ageMs = Date.now() - exp.createdAt.getTime();
     const ageDays = ageMs / (1000 * 60 * 60 * 24);
     const recencyScore = Math.exp(-ageDays / 30); // Decay over ~30 days
@@ -441,7 +601,7 @@ export class ExperienceMemory {
     };
   }> {
     await this.init();
-    const experiences = this._store.values();
+    const experiences = this.getAllSync();
 
     const byDomain: Record<string, number> = {};
     let successCount = 0;
@@ -503,13 +663,20 @@ export class ExperienceMemory {
    */
   async count(): Promise<number> {
     await this.init();
-    return this._store.size();
+    return this.persistence.getExperienceCount();
   }
 
   /**
-   * Close the store
+   * Close the store (no-op — SqlitePersistence lifecycle is managed externally)
    */
   async close(): Promise<void> {
-    await this._store.close();
+    // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
+  }
+
+  /**
+   * Synchronous helper: get all experiences from SQLite.
+   */
+  private getAllSync(): Experience[] {
+    return this.persistence.getAllExperiences().map(rowToExperience);
   }
 }

package/src/memory/index.ts

@@ -35,6 +35,45 @@ export {
   type TeamMetaObservationEntry,
 } from './team-experience.js';
 
+// Reflexion episodes
+export {
+  ReflexionMemory,
+  createReflexionMemory,
+  type ReflexionQueryOptions,
+} from './reflexion.js';
+
+// Coherence checking
+export {
+  CoherenceChecker,
+  createCoherenceChecker,
+  type CoherenceResult,
+  type CoherenceCheckerConfig,
+} from './coherence.js';
+
+// Reasoning bank (clustered experience retrieval)
+export {
+  ReasoningBank,
+  createReasoningBank,
+  type ExperienceCluster,
+  type ClusterStats,
+  type ReasoningBankConfig,
+} from './reasoning-bank.js';
+
+// Causal edge store
+export {
+  CausalStore,
+  createCausalStore,
+  type CausalEdge,
+} from './causal-store.js';
+
+// Temporal compression
+export {
+  TemporalCompressor,
+  createTemporalCompressor,
+  type TemporalCompressorConfig,
+  type CompressionResult,
+} from './temporal-compressor.js';
+
 // Knowledge bank (semantic memory)
 export { KnowledgeBank } from './knowledge-bank.js';
 export { KnowledgeGraphManager } from './knowledge-graph.js';
@@ -53,6 +92,10 @@ export {
   EntityGraphLayer,
 } from './graph-layers/index.js';
 
+// Re-export persistence module
+export { SqlitePersistence, createSqlitePersistence } from '../persistence/index.js';
+export type { SqlitePersistenceConfig } from '../persistence/index.js';
+
 // Curated playbook loading
 export {
   loadCuratedPlaybooks,

package/src/memory/knowledge-bank.ts

@@ -21,6 +21,7 @@ import type { GraphNode } from '../types/knowledge-graph.js';
 import type { AgenticTaskRunner } from '../workspace/runner.js';
 import type { TrajectoryAnalyzer, AnalysisResult } from '../learning/analyzer.js';
 import { KnowledgeGraphManager } from './knowledge-graph.js';
+import { CoherenceChecker } from './coherence.js';
 import {
   parseKnowledgeNote,
   serializeKnowledgeNote,
@@ -50,6 +51,7 @@ export class KnowledgeBank {
   private readonly bankConfig: KnowledgeBankConfig;
   private initialized = false;
   private searchProvider: SearchProvider = new TextSimilaritySearchProvider();
+  private coherenceChecker: CoherenceChecker = new CoherenceChecker();
 
   // Directory paths (resolved on init)
   private observationsDir = '';
@@ -115,15 +117,45 @@ export class KnowledgeBank {
 
   /**
    * Create a new knowledge note and write it to disk.
+   * Runs coherence checking against existing notes — contradictions are flagged
+   * via metadata but the note is still stored.
    * Updates the graph overlay in memory.
    */
   async addObservation(note: KnowledgeNote): Promise<string> {
     await this.init();
+
+    // Run coherence check against related existing notes (if enabled)
+    if (this.bankConfig.coherenceChecking !== false) {
+      try {
+        const existing = await this.getRelatedNotes(note);
+        const coherence = await this.coherenceChecker.check(note, existing);
+
+        if (!coherence.isCoherent) {
+          // Flag contradictions in metadata but still store the note
+          const meta = (note.frontmatter as Record<string, unknown>);
+          meta['contradictions'] = coherence.contradictions.map(
+            (c) => c.existingNoteId
+          );
+          meta['coherenceEnergy'] = coherence.globalEnergy;
+        }
+      } catch {
+        // Coherence check is non-critical — don't block insertion
+      }
+    }
+
     await this.writeNote(note);
     this.graph.addNode(this.noteToGraphNode(note));
     return note.frontmatter.id;
   }
 
+  /**
+   * Get the last coherence result from the most recent addObservation call.
+   * Useful for downstream consumers to react to contradictions.
+   */
+  getCoherenceChecker(): CoherenceChecker {
+    return this.coherenceChecker;
+  }
+
   /**
    * Update an existing entity note by appending a section.
    */
@@ -1245,6 +1277,31 @@ export class KnowledgeBank {
     return lines.join('\n');
   }
 
+  /**
+   * Get notes related to the given note by entity or domain overlap.
+   * Used for coherence checking before insertion.
+   */
+  private async getRelatedNotes(note: KnowledgeNote): Promise<KnowledgeNote[]> {
+    const allNotes = await this.getAllNotes();
+
+    const noteEntities = new Set(note.frontmatter.entities);
+    const noteDomains = new Set(note.frontmatter.domain);
+
+    return allNotes.filter((existing) => {
+      if (existing.frontmatter.id === note.frontmatter.id) return false;
+
+      const hasEntityOverlap = existing.frontmatter.entities.some((e) =>
+        noteEntities.has(e)
+      );
+      if (hasEntityOverlap) return true;
+
+      const hasDomainOverlap = existing.frontmatter.domain.some((d) =>
+        noteDomains.has(d)
+      );
+      return hasDomainOverlap;
+    });
+  }
+
   private noteToGraphNode(note: KnowledgeNote): GraphNode {
     return {
       id: note.frontmatter.id,