cognitive-core 0.1.0 → 0.2.0

package/src/memory/reasoning-bank.ts

@@ -0,0 +1,458 @@
+/**
+ * ReasoningBank — Pre-clusters successful experiences for faster, more
+ * interpretable retrieval.
+ *
+ * Uses K-means++ on tokenized task descriptions (bag-of-words similarity).
+ * No embedding dependency — works with textSimilarity only.
+ *
+ * Clustering algorithm:
+ * 1. Initialize k centroids using K-means++ (farthest-point initialization)
+ * 2. Assign experiences to nearest centroid by textSimilarity
+ * 3. Recompute centroids (experience with highest avg similarity to members)
+ * 4. Repeat until convergence or maxIterations
+ * 5. Label clusters by top-3 most frequent non-stop tokens
+ */
+
+import type { Experience } from '../types/index.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+import { textSimilarity, tokenize } from '../utils/similarity.js';
+
+/**
+ * A cluster of similar experiences
+ */
+export interface ExperienceCluster {
+  id: string;
+  /** Auto-generated label from common tokens */
+  label: string;
+  /** Representative taskInput (closest to cluster mean) */
+  centroid: string;
+  /** IDs of experiences in this cluster */
+  experienceIds: string[];
+  /** Aggregate success rate */
+  successRate: number;
+  /** Average access score (from Phase 0) */
+  avgAccessScore: number;
+  /** Domains represented */
+  domains: string[];
+}
+
+/**
+ * Cluster statistics
+ */
+export interface ClusterStats {
+  clusterId: string;
+  label: string;
+  successRate: number;
+  size: number;
+}
+
+/**
+ * Configuration for ReasoningBank
+ */
+export interface ReasoningBankConfig {
+  /** Maximum number of clusters (default: 20) */
+  maxClusters?: number;
+  /** Minimum experiences per cluster (default: 3) */
+  minClusterSize?: number;
+  /** Re-cluster after this many new experiences (default: 50) */
+  reclusterInterval?: number;
+  /** Max K-means iterations (default: 10) */
+  maxIterations?: number;
+}
+
+// Stop words to exclude from cluster labels
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+  'should', 'may', 'might', 'shall', 'can', 'need', 'dare', 'ought',
+  'and', 'but', 'or', 'nor', 'not', 'so', 'yet', 'both', 'either',
+  'neither', 'each', 'every', 'all', 'any', 'few', 'more', 'most',
+  'in', 'on', 'at', 'by', 'for', 'with', 'about', 'against', 'between',
+  'to', 'from', 'up', 'down', 'out', 'off', 'of', 'into', 'through',
+  'this', 'that', 'these', 'those', 'it', 'its', 'i', 'we', 'you', 'he',
+  'she', 'they', 'me', 'us', 'him', 'her', 'them', 'my', 'our', 'your',
+  'what', 'which', 'who', 'whom', 'when', 'where', 'why', 'how',
+  'if', 'then', 'else', 'than', 'as', 'no', 'yes',
+]);
+
+/**
+ * ReasoningBank — clustered experience retrieval
+ */
+export class ReasoningBank {
+  private clusters: Map<string, ExperienceCluster> = new Map();
+  private experienceIndex: Map<string, Experience> = new Map();
+  private experiencesSinceLastCluster = 0;
+  private config: Required<ReasoningBankConfig>;
+  private persistence?: SqlitePersistence;
+
+  constructor(config?: ReasoningBankConfig, persistence?: SqlitePersistence) {
+    this.config = {
+      maxClusters: config?.maxClusters ?? 20,
+      minClusterSize: config?.minClusterSize ?? 3,
+      reclusterInterval: config?.reclusterInterval ?? 50,
+      maxIterations: config?.maxIterations ?? 10,
+    };
+    this.persistence = persistence;
+
+    // Load persisted clusters if available
+    if (persistence?.isInitialized) {
+      const saved = persistence.getSystemState<{
+        clusters: [string, ExperienceCluster][];
+        experiencesSinceLastCluster: number;
+      }>('reasoning_bank');
+      if (saved) {
+        this.clusters = new Map(saved.clusters);
+        this.experiencesSinceLastCluster = saved.experiencesSinceLastCluster;
+      }
+    }
+  }
+
+  /**
+   * Build clusters from a set of experiences.
+   * Filters to successful experiences only.
+   */
+  buildClusters(experiences: Experience[]): void {
+    this.experienceIndex.clear();
+    for (const exp of experiences) {
+      this.experienceIndex.set(exp.id, exp);
+    }
+
+    // Only cluster successful experiences
+    const successful = experiences.filter((e) => e.success);
+    if (successful.length < this.config.minClusterSize) {
+      this.clusters.clear();
+      return;
+    }
+
+    // Determine k: at most maxClusters, but scale with data size
+    const k = Math.min(
+      this.config.maxClusters,
+      Math.max(2, Math.floor(successful.length / this.config.minClusterSize))
+    );
+
+    // Run K-means++
+    const assignments = this.kMeansPlusPlus(successful, k);
+
+    // Build cluster objects
+    this.clusters.clear();
+    for (const [clusterId, memberIds] of assignments.entries()) {
+      if (memberIds.length < this.config.minClusterSize) continue;
+
+      const members = memberIds
+        .map((id) => this.experienceIndex.get(id))
+        .filter((e): e is Experience => e !== undefined);
+
+      if (members.length === 0) continue;
+
+      const centroid = this.findCentroid(members);
+      const label = this.generateLabel(members);
+      const domains = [...new Set(members.map((e) => e.domain))];
+      const successCount = members.filter((e) => e.success).length;
+      const avgAccessScore =
+        members.reduce((sum, e) => sum + (e.accessScore ?? 0), 0) /
+        members.length;
+
+      this.clusters.set(clusterId, {
+        id: clusterId,
+        label,
+        centroid: centroid.taskInput,
+        experienceIds: members.map((e) => e.id),
+        successRate: members.length > 0 ? successCount / members.length : 0,
+        avgAccessScore,
+        domains,
+      });
+    }
+
+    this.experiencesSinceLastCluster = 0;
+
+    // Persist clusters
+    if (this.persistence) {
+      this.persistence.setSystemState('reasoning_bank', {
+        clusters: [...this.clusters.entries()],
+        experiencesSinceLastCluster: this.experiencesSinceLastCluster,
+      });
+    }
+  }
+
+  /**
+   * Find the nearest cluster for a query, then search within it.
+   */
+  findInCluster(
+    query: string,
+    options?: { k?: number; domain?: string }
+  ): Array<{ experience: Experience; score: number; clusterId: string }> {
+    const k = options?.k ?? 5;
+
+    if (this.clusters.size === 0) return [];
+
+    // Find the best-matching cluster by centroid similarity
+    let bestCluster: ExperienceCluster | undefined;
+    let bestClusterScore = -1;
+
+    for (const cluster of this.clusters.values()) {
+      // Filter by domain if specified
+      if (options?.domain && !cluster.domains.includes(options.domain)) continue;
+
+      const score = textSimilarity(query, cluster.centroid);
+      if (score > bestClusterScore) {
+        bestClusterScore = score;
+        bestCluster = cluster;
+      }
+    }
+
+    if (!bestCluster) return [];
+
+    // Search within the cluster
+    const results: Array<{ experience: Experience; score: number; clusterId: string }> = [];
+    for (const expId of bestCluster.experienceIds) {
+      const exp = this.experienceIndex.get(expId);
+      if (!exp) continue;
+      if (options?.domain && exp.domain !== options.domain) continue;
+
+      const score = textSimilarity(query, exp.taskInput);
+      results.push({ experience: exp, score, clusterId: bestCluster.id });
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, k);
+  }
+
+  /**
+   * Get all clusters.
+   */
+  getClusters(): ExperienceCluster[] {
+    return [...this.clusters.values()];
+  }
+
+  /**
+   * Get cluster-level statistics.
+   */
+  getClusterStats(): ClusterStats[] {
+    return [...this.clusters.values()].map((c) => ({
+      clusterId: c.id,
+      label: c.label,
+      successRate: c.successRate,
+      size: c.experienceIds.length,
+    }));
+  }
+
+  /**
+   * Check whether re-clustering should be triggered.
+   */
+  shouldRecluster(): boolean {
+    return this.experiencesSinceLastCluster >= this.config.reclusterInterval;
+  }
+
+  /**
+   * Load persisted clusters. Call after persistence is initialized.
+   */
+  loadPersistedState(): void {
+    if (this.persistence?.isInitialized) {
+      const saved = this.persistence.getSystemState<{
+        clusters: [string, ExperienceCluster][];
+        experiencesSinceLastCluster: number;
+      }>('reasoning_bank');
+      if (saved) {
+        this.clusters = new Map(saved.clusters);
+        this.experiencesSinceLastCluster = saved.experiencesSinceLastCluster;
+      }
+    }
+  }
+
+  /**
+   * Notify that a new experience was added (for recluster tracking).
+   */
+  notifyNewExperience(): void {
+    this.experiencesSinceLastCluster++;
+  }
+
+  /**
+   * Get the number of clusters.
+   */
+  get clusterCount(): number {
+    return this.clusters.size;
+  }
+
+  // === K-Means++ Implementation ===
+
+  /**
+   * K-means++ clustering on experience taskInputs using textSimilarity.
+   * Returns a map of clusterId → memberIds.
+   */
+  private kMeansPlusPlus(
+    experiences: Experience[],
+    k: number
+  ): Map<string, string[]> {
+    if (experiences.length <= k) {
+      // Not enough data for clustering — each is its own cluster
+      const result = new Map<string, string[]>();
+      for (let i = 0; i < experiences.length; i++) {
+        result.set(`cluster-${i}`, [experiences[i].id]);
+      }
+      return result;
+    }
+
+    // Step 1: Initialize centroids with K-means++ (farthest-point)
+    const centroidIndices = this.initCentroids(experiences, k);
+    let centroids = centroidIndices.map((i) => experiences[i]);
+
+    // Step 2-4: Iterative assignment and recomputation
+    let assignments = new Map<number, Experience[]>();
+
+    for (let iter = 0; iter < this.config.maxIterations; iter++) {
+      // Assign each experience to nearest centroid
+      assignments = new Map<number, Experience[]>();
+      for (let c = 0; c < centroids.length; c++) {
+        assignments.set(c, []);
+      }
+
+      for (const exp of experiences) {
+        let bestCentroid = 0;
+        let bestSim = -1;
+
+        for (let c = 0; c < centroids.length; c++) {
+          const sim = textSimilarity(exp.taskInput, centroids[c].taskInput);
+          if (sim > bestSim) {
+            bestSim = sim;
+            bestCentroid = c;
+          }
+        }
+
+        assignments.get(bestCentroid)!.push(exp);
+      }
+
+      // Recompute centroids
+      const newCentroids: Experience[] = [];
+      let changed = false;
+
+      for (let c = 0; c < centroids.length; c++) {
+        const members = assignments.get(c) ?? [];
+        if (members.length === 0) {
+          newCentroids.push(centroids[c]);
+          continue;
+        }
+
+        const newCentroid = this.findCentroid(members);
+        if (newCentroid.id !== centroids[c].id) {
+          changed = true;
+        }
+        newCentroids.push(newCentroid);
+      }
+
+      centroids = newCentroids;
+
+      // Converged
+      if (!changed) break;
+    }
+
+    // Build result map
+    const result = new Map<string, string[]>();
+    for (const [centroidIdx, members] of assignments.entries()) {
+      result.set(`cluster-${centroidIdx}`, members.map((e) => e.id));
+    }
+
+    return result;
+  }
+
+  /**
+   * K-means++ initialization: select centroids using farthest-point heuristic.
+   */
+  private initCentroids(experiences: Experience[], k: number): number[] {
+    const indices: number[] = [];
+
+    // Pick first centroid randomly
+    indices.push(Math.floor(Math.random() * experiences.length));
+
+    for (let c = 1; c < k; c++) {
+      // For each remaining point, compute distance to nearest centroid
+      let maxDist = -1;
+      let bestIdx = 0;
+
+      for (let i = 0; i < experiences.length; i++) {
+        if (indices.includes(i)) continue;
+
+        let minSimToCentroid = Infinity;
+        for (const ci of indices) {
+          const sim = textSimilarity(
+            experiences[i].taskInput,
+            experiences[ci].taskInput
+          );
+          if (sim < minSimToCentroid) {
+            minSimToCentroid = sim;
+          }
+        }
+
+        // Distance = 1 - similarity (farthest point)
+        const dist = 1 - minSimToCentroid;
+        if (dist > maxDist) {
+          maxDist = dist;
+          bestIdx = i;
+        }
+      }
+
+      indices.push(bestIdx);
+    }
+
+    return indices;
+  }
+
+  /**
+   * Find the centroid of a cluster: the experience with highest average
+   * similarity to all other members.
+   */
+  private findCentroid(members: Experience[]): Experience {
+    if (members.length === 1) return members[0];
+
+    let bestExp = members[0];
+    let bestAvgSim = -1;
+
+    for (const candidate of members) {
+      let totalSim = 0;
+      for (const other of members) {
+        if (other.id === candidate.id) continue;
+        totalSim += textSimilarity(candidate.taskInput, other.taskInput);
+      }
+      const avgSim = totalSim / (members.length - 1);
+      if (avgSim > bestAvgSim) {
+        bestAvgSim = avgSim;
+        bestExp = candidate;
+      }
+    }
+
+    return bestExp;
+  }
+
+  /**
+   * Generate a cluster label from the top-3 most frequent non-stop tokens.
+   */
+  private generateLabel(members: Experience[]): string {
+    const tokenCounts = new Map<string, number>();
+
+    for (const exp of members) {
+      const tokens = tokenize(exp.taskInput);
+      for (const token of tokens) {
+        if (STOP_WORDS.has(token)) continue;
+        if (token.length < 3) continue;
+        tokenCounts.set(token, (tokenCounts.get(token) ?? 0) + 1);
+      }
+    }
+
+    // Sort by frequency descending
+    const sorted = [...tokenCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([token]) => token);
+
+    return sorted.length > 0 ? sorted.join('-') : 'unlabeled';
+  }
+}
+
+/**
+ * Create a ReasoningBank instance
+ */
+export function createReasoningBank(
+  config?: ReasoningBankConfig,
+  persistence?: SqlitePersistence
+): ReasoningBank {
+  return new ReasoningBank(config, persistence);
+}

