cognitive-core 0.1.0 → 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/graph-layers/base.ts

@@ -0,0 +1,184 @@
+import type {
+  GraphEdge,
+  GraphLayerOperations,
+} from '../../types/knowledge-graph.js';
+import type {
+  GraphLayerName,
+  KnowledgeNote,
+  LinkRelation,
+} from '../../types/knowledge.js';
+import { inferLayerFromRelation } from '../../types/knowledge.js';
+
+/**
+ * Base implementation for a graph layer.
+ *
+ * Uses an in-memory adjacency list for O(1) edge lookups.
+ * Subclasses only override the set of valid relation types for their layer.
+ */
+export abstract class BaseGraphLayer implements GraphLayerOperations {
+  abstract readonly name: GraphLayerName;
+  readonly enabled: boolean;
+
+  /** Outgoing edges: nodeId → edges[] */
+  protected outgoing = new Map<string, GraphEdge[]>();
+  /** Incoming edges: nodeId → edges[] */
+  protected incoming = new Map<string, GraphEdge[]>();
+
+  /** Which relation types belong to this layer */
+  protected abstract readonly validRelations: readonly LinkRelation[];
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  getEdges(
+    nodeId: string,
+    direction: 'outgoing' | 'incoming' | 'both' = 'both'
+  ): GraphEdge[] {
+    const result: GraphEdge[] = [];
+    if (direction === 'outgoing' || direction === 'both') {
+      result.push(...(this.outgoing.get(nodeId) ?? []));
+    }
+    if (direction === 'incoming' || direction === 'both') {
+      result.push(...(this.incoming.get(nodeId) ?? []));
+    }
+    return result;
+  }
+
+  neighbors(nodeId: string, depth: number = 1): string[] {
+    const visited = new Set<string>();
+    const queue: Array<{ id: string; d: number }> = [{ id: nodeId, d: 0 }];
+    visited.add(nodeId);
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (current.d >= depth) continue;
+
+      const edges = this.getEdges(current.id, 'both');
+      for (const edge of edges) {
+        const neighborId = edge.from === current.id ? edge.to : edge.from;
+        if (!visited.has(neighborId)) {
+          visited.add(neighborId);
+          queue.push({ id: neighborId, d: current.d + 1 });
+        }
+      }
+    }
+
+    visited.delete(nodeId);
+    return Array.from(visited);
+  }
+
+  pathBetween(fromId: string, toId: string): string[] | null {
+    if (fromId === toId) return [fromId];
+
+    const visited = new Set<string>();
+    const parent = new Map<string, string>();
+    const queue: string[] = [fromId];
+    visited.add(fromId);
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      const edges = this.getEdges(current, 'both');
+
+      for (const edge of edges) {
+        const neighborId = edge.from === current ? edge.to : edge.from;
+        if (!visited.has(neighborId)) {
+          visited.add(neighborId);
+          parent.set(neighborId, current);
+
+          if (neighborId === toId) {
+            // Reconstruct path
+            const path: string[] = [toId];
+            let node = toId;
+            while (parent.has(node)) {
+              node = parent.get(node)!;
+              path.unshift(node);
+            }
+            return path;
+          }
+
+          queue.push(neighborId);
+        }
+      }
+    }
+
+    return null;
+  }
+
+  addEdge(edge: GraphEdge): void {
+    // Add to outgoing
+    if (!this.outgoing.has(edge.from)) {
+      this.outgoing.set(edge.from, []);
+    }
+    this.outgoing.get(edge.from)!.push(edge);
+
+    // Add to incoming
+    if (!this.incoming.has(edge.to)) {
+      this.incoming.set(edge.to, []);
+    }
+    this.incoming.get(edge.to)!.push(edge);
+  }
+
+  removeEdge(fromId: string, toId: string, relation: string): void {
+    const outEdges = this.outgoing.get(fromId);
+    if (outEdges) {
+      const idx = outEdges.findIndex(
+        (e) => e.to === toId && e.relation === relation
+      );
+      if (idx !== -1) outEdges.splice(idx, 1);
+    }
+
+    const inEdges = this.incoming.get(toId);
+    if (inEdges) {
+      const idx = inEdges.findIndex(
+        (e) => e.from === fromId && e.relation === relation
+      );
+      if (idx !== -1) inEdges.splice(idx, 1);
+    }
+  }
+
+  getAllEdges(): GraphEdge[] {
+    const edges: GraphEdge[] = [];
+    for (const edgeList of this.outgoing.values()) {
+      edges.push(...edgeList);
+    }
+    return edges;
+  }
+
+  edgeCount(): number {
+    let count = 0;
+    for (const edgeList of this.outgoing.values()) {
+      count += edgeList.length;
+    }
+    return count;
+  }
+
+  rebuild(notes: KnowledgeNote[]): void {
+    this.clear();
+
+    for (const note of notes) {
+      for (const link of note.frontmatter.links) {
+        // Determine if this link belongs to this layer
+        const explicitLayer = link.layer;
+        const inferredLayer = inferLayerFromRelation(link.relation);
+        const belongsToLayer =
+          explicitLayer === this.name || (!explicitLayer && inferredLayer === this.name);
+
+        if (belongsToLayer) {
+          this.addEdge({
+            from: note.frontmatter.id,
+            to: link.target,
+            relation: link.relation,
+            weight: 1.0,
+            created: note.frontmatter.updated,
+          });
+        }
+      }
+    }
+  }
+
+  clear(): void {
+    this.outgoing.clear();
+    this.incoming.clear();
+  }
+}

