cognitive-core 0.2.4 → 0.3.1

package/src/memory/reasoning-bank.ts

@@ -1,458 +0,0 @@
-/**
- * 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

@@ -1,122 +0,0 @@
-/**
- * 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

@@ -1,35 +0,0 @@
-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

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

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

@@ -1,84 +0,0 @@
-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 [];
-    }
-  }
-}