package/src/memory/reflexion.ts

@@ -0,0 +1,122 @@
+/**
+ * ReflexionMemory — Store and retrieve reflexion episodes.
+ *
+ * Each episode captures structured self-reflection on a completed trajectory:
+ * critique, key insights, strategy assessment, and suggested playbook updates.
+ *
+ * Backed by SqlitePersistence for unified database storage.
+ */
+
+import type { ReflexionEpisode } from '../types/index.js';
+import type { SqlitePersistence, ReflexionRow } from '../persistence/index.js';
+import { fromJSON, fromISO } from '../persistence/index.js';
+
+/**
+ * Options for querying recent reflexion episodes
+ */
+export interface ReflexionQueryOptions {
+  /** Maximum number of episodes to return (default: 10) */
+  k?: number;
+  /** Filter by domain */
+  domain?: string;
+  /** Filter by outcome */
+  outcome?: 'success' | 'partial' | 'failure';
+}
+
+/**
+ * Convert a ReflexionRow to a ReflexionEpisode.
+ */
+function rowToReflexion(row: ReflexionRow): ReflexionEpisode {
+  return {
+    id: row.id,
+    trajectoryId: row.trajectory_id,
+    taskSummary: row.task_summary,
+    outcome: row.outcome as 'success' | 'partial' | 'failure',
+    selfCritique: row.self_critique,
+    keyInsights: fromJSON(row.key_insights, []),
+    strategyAssessment: row.strategy_assessment,
+    suggestedPlaybookUpdates: fromJSON(row.suggested_playbook_updates, []),
+    domain: row.domain,
+    createdAt: fromISO(row.created_at) ?? new Date(),
+  };
+}
+
+/**
+ * ReflexionMemory — persistent store for reflexion episodes
+ */
+export class ReflexionMemory {
+  private persistence: SqlitePersistence;
+  private initialized = false;
+
+  constructor(persistence: SqlitePersistence) {
+    this.persistence = persistence;
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    this.initialized = true;
+  }
+
+  /**
+   * Store a reflexion episode
+   */
+  async add(episode: ReflexionEpisode): Promise<void> {
+    await this.init();
+    this.persistence.insertReflexionEpisode(episode);
+  }
+
+  /**
+   * Get the reflexion episode for a specific trajectory
+   */
+  async getByTrajectory(trajectoryId: string): Promise<ReflexionEpisode | undefined> {
+    await this.init();
+    const rows = this.persistence.getReflexionByTrajectory(trajectoryId);
+    return rows.length > 0 ? rowToReflexion(rows[0]) : undefined;
+  }
+
+  /**
+   * Get a reflexion episode by ID
+   */
+  async get(id: string): Promise<ReflexionEpisode | undefined> {
+    await this.init();
+    const row = this.persistence.getReflexionEpisode(id);
+    return row ? rowToReflexion(row) : undefined;
+  }
+
+  /**
+   * Get recent reflexion episodes, optionally filtered
+   */
+  async getRecent(options?: ReflexionQueryOptions): Promise<ReflexionEpisode[]> {
+    await this.init();
+
+    const rows = this.persistence.getReflexionEpisodes({
+      domain: options?.domain,
+      outcome: options?.outcome,
+      limit: options?.k ?? 10,
+    });
+
+    return rows.map(rowToReflexion);
+  }
+
+  /**
+   * Get the total number of stored episodes
+   */
+  async count(): Promise<number> {
+    await this.init();
+    return this.persistence.getReflexionEpisodes().length;
+  }
+
+  /**
+   * Close the store (no-op — SqlitePersistence lifecycle is managed externally)
+   */
+  async close(): Promise<void> {
+    // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
+  }
+}
+
+/**
+ * Create a ReflexionMemory instance
+ */
+export function createReflexionMemory(persistence: SqlitePersistence): ReflexionMemory {
+  return new ReflexionMemory(persistence);
+}