package/src/memory/graph-layers/causal.ts

@@ -0,0 +1,16 @@
+import type { LinkRelation } from '../../types/knowledge.js';
+import { CAUSAL_RELATIONS } from '../../types/knowledge-graph.js';
+import { BaseGraphLayer } from './base.js';
+
+/**
+ * Causal graph layer — captures cause-effect chains between facts.
+ *
+ * Relations: caused-by, led-to, broke, enabled, prevented
+ *
+ * Disabled by default.
+ */
+export class CausalGraphLayer extends BaseGraphLayer {
+  readonly name = 'causal' as const;
+  protected readonly validRelations: readonly LinkRelation[] =
+    CAUSAL_RELATIONS;
+}

package/src/memory/graph-layers/entity.ts

@@ -0,0 +1,16 @@
+import type { LinkRelation } from '../../types/knowledge.js';
+import { ENTITY_RELATIONS } from '../../types/knowledge-graph.js';
+import { BaseGraphLayer } from './base.js';
+
+/**
+ * Entity graph layer — captures relationships between tools/libs/components.
+ *
+ * Relations: uses, part-of, interacts-with, contradicts, created-by
+ *
+ * Disabled by default.
+ */
+export class EntityGraphLayer extends BaseGraphLayer {
+  readonly name = 'entity' as const;
+  protected readonly validRelations: readonly LinkRelation[] =
+    ENTITY_RELATIONS;
+}

package/src/memory/graph-layers/index.ts

@@ -0,0 +1,5 @@
+export { BaseGraphLayer } from './base.js';
+export { SemanticGraphLayer } from './semantic.js';
+export { TemporalGraphLayer } from './temporal.js';
+export { CausalGraphLayer } from './causal.js';
+export { EntityGraphLayer } from './entity.js';

package/src/memory/graph-layers/semantic.ts

@@ -0,0 +1,16 @@
+import type { LinkRelation } from '../../types/knowledge.js';
+import { SEMANTIC_RELATIONS } from '../../types/knowledge-graph.js';
+import { BaseGraphLayer } from './base.js';
+
+/**
+ * Semantic graph layer — captures conceptual relationships.
+ *
+ * Relations: related-to, depends-on, specializes, generalizes, supports
+ *
+ * Always enabled by default.
+ */
+export class SemanticGraphLayer extends BaseGraphLayer {
+  readonly name = 'semantic' as const;
+  protected readonly validRelations: readonly LinkRelation[] =
+    SEMANTIC_RELATIONS;
+}