cognitive-core 0.1.0 → 0.1.2

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,
+      }));
+  }
+}

package/src/memory/skill-exporter.ts

@@ -0,0 +1,357 @@
+/**
+ * Skill Exporter - Compile playbooks into the Open Agent Skills format
+ *
+ * Playbooks are the source of truth (rich, evolving, learned from experience).
+ * SKILL.md files are the compiled distribution artifact — portable across 25+
+ * agent platforms (Claude Code, Codex CLI, GitHub Copilot, Cursor, etc.).
+ *
+ * The export preserves playbook-specific knowledge (anti-patterns, refinements,
+ * verification) in the Markdown body, while mapping core fields to the standard
+ * YAML frontmatter schema.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { Playbook } from '../types/index.js';
+import { getPlaybookSuccessRate, hasReliableStats } from '../types/index.js';
+import type { PlaybookLibrary } from './playbook.js';
+
+/**
+ * Options for filtering which playbooks to export
+ */
+export interface SkillExportFilter {
+  /** Minimum confidence to include (default: 0.5) */
+  minConfidence?: number;
+  /** Only include playbooks with at least this many total uses */
+  minUses?: number;
+  /** Only include playbooks from these domains */
+  domains?: string[];
+  /** Only include playbooks with these origins */
+  origins?: Array<'extracted' | 'curated' | 'imported' | 'manual'>;
+}
+
+/**
+ * Options for how the SKILL.md is generated
+ */
+export interface SkillExportOptions {
+  /** Include evolution stats (confidence, success rate) in metadata */
+  includeStats?: boolean;
+  /** Include refinements section in the body */
+  includeRefinements?: boolean;
+  /** Include anti-patterns as a "When NOT to use" section */
+  includeAntiPatterns?: boolean;
+  /** Include verification section */
+  includeVerification?: boolean;
+  /** Custom metadata fields to add to frontmatter */
+  extraMetadata?: Record<string, string>;
+}
+
+const DEFAULT_OPTIONS: Required<SkillExportOptions> = {
+  includeStats: true,
+  includeRefinements: true,
+  includeAntiPatterns: true,
+  includeVerification: true,
+  extraMetadata: {},
+};
+
+/**
+ * Result of an export operation
+ */
+export interface SkillExportResult {
+  exported: number;
+  skipped: number;
+  errors: Array<{ playbook: string; error: string }>;
+  skills: ExportedSkill[];
+}
+
+/**
+ * A single exported skill (before writing to disk)
+ */
+export interface ExportedSkill {
+  name: string;
+  dirName: string;
+  content: string;
+  sourcePlaybookId: string;
+}
+
+/**
+ * Compile a single playbook into SKILL.md content
+ */
+export function compilePlaybookToSkill(
+  playbook: Playbook,
+  options?: SkillExportOptions
+): string {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const sections: string[] = [];
+
+  // === YAML Frontmatter ===
+  sections.push('---');
+  sections.push(`name: ${playbook.name}`);
+  sections.push(`description: >-`);
+  sections.push(`  ${buildDescription(playbook)}`);
+
+  // Metadata block
+  const metadata: Record<string, string> = {
+    version: playbook.evolution.version,
+    complexity: playbook.complexity,
+    ...opts.extraMetadata,
+  };
+
+  if (playbook.provenance?.origin) {
+    metadata['origin'] = playbook.provenance.origin;
+  }
+  if (playbook.provenance?.curatedBy) {
+    metadata['author'] = playbook.provenance.curatedBy;
+  }
+  if (opts.includeStats) {
+    metadata['confidence'] = playbook.confidence.toFixed(2);
+    if (hasReliableStats(playbook)) {
+      metadata['success-rate'] = getPlaybookSuccessRate(playbook).toFixed(2);
+    }
+  }
+
+  sections.push('metadata:');
+  for (const [key, value] of Object.entries(metadata)) {
+    sections.push(`  ${key}: "${value}"`);
+  }
+
+  // Compatibility — express domains as environment context
+  if (playbook.applicability.domains.length > 0) {
+    sections.push(
+      `compatibility: Applicable to ${playbook.applicability.domains.join(', ')} projects`
+    );
+  }
+
+  sections.push('---');
+  sections.push('');
+
+  // === Markdown Body ===
+
+  // Strategy (the core guidance)
+  sections.push(`## Strategy`);
+  sections.push('');
+  sections.push(playbook.guidance.strategy);
+  sections.push('');
+
+  // Tactics
+  if (playbook.guidance.tactics.length > 0) {
+    sections.push('## Tactics');
+    sections.push('');
+    for (const tactic of playbook.guidance.tactics) {
+      sections.push(`- ${tactic}`);
+    }
+    sections.push('');
+  }
+
+  // Concrete steps
+  if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+    sections.push('## Steps');
+    sections.push('');
+    for (let i = 0; i < playbook.guidance.steps.length; i++) {
+      sections.push(`${i + 1}. ${playbook.guidance.steps[i]}`);
+    }
+    sections.push('');
+  }
+
+  // Code example
+  if (playbook.guidance.codeExample) {
+    sections.push('## Example');
+    sections.push('');
+    sections.push('```');
+    sections.push(playbook.guidance.codeExample);
+    sections.push('```');
+    sections.push('');
+  }
+
+  // Anti-patterns — "when NOT to use this"
+  if (opts.includeAntiPatterns && playbook.applicability.antiPatterns.length > 0) {
+    sections.push('## When NOT to use this');
+    sections.push('');
+    for (const ap of playbook.applicability.antiPatterns) {
+      sections.push(`- ${ap}`);
+    }
+    sections.push('');
+  }
+
+  // Triggers — concrete signals that this skill applies
+  if (playbook.applicability.triggers.length > 0) {
+    sections.push('## Triggers');
+    sections.push('');
+    sections.push(
+      'This skill applies when you encounter any of the following:'
+    );
+    sections.push('');
+    for (const trigger of playbook.applicability.triggers) {
+      sections.push(`- ${trigger}`);
+    }
+    sections.push('');
+  }
+
+  // Verification
+  if (opts.includeVerification) {
+    const { successIndicators, failureIndicators, rollbackStrategy } =
+      playbook.verification;
+    if (successIndicators.length > 0 || failureIndicators.length > 0) {
+      sections.push('## Verification');
+      sections.push('');
+      if (successIndicators.length > 0) {
+        sections.push('**Success looks like:**');
+        for (const si of successIndicators) {
+          sections.push(`- ${si}`);
+        }
+        sections.push('');
+      }
+      if (failureIndicators.length > 0) {
+        sections.push('**Failure looks like:**');
+        for (const fi of failureIndicators) {
+          sections.push(`- ${fi}`);
+        }
+        sections.push('');
+      }
+      if (rollbackStrategy) {
+        sections.push(`**Rollback:** ${rollbackStrategy}`);
+        sections.push('');
+      }
+    }
+  }
+
+  // Refinements — context-specific notes learned from experience
+  if (opts.includeRefinements && playbook.evolution.refinements.length > 0) {
+    sections.push('## Context-specific notes');
+    sections.push('');
+    for (const ref of playbook.evolution.refinements) {
+      sections.push(`- **${ref.context}:** ${ref.addition}`);
+    }
+    sections.push('');
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Build the description field from playbook applicability.
+ * The description is critical for skill discovery — agents use it to
+ * decide whether to load the skill.
+ */
+function buildDescription(playbook: Playbook): string {
+  const parts = [
+    ...playbook.applicability.situations,
+    ...playbook.applicability.triggers.slice(0, 2),
+  ];
+  const desc = parts.join('. ');
+  const domains = playbook.applicability.domains.join(', ');
+  // YAML multiline: use >- for long descriptions
+  const full = `${desc}. Domains: ${domains}.`;
+  // Truncate to 1024 chars per spec
+  if (full.length > 1024) {
+    return full.slice(0, 1021) + '...';
+  }
+  return full;
+}
+
+/**
+ * Export playbooks from a library to a directory of SKILL.md files
+ */
+export async function exportPlaybooksAsSkills(
+  library: PlaybookLibrary,
+  outputDir: string,
+  filter?: SkillExportFilter,
+  options?: SkillExportOptions
+): Promise<SkillExportResult> {
+  const result: SkillExportResult = {
+    exported: 0,
+    skipped: 0,
+    errors: [],
+    skills: [],
+  };
+
+  let playbooks = await library.getAll();
+
+  // Apply filters
+  if (filter?.minConfidence !== undefined) {
+    playbooks = playbooks.filter((p) => p.confidence >= filter.minConfidence!);
+  }
+  if (filter?.minUses !== undefined) {
+    playbooks = playbooks.filter(
+      (p) =>
+        p.evolution.successCount + p.evolution.failureCount >= filter.minUses!
+    );
+  }
+  if (filter?.domains && filter.domains.length > 0) {
+    playbooks = playbooks.filter((p) =>
+      p.applicability.domains.some((d) => filter.domains!.includes(d))
+    );
+  }
+  if (filter?.origins && filter.origins.length > 0) {
+    playbooks = playbooks.filter(
+      (p) =>
+        p.provenance?.origin !== undefined &&
+        filter.origins!.includes(p.provenance.origin)
+    );
+  }
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  for (const playbook of playbooks) {
+    try {
+      const content = compilePlaybookToSkill(playbook, options);
+      const dirName = playbook.name;
+      const skillDir = join(outputDir, dirName);
+
+      // Create skill directory
+      if (!existsSync(skillDir)) {
+        await mkdir(skillDir, { recursive: true });
+      }
+
+      // Write SKILL.md
+      await writeFile(join(skillDir, 'SKILL.md'), content, 'utf-8');
+
+      const skill: ExportedSkill = {
+        name: playbook.name,
+        dirName,
+        content,
+        sourcePlaybookId: playbook.id,
+      };
+
+      result.skills.push(skill);
+      result.exported++;
+    } catch (error) {
+      result.errors.push({
+        playbook: playbook.name,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Export a single playbook to a SKILL.md file
+ */
+export async function exportPlaybookAsSkill(
+  playbook: Playbook,
+  outputDir: string,
+  options?: SkillExportOptions
+): Promise<ExportedSkill> {
+  const content = compilePlaybookToSkill(playbook, options);
+  const dirName = playbook.name;
+  const skillDir = join(outputDir, dirName);
+
+  if (!existsSync(skillDir)) {
+    await mkdir(skillDir, { recursive: true });
+  }
+
+  await writeFile(join(skillDir, 'SKILL.md'), content, 'utf-8');
+
+  return {
+    name: playbook.name,
+    dirName,
+    content,
+    sourcePlaybookId: playbook.id,
+  };
+}

package/src/memory/system.ts

@@ -10,15 +10,23 @@ import type {
   MemoryConfig,
   MemoryCapacityConfig,
   Trajectory,
+  TeamTrajectory,
+  KnowledgeBankConfig,
 } from '../types/index.js';
 import { createExperience } from '../types/index.js';
 import { ExperienceMemory, type PruneResult } from './experience.js';
 import { PlaybookLibrary, type PlaybookMatch } from './playbook.js';
 import { MetaMemory } from './meta.js';
+import {
+  TeamExperienceMemory,
+  type TeamExperience,
+} from './team-experience.js';
 import {
   LearningEffectivenessTracker,
   type EffectivenessMetrics,
 } from '../learning/effectiveness.js';
+import { KnowledgeBank } from './knowledge-bank.js';
+import { join } from 'node:path';
 
 /**
  * Default capacity configuration
@@ -64,6 +72,8 @@ export class MemorySystem {
   public readonly playbooks: PlaybookLibrary;
   public readonly meta: MetaMemory;
   public readonly effectiveness: LearningEffectivenessTracker;
+  public readonly teamExperiences: TeamExperienceMemory;
+  public readonly knowledgeBank: KnowledgeBank | null;
 
   private config: MemoryConfig;
   private capacityConfig: MemoryCapacityConfig;
@@ -71,7 +81,11 @@ export class MemorySystem {
   private lastCapacityCheck = 0;
   private capacityCheckInterval = 60000; // Check every minute
 
-  constructor(baseDir: string, config?: Partial<MemoryConfig>) {
+  constructor(
+    baseDir: string,
+    config?: Partial<MemoryConfig>,
+    knowledgeBankConfig?: KnowledgeBankConfig
+  ) {
     this.config = {
       maxExperiences: config?.maxExperiences ?? 4,
       maxStrategies: config?.maxStrategies ?? 3,
@@ -87,6 +101,15 @@ export class MemorySystem {
     this.playbooks = new PlaybookLibrary(baseDir);
     this.meta = new MetaMemory(baseDir);
     this.effectiveness = new LearningEffectivenessTracker(baseDir);
+    this.teamExperiences = new TeamExperienceMemory(baseDir);
+
+    // Initialize knowledge bank if enabled
+    if (knowledgeBankConfig?.enabled) {
+      const memoryDir = join(baseDir, knowledgeBankConfig.memoryDir ?? 'memory');
+      this.knowledgeBank = new KnowledgeBank(memoryDir, knowledgeBankConfig);
+    } else {
+      this.knowledgeBank = null;
+    }
   }
 
   /**
@@ -95,12 +118,17 @@ export class MemorySystem {
   async init(): Promise<void> {
     if (this.initialized) return;
 
-    await Promise.all([
+    const initPromises: Promise<void>[] = [
       this.experiences.init(),
       this.playbooks.init(),
       this.meta.init(),
       this.effectiveness.init(),
-    ]);
+      this.teamExperiences.init(),
+    ];
+    if (this.knowledgeBank) {
+      initPromises.push(this.knowledgeBank.init());
+    }
+    await Promise.all(initPromises);
 
     this.initialized = true;
   }
@@ -368,14 +396,19 @@ export class MemorySystem {
     playbookCount: number;
     metaObservationCount: number;
     annotationCount: number;
+    teamExperienceCount: number;
+    teamPlaybookCount: number;
+    rolePlaybookCount: number;
+    teamMetaObservationCount: number;
   }> {
     await this.init();
 
-    const [experienceCount, playbookCount, metaStats, annotationCount] = await Promise.all([
+    const [experienceCount, playbookCount, metaStats, annotationCount, teamStats] = await Promise.all([
       this.experiences.count(),
       this.playbooks.count(),
       this.meta.getStats(),
       this.effectiveness.count(),
+      this.teamExperiences.getStats(),
     ]);
 
     return {
@@ -383,6 +416,10 @@ export class MemorySystem {
       playbookCount,
       metaObservationCount: metaStats.totalObservations,
       annotationCount,
+      teamExperienceCount: teamStats.teamExperienceCount,
+      teamPlaybookCount: teamStats.teamPlaybookCount,
+      rolePlaybookCount: teamStats.rolePlaybookCount,
+      teamMetaObservationCount: teamStats.metaObservationCount,
     };
   }
 
@@ -530,13 +567,28 @@ export class MemorySystem {
   /**
    * Close all stores
    */
+  /**
+   * Store a team trajectory and create a team experience
+   */
+  async storeTeamTrajectory(trajectory: TeamTrajectory): Promise<TeamExperience> {
+    await this.init();
+    return this.teamExperiences.storeTeamExperience({
+      teamTrajectory: trajectory,
+    });
+  }
+
   async close(): Promise<void> {
-    await Promise.all([
+    const closePromises: Promise<void>[] = [
       this.experiences.close(),
       this.playbooks.close(),
       this.meta.close(),
       this.effectiveness.close(),
-    ]);
+      this.teamExperiences.close(),
+    ];
+    if (this.knowledgeBank) {
+      closePromises.push(this.knowledgeBank.close());
+    }
+    await Promise.all(closePromises);
   }
 }
 
@@ -545,7 +597,8 @@ export class MemorySystem {
  */
 export function createMemorySystem(
   baseDir: string,
-  config?: Partial<MemoryConfig>
+  config?: Partial<MemoryConfig>,
+  knowledgeBankConfig?: KnowledgeBankConfig
 ): MemorySystem {
-  return new MemorySystem(baseDir, config);
+  return new MemorySystem(baseDir, config, knowledgeBankConfig);
 }