package/src/memory/search-provider.ts

@@ -0,0 +1,35 @@
+import type { KnowledgeNote } from '../types/knowledge.js';
+
+/**
+ * Result from a SearchProvider — maps a note ID to a relevance score.
+ */
+export interface SearchProviderResult {
+  noteId: string;
+  score: number;
+}
+
+/**
+ * Strategy interface for searching knowledge notes.
+ *
+ * Implementations receive pre-filtered candidate notes and return
+ * scored results. This allows swapping between text-based similarity
+ * (default) and external search backends (e.g., minimem).
+ */
+export interface SearchProvider {
+  /** Human-readable name for diagnostics / logging. */
+  readonly name: string;
+
+  /**
+   * Search pre-filtered candidates and return scored results.
+   *
+   * @param query      - The search query string.
+   * @param candidates - Pre-filtered KnowledgeNote array (already domain/stale-filtered).
+   * @param options    - Additional options like maxResults.
+   * @returns Scored results sorted by descending score.
+   */
+  search(
+    query: string,
+    candidates: KnowledgeNote[],
+    options?: { maxResults?: number }
+  ): SearchProviderResult[] | Promise<SearchProviderResult[]>;
+}

package/src/memory/search-providers/index.ts

@@ -0,0 +1,3 @@
+export { TextSimilaritySearchProvider } from './text-similarity.js';
+export { MinimemSearchProvider, type MinimemSearchClient } from './minimem.js';
+

