cognitive-core 0.0.2 → 0.1.2

package/src/memory/playbook.ts

@@ -0,0 +1,493 @@
+/**
+ * Playbook Library - Unified store for adaptive guidance
+ * Replaces StrategyBank + SkillStore with a single, evolvable abstraction
+ */
+
+import type {
+  Playbook,
+  PlaybookOrigin,
+  FailureRecord,
+  Refinement,
+} from '../types/index.js';
+import { createPlaybook, bumpPlaybookVersion } from '../types/index.js';
+import { JsonStore } from '../utils/storage.js';
+import { textSimilarity } from '../utils/similarity.js';
+
+/**
+ * Match result for playbook retrieval
+ */
+export interface PlaybookMatch {
+  playbook: Playbook;
+  score: number;
+  matchType: 'situation' | 'trigger' | 'domain';
+}
+
+/**
+ * Options for finding matching playbooks
+ */
+export interface FindMatchingOptions {
+  k?: number;
+  domains?: string[];
+  minConfidence?: number;
+  excludeAntiPatterns?: boolean;
+  minScore?: number;
+}
+
+/**
+ * Playbook Library - Store and retrieve adaptive guidance
+ */
+export class PlaybookLibrary {
+  private store: JsonStore<Playbook>;
+  private initialized = false;
+
+  constructor(baseDir: string) {
+    this.store = new JsonStore<Playbook>(baseDir, 'playbooks', {
+      autoSaveInterval: 60000,
+      pretty: true,
+    });
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.init();
+    this.initialized = true;
+  }
+
+  // === RETRIEVAL ===
+
+  /**
+   * Find playbooks matching a context
+   * Uses weighted scoring across situations, triggers, and anti-patterns
+   */
+  async findMatching(
+    context: string,
+    options?: FindMatchingOptions
+  ): Promise<PlaybookMatch[]> {
+    await this.init();
+
+    const k = options?.k ?? 5;
+    let playbooks = this.store.values();
+
+    // Filter by domains if specified
+    if (options?.domains && options.domains.length > 0) {
+      playbooks = playbooks.filter((p) =>
+        p.applicability.domains.some((d) => options.domains!.includes(d))
+      );
+    }
+
+    // Filter by minimum confidence
+    if (options?.minConfidence !== undefined) {
+      playbooks = playbooks.filter((p) => p.confidence >= options.minConfidence!);
+    }
+
+    // Score playbooks
+    const scored: PlaybookMatch[] = [];
+
+    for (const playbook of playbooks) {
+      // Check anti-patterns first (if enabled)
+      if (options?.excludeAntiPatterns !== false) {
+        const antiPatternMatch = playbook.applicability.antiPatterns.some(
+          (ap) => textSimilarity(context, ap) > 0.7
+        );
+        if (antiPatternMatch) continue;
+      }
+
+      // Score against situations
+      const situationScores = playbook.applicability.situations.map((s) =>
+        textSimilarity(context, s)
+      );
+      const maxSituationScore =
+        situationScores.length > 0 ? Math.max(...situationScores) : 0;
+
+      // Score against triggers (weighted higher for exact matches)
+      const triggerScores = playbook.applicability.triggers.map((t) =>
+        textSimilarity(context, t)
+      );
+      const maxTriggerScore =
+        triggerScores.length > 0 ? Math.max(...triggerScores) * 1.2 : 0;
+
+      // Combine scores
+      const score = Math.max(maxSituationScore, maxTriggerScore);
+      const matchType: 'situation' | 'trigger' =
+        maxTriggerScore > maxSituationScore ? 'trigger' : 'situation';
+
+      if (score > 0) {
+        scored.push({ playbook, score, matchType });
+      }
+    }
+
+    // Sort by score and return top k
+    scored.sort((a, b) => b.score - a.score);
+    const results = scored.slice(0, k);
+
+    // Apply minimum score filter
+    if (options?.minScore !== undefined) {
+      return results.filter((r) => r.score >= options.minScore!);
+    }
+
+    return results;
+  }
+
+  /**
+   * Find by specific trigger (for error messages, etc.)
+   */
+  async findByTrigger(trigger: string, threshold = 0.5): Promise<Playbook[]> {
+    await this.init();
+
+    return this.store.values().filter((playbook) =>
+      playbook.applicability.triggers.some(
+        (t) =>
+          t.toLowerCase().includes(trigger.toLowerCase()) ||
+          textSimilarity(trigger, t) >= threshold
+      )
+    );
+  }
+
+  /**
+   * Get playbooks with refinements for a specific context
+   */
+  async findWithRefinements(context: string): Promise<Playbook[]> {
+    await this.init();
+
+    return this.store.values().filter((playbook) =>
+      playbook.evolution.refinements.some(
+        (r) => textSimilarity(context, r.context) > 0.6
+      )
+    );
+  }
+
+  // === EVOLUTION ===
+
+  /**
+   * Record successful application
+   */
+  async recordSuccess(id: string, _trajectoryId: string): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    playbook.evolution.successCount++;
+    playbook.evolution.lastUsed = new Date();
+
+    // Increase confidence (exponential moving average)
+    const alpha = 0.1;
+    playbook.confidence = playbook.confidence * (1 - alpha) + 1 * alpha;
+    playbook.confidence = Math.min(playbook.confidence, 0.99); // Cap at 0.99
+
+    playbook.updatedAt = new Date();
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Record failure and capture context
+   */
+  async recordFailure(
+    id: string,
+    trajectoryId: string,
+    failureContext: string,
+    failureMode: string
+  ): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    playbook.evolution.failureCount++;
+    playbook.evolution.lastUsed = new Date();
+
+    // Add failure record
+    const failure: FailureRecord = {
+      trajectoryId,
+      context: failureContext,
+      failureMode,
+      timestamp: new Date(),
+    };
+    playbook.evolution.failures.push(failure);
+
+    // Keep only last 10 failures
+    if (playbook.evolution.failures.length > 10) {
+      playbook.evolution.failures = playbook.evolution.failures.slice(-10);
+    }
+
+    // Decrease confidence
+    const alpha = 0.15; // Failures have slightly more impact
+    playbook.confidence = playbook.confidence * (1 - alpha) + 0 * alpha;
+    playbook.confidence = Math.max(playbook.confidence, 0.1); // Floor at 0.1
+
+    playbook.updatedAt = new Date();
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Add a context-specific refinement
+   */
+  async addRefinement(
+    id: string,
+    context: string,
+    addition: string,
+    source: 'failure' | 'success' | 'manual'
+  ): Promise<void> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return;
+
+    // Check if similar refinement exists
+    const exists = playbook.evolution.refinements.some(
+      (r) => textSimilarity(r.context, context) > 0.85
+    );
+    if (exists) return;
+
+    const refinement: Refinement = {
+      context,
+      addition,
+      source,
+      addedAt: new Date(),
+    };
+
+    playbook.evolution.refinements.push(refinement);
+
+    // Bump patch version
+    playbook.evolution.version = bumpPlaybookVersion(playbook, 'patch');
+    playbook.updatedAt = new Date();
+
+    this.store.set(id, playbook);
+    await this.store.save(id);
+  }
+
+  /**
+   * Evolve playbook based on accumulated failures
+   * Should be called after several failures to update guidance
+   */
+  async evolve(
+    id: string,
+    newGuidance?: Partial<Playbook['guidance']>,
+    newAntiPatterns?: string[]
+  ): Promise<Playbook | undefined> {
+    await this.init();
+    const playbook = this.store.get(id);
+    if (!playbook) return undefined;
+
+    // Update guidance if provided
+    if (newGuidance) {
+      playbook.guidance = { ...playbook.guidance, ...newGuidance };
+    }
+
+    // Add new anti-patterns
+    if (newAntiPatterns) {
+      const unique = newAntiPatterns.filter(
+        (ap) => !playbook.applicability.antiPatterns.includes(ap)
+      );
+      playbook.applicability.antiPatterns.push(...unique);
+    }
+
+    // Bump minor version for evolution
+    playbook.evolution.version = bumpPlaybookVersion(playbook, 'minor');
+    playbook.updatedAt = new Date();
+
+    this.store.set(id, playbook);
+    await this.store.save(id);
+
+    return playbook;
+  }
+
+  // === LIFECYCLE ===
+
+  /**
+   * Add a new playbook
+   */
+  async add(playbook: Playbook): Promise<void> {
+    await this.init();
+    this.store.set(playbook.id, playbook);
+    await this.store.save(playbook.id);
+  }
+
+  /**
+   * Create and add a new playbook
+   */
+  async create(
+    input: Parameters<typeof createPlaybook>[0]
+  ): Promise<Playbook> {
+    const playbook = createPlaybook(input);
+    await this.add(playbook);
+    return playbook;
+  }
+
+  /**
+   * Get a playbook by ID
+   */
+  async get(id: string): Promise<Playbook | undefined> {
+    await this.init();
+    return this.store.get(id);
+  }
+
+  /**
+   * Get playbook by name
+   */
+  async getByName(name: string): Promise<Playbook | undefined> {
+    await this.init();
+    return this.store.values().find((p) => p.name === name);
+  }
+
+  /**
+   * Check if a similar playbook exists
+   */
+  async exists(
+    description: string,
+    threshold = 0.85
+  ): Promise<Playbook | undefined> {
+    await this.init();
+
+    // Check by exact name match
+    const byName = this.store.values().find(
+      (p) => p.name === description.toLowerCase().replace(/\s+/g, '-')
+    );
+    if (byName) return byName;
+
+    // Check by situation similarity
+    for (const playbook of this.store.values()) {
+      for (const situation of playbook.applicability.situations) {
+        if (textSimilarity(description, situation) >= threshold) {
+          return playbook;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get playbooks by domain
+   */
+  async getByDomain(domain: string): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) =>
+      p.applicability.domains.includes(domain)
+    );
+  }
+
+  /**
+   * Get most effective playbooks (by success rate)
+   */
+  async getMostEffective(k = 10): Promise<Playbook[]> {
+    await this.init();
+    return this.store
+      .values()
+      .filter((p) => p.evolution.successCount + p.evolution.failureCount >= 3)
+      .sort((a, b) => {
+        const rateA =
+          a.evolution.successCount /
+          (a.evolution.successCount + a.evolution.failureCount);
+        const rateB =
+          b.evolution.successCount /
+          (b.evolution.successCount + b.evolution.failureCount);
+        return rateB - rateA;
+      })
+      .slice(0, k);
+  }
+
+  /**
+   * Get playbooks by confidence threshold
+   */
+  async getHighConfidence(minConfidence = 0.8): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) => p.confidence >= minConfidence);
+  }
+
+  /**
+   * Get all playbooks
+   */
+  async getAll(): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values();
+  }
+
+  /**
+   * Delete a playbook
+   */
+  async delete(id: string): Promise<boolean> {
+    await this.init();
+    const existed = this.store.has(id);
+    if (existed) {
+      this.store.delete(id);
+    }
+    return existed;
+  }
+
+  /**
+   * Get count
+   */
+  async count(): Promise<number> {
+    await this.init();
+    return this.store.size();
+  }
+
+  /**
+   * Get all unique domains
+   */
+  async getDomains(): Promise<string[]> {
+    await this.init();
+    const domains = new Set<string>();
+    for (const playbook of this.store.values()) {
+      for (const domain of playbook.applicability.domains) {
+        domains.add(domain);
+      }
+    }
+    return Array.from(domains);
+  }
+
+  // === PROVENANCE ===
+
+  /**
+   * Get playbooks by origin type
+   */
+  async getByOrigin(origin: PlaybookOrigin): Promise<Playbook[]> {
+    await this.init();
+    return this.store.values().filter((p) => p.provenance?.origin === origin);
+  }
+
+  /**
+   * Delete all playbooks with a specific origin
+   * Returns the number of playbooks deleted
+   */
+  async deleteByOrigin(origin: PlaybookOrigin): Promise<number> {
+    await this.init();
+    const toDelete = this.store.values().filter((p) => p.provenance?.origin === origin);
+    for (const playbook of toDelete) {
+      this.store.delete(playbook.id);
+    }
+    return toDelete.length;
+  }
+
+  /**
+   * Get provenance summary across all playbooks
+   */
+  async getProvenanceSummary(): Promise<Record<PlaybookOrigin, number>> {
+    await this.init();
+    const summary: Record<string, number> = {
+      extracted: 0,
+      curated: 0,
+      imported: 0,
+      manual: 0,
+    };
+    for (const playbook of this.store.values()) {
+      const origin = playbook.provenance?.origin ?? 'extracted';
+      summary[origin] = (summary[origin] ?? 0) + 1;
+    }
+    return summary as Record<PlaybookOrigin, number>;
+  }
+
+  /**
+   * Close the store
+   */
+  async close(): Promise<void> {
+    await this.store.close();
+  }
+}
+
+/**
+ * Create a playbook library
+ */
+export function createPlaybookLibrary(baseDir: string): PlaybookLibrary {
+  return new PlaybookLibrary(baseDir);
+}

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 [];
+    }
+  }
+}

package/src/memory/search-providers/text-similarity.ts

@@ -0,0 +1,35 @@
+import type { KnowledgeNote } from '../../types/knowledge.js';
+import type { SearchProvider, SearchProviderResult } from '../search-provider.js';
+import { findTopK } from '../../utils/similarity.js';
+
+/**
+ * Default search provider using Jaccard + n-gram text similarity.
+ *
+ * This is the original search logic extracted from KnowledgeBank.search().
+ * Scores each candidate note against the query using `findTopK()`.
+ */
+export class TextSimilaritySearchProvider implements SearchProvider {
+  readonly name = 'text-similarity';
+
+  search(
+    query: string,
+    candidates: KnowledgeNote[],
+    options?: { maxResults?: number }
+  ): SearchProviderResult[] {
+    const maxResults = options?.maxResults ?? 10;
+
+    const results = findTopK<KnowledgeNote>(
+      query,
+      candidates,
+      (note) => `${note.frontmatter.id} ${note.body}`,
+      maxResults
+    );
+
+    return results
+      .filter((r) => r.score > 0)
+      .map((r) => ({
+        noteId: r.item.frontmatter.id,
+        score: r.score,
+      }));
+  }
+}