package/src/memory/search-providers/minimem.ts

@@ -0,0 +1,84 @@
+import type { KnowledgeNote } from '../../types/knowledge.js';
+import type { SearchProvider, SearchProviderResult } from '../search-provider.js';
+
+/**
+ * Subset of the minimem search API that MinimemSearchProvider depends on.
+ * Structurally compatible with the Minimem class from the minimem package.
+ *
+ * Kept as a narrow interface (rather than importing Minimem directly) so
+ * tests can inject a lightweight mock without instantiating a full Minimem.
+ */
+export interface MinimemSearchClient {
+  search(query: string, options?: { maxResults?: number; minScore?: number }): Promise<
+    Array<{
+      path: string;
+      startLine: number;
+      endLine: number;
+      score: number;
+      snippet: string;
+    }>
+  >;
+}
+
+/**
+ * Search provider that delegates to a minimem instance.
+ *
+ * Maps minimem search results (which return file paths) back to
+ * KnowledgeNote IDs by matching against the candidate set.
+ *
+ * Falls back to returning an empty array on any error so that
+ * the KnowledgeBank can gracefully degrade.
+ */
+export class MinimemSearchProvider implements SearchProvider {
+  readonly name = 'minimem';
+
+  constructor(private readonly client: MinimemSearchClient) {}
+
+  /**
+   * Async search via minimem client.
+   * Maps minimem results back to note IDs from the candidate set.
+   */
+  async search(
+    query: string,
+    candidates: KnowledgeNote[],
+    options?: { maxResults?: number }
+  ): Promise<SearchProviderResult[]> {
+    try {
+      const maxResults = options?.maxResults ?? 10;
+      const minimemResults = await this.client.search(query, { maxResults });
+
+      // Build a lookup: normalize paths to match against candidate filePaths
+      const noteByPath = new Map<string, KnowledgeNote>();
+      for (const note of candidates) {
+        // Match on the full filePath or just the filename
+        noteByPath.set(note.filePath, note);
+        const filename = note.filePath.split('/').pop();
+        if (filename) {
+          noteByPath.set(filename, note);
+        }
+      }
+
+      const results: SearchProviderResult[] = [];
+      for (const mr of minimemResults) {
+        // Try matching by full path, then by filename portion
+        const pathParts = mr.path.split('/');
+        const filename = pathParts.pop();
+        const note =
+          noteByPath.get(mr.path) ||
+          (filename ? noteByPath.get(filename) : undefined);
+
+        if (note) {
+          results.push({
+            noteId: note.frontmatter.id,
+            score: mr.score,
+          });
+        }
+      }
+
+      return results;
+    } catch {
+      // Gracefully degrade: return empty on any error
+      return [];
+    }
+  }
+}