recallnest 1.4.1 → 2.2.1

package/src/skill-engine.ts

@@ -0,0 +1,208 @@
+/**
+ * D-1: Skill Memory — store and retrieve executable skills.
+ *
+ * Skills are stored as "patterns" category entries with structured metadata,
+ * using the same LanceDB vector search infrastructure as regular memories.
+ */
+
+import type { Embedder } from "./embedder.js";
+import type { MemoryStore, MemoryEntry } from "./store.js";
+import { deterministicId } from "./store.js";
+import { SkillInputSchema, type SkillInput, type StoredSkillRecord } from "./skill-schema.js";
+import { defaultEvolution } from "./memory-evolution.js";
+import { generateAnchor } from "./anchor-generator.js";
+import { buildStructuredMemoryBoundary } from "./memory-boundaries.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type StoreDeps = Pick<MemoryStore, "store" | "update" | "getById">;
+type EmbedDeps = Pick<Embedder, "embedPassage">;
+type SearchDeps = Pick<MemoryStore, "vectorSearch">;
+
+const SKILL_IMPORTANCE = 0.85;
+const SKILL_CATEGORY = "patterns" as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildEmbeddingText(input: SkillInput): string {
+  return `${input.description} ${input.triggerPattern}`;
+}
+
+function buildFullText(input: SkillInput): string {
+  return [
+    `Skill: ${input.name}`,
+    `Description: ${input.description}`,
+    `Trigger: ${input.triggerPattern}`,
+    `Type: ${input.implementationType}`,
+    `Implementation: ${input.implementation}`,
+  ].join("\n");
+}
+
+function buildSkillMetadata(input: SkillInput, anchor: string | undefined): string {
+  return JSON.stringify({
+    source: input.source,
+    tags: input.tags,
+    capture: "skill_schema_v1",
+    boundary: buildStructuredMemoryBoundary("patterns"),
+    canonicalKey: `patterns:skill:${input.name.toLowerCase().replace(/\s+/g, "-")}`,
+    evolution: defaultEvolution(),
+    ...(anchor ? { anchor } : {}),
+    skill: {
+      name: input.name,
+      description: input.description,
+      triggerPattern: input.triggerPattern,
+      implementationType: input.implementationType,
+      implementation: input.implementation,
+      ...(input.inputSchema ? { inputSchema: input.inputSchema } : {}),
+      ...(input.verification ? { verification: input.verification } : {}),
+      successCount: 0,
+      failureCount: 0,
+    },
+  });
+}
+
+function parseSkillFromEntry(entry: MemoryEntry): StoredSkillRecord | null {
+  let meta: Record<string, unknown>;
+  try {
+    meta = JSON.parse(entry.metadata || "{}");
+  } catch {
+    return null;
+  }
+
+  const skill = meta.skill;
+  if (!skill || typeof skill !== "object") return null;
+
+  const s = skill as Record<string, unknown>;
+  if (typeof s.name !== "string" || typeof s.implementation !== "string") return null;
+
+  return {
+    name: s.name as string,
+    description: (s.description as string) || "",
+    triggerPattern: (s.triggerPattern as string) || "",
+    implementationType: (s.implementationType as string) as StoredSkillRecord["implementationType"],
+    implementation: s.implementation as string,
+    inputSchema: s.inputSchema as Record<string, unknown> | undefined,
+    verification: (s.verification as string) || undefined,
+    scope: entry.scope,
+    source: (meta.source as StoredSkillRecord["source"]) || "manual",
+    tags: Array.isArray(meta.tags) ? (meta.tags as string[]) : [],
+    id: entry.id,
+    storedAt: new Date(entry.timestamp).toISOString(),
+    successCount: typeof s.successCount === "number" ? s.successCount : 0,
+    failureCount: typeof s.failureCount === "number" ? s.failureCount : 0,
+    lastRefinedAt: typeof s.lastRefinedAt === "string" ? s.lastRefinedAt : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function persistSkill(
+  store: StoreDeps,
+  embedder: EmbedDeps,
+  rawInput: unknown,
+): Promise<StoredSkillRecord> {
+  const input = SkillInputSchema.parse(rawInput);
+
+  const embeddingText = buildEmbeddingText(input);
+  const vector = await embedder.embedPassage(embeddingText);
+  const fullText = buildFullText(input);
+  const id = deterministicId(input.scope, input.name);
+  const anchor = generateAnchor(fullText);
+  const metadata = buildSkillMetadata(input, anchor);
+
+  // Check for existing skill with same scope+name (idempotent upsert)
+  const existing = await store.getById(id);
+
+  if (existing) {
+    // Update existing skill — bump version in evolution metadata
+    let existingMeta: Record<string, unknown> = {};
+    try {
+      existingMeta = JSON.parse(existing.metadata || "{}");
+    } catch { /* use fresh metadata */ }
+
+    const existingEvolution = existingMeta.evolution as Record<string, unknown> | undefined;
+    const currentVersion = typeof existingEvolution?.version === "number" ? existingEvolution.version : 1;
+
+    const updatedMetadata = JSON.stringify({
+      ...JSON.parse(metadata),
+      evolution: {
+        ...defaultEvolution(),
+        version: currentVersion + 1,
+      },
+    });
+
+    const updated = await store.update(id, {
+      text: fullText,
+      vector,
+      metadata: updatedMetadata,
+      timestamp: Date.now(),
+    });
+
+    if (!updated) {
+      throw new Error(`Failed to update skill "${input.name}" (id: ${id})`);
+    }
+
+    return {
+      ...input,
+      id: updated.id,
+      storedAt: new Date(updated.timestamp).toISOString(),
+      successCount: 0,
+      failureCount: 0,
+    };
+  }
+
+  // Store new skill
+  const stored = await store.store({
+    id,
+    text: fullText,
+    vector,
+    category: SKILL_CATEGORY,
+    scope: input.scope,
+    importance: SKILL_IMPORTANCE,
+    metadata,
+  });
+
+  return {
+    ...input,
+    id: stored.id,
+    storedAt: new Date(stored.timestamp).toISOString(),
+    successCount: 0,
+    failureCount: 0,
+  };
+}
+
+export async function retrieveSkills(
+  store: SearchDeps,
+  embedder: EmbedDeps,
+  query: string,
+  scope?: string,
+  limit?: number,
+): Promise<Array<{ skill: StoredSkillRecord; score: number }>> {
+  const vector = await embedder.embedPassage(query);
+  const safeLimit = Math.min(Math.max(limit ?? 3, 1), 10);
+
+  // Over-fetch to account for filtering
+  const fetchLimit = safeLimit * 3;
+  const scopeFilter = scope ? [scope] : undefined;
+  const results = await store.vectorSearch(vector, fetchLimit, 0.3, scopeFilter);
+
+  const matched: Array<{ skill: StoredSkillRecord; score: number }> = [];
+
+  for (const result of results) {
+    if (result.entry.category !== SKILL_CATEGORY) continue;
+
+    const skill = parseSkillFromEntry(result.entry);
+    if (!skill) continue;
+
+    matched.push({ skill, score: result.score });
+    if (matched.length >= safeLimit) break;
+  }
+
+  return matched;
+}

package/src/skill-promotion.ts

@@ -0,0 +1,293 @@
+/**
+ * D-2: Case -> Strategy -> Skill Promotion Pipeline.
+ *
+ * Automatically detects promotion opportunities:
+ * - Same scope has N+ similar cases (store_case called repeatedly) -> suggest workflow_pattern
+ * - workflow_pattern with structured steps that correlates with multiple cases -> suggest skill
+ *
+ * Promotion suggestions are returned to the agent for review — never auto-executed,
+ * to avoid low-quality skills entering the store.
+ */
+
+import type { MemoryEntry, MemoryStore } from "./store.js";
+import { cosineSimilarity } from "./multi-vector.js";
+import { isActiveMemory } from "./memory-evolution.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PromotionCandidate {
+  type: "case_to_pattern" | "pattern_to_skill";
+  sourceEntries: Array<{ id: string; text: string; score: number }>;
+  suggestedName: string;
+  suggestedDescription: string;
+  /** For pattern_to_skill: extracted implementation steps */
+  suggestedImplementation?: string;
+  confidence: number; // 0-1
+}
+
+export interface PromotionScanResult {
+  candidates: PromotionCandidate[];
+  scannedCases: number;
+  scannedPatterns: number;
+}
+
+export interface PromotionConfig {
+  /** Minimum similar cases to suggest pattern promotion (default: 3) */
+  minCaseOccurrences: number;
+  /** Similarity threshold for case clustering (default: 0.75) */
+  caseSimilarityThreshold: number;
+  /** Max candidates to return (default: 5) */
+  maxCandidates: number;
+}
+
+const DEFAULT_CONFIG: PromotionConfig = {
+  minCaseOccurrences: 3,
+  caseSimilarityThreshold: 0.75,
+  maxCandidates: 5,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type PromotionStore = Pick<MemoryStore, "list" | "vectorSearch">;
+
+function isActive(entry: MemoryEntry): boolean {
+  return isActiveMemory(entry.metadata);
+}
+
+/** Extract a short name from the first case's text (first line or first ~60 chars). */
+function extractName(text: string): string {
+  const firstLine = text.split("\n")[0].trim();
+  return firstLine.length > 60 ? firstLine.slice(0, 57) + "..." : firstLine;
+}
+
+/** Summarize a cluster into a description from member texts. */
+function summarizeCluster(members: MemoryEntry[]): string {
+  const snippets = members.slice(0, 3).map(m => {
+    const first = m.text.split("\n")[0].trim();
+    return first.length > 80 ? first.slice(0, 77) + "..." : first;
+  });
+  return `Recurring pattern across ${members.length} cases: ${snippets.join("; ")}`;
+}
+
+/** Check if text contains structured steps (numbered list or "Steps:" header). */
+function hasStructuredSteps(text: string): boolean {
+  return /(?:^|\n)\s*(?:Steps?:|##?\s*Steps?)/i.test(text)
+    || /(?:^|\n)\s*[1-9]\.\s+\S/.test(text);
+}
+
+/** Extract the steps section from a pattern's text. */
+function extractSteps(text: string): string {
+  // Try to find content after "Steps:" header
+  const stepsMatch = text.match(/(?:^|\n)\s*(?:Steps?:|##?\s*Steps?)\s*\n([\s\S]+)/i);
+  if (stepsMatch) return stepsMatch[1].trim();
+
+  // Fall back: extract all numbered list items
+  const lines = text.split("\n");
+  const numbered = lines.filter(l => /^\s*[1-9]\d*\.\s+\S/.test(l));
+  return numbered.length > 0 ? numbered.join("\n") : text;
+}
+
+// ---------------------------------------------------------------------------
+// Greedy Clustering (same approach as consolidation-engine's C-2)
+// ---------------------------------------------------------------------------
+
+interface Cluster {
+  seed: MemoryEntry;
+  members: MemoryEntry[];
+}
+
+function greedyCluster(
+  entries: MemoryEntry[],
+  threshold: number,
+): Cluster[] {
+  const clusters: Cluster[] = [];
+  const centroids: number[][] = [];
+  const assigned = new Set<string>();
+
+  for (const entry of entries) {
+    if (assigned.has(entry.id) || !entry.vector?.length) continue;
+
+    let bestIdx = -1;
+    let bestSim = -1;
+
+    for (let ci = 0; ci < centroids.length; ci++) {
+      const sim = cosineSimilarity(entry.vector, centroids[ci]);
+      if (sim > threshold && sim > bestSim) {
+        bestSim = sim;
+        bestIdx = ci;
+      }
+    }
+
+    if (bestIdx >= 0) {
+      clusters[bestIdx].members.push(entry);
+      assigned.add(entry.id);
+      // Update centroid as running average
+      const members = clusters[bestIdx].members;
+      const dim = centroids[bestIdx].length;
+      const newCentroid = new Array<number>(dim);
+      for (let d = 0; d < dim; d++) {
+        let sum = 0;
+        for (const m of members) sum += m.vector[d];
+        newCentroid[d] = sum / members.length;
+      }
+      centroids[bestIdx] = newCentroid;
+    } else {
+      clusters.push({ seed: entry, members: [entry] });
+      centroids.push([...entry.vector]);
+      assigned.add(entry.id);
+    }
+  }
+
+  return clusters;
+}
+
+// ---------------------------------------------------------------------------
+// Main scan
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan for promotion candidates in a given scope.
+ *
+ * Algorithm:
+ * 1. Load all active entries in scope, split into cases and patterns
+ * 2. Cluster cases by embedding similarity (greedy clustering)
+ * 3. Clusters with >= minCaseOccurrences members -> case_to_pattern candidate
+ * 4. Patterns with structured steps that are similar to >= 2 cases -> pattern_to_skill candidate
+ */
+export async function scanForPromotions(
+  store: PromotionStore,
+  scope: string,
+  config?: Partial<PromotionConfig>,
+): Promise<PromotionScanResult> {
+  const cfg: PromotionConfig = { ...DEFAULT_CONFIG, ...config };
+
+  // 1. Load all entries in scope (high limit to get everything meaningful)
+  const entries = await store.list([scope], undefined, 500, 0);
+  const active = entries.filter(isActive);
+
+  const cases = active.filter(e => e.category === "cases");
+  const patterns = active.filter(e => e.category === "patterns");
+
+  const result: PromotionScanResult = {
+    candidates: [],
+    scannedCases: cases.length,
+    scannedPatterns: patterns.length,
+  };
+
+  // 2. Cluster cases by vector similarity
+  if (cases.length >= cfg.minCaseOccurrences) {
+    const clusters = greedyCluster(cases, cfg.caseSimilarityThreshold);
+
+    for (const cluster of clusters) {
+      if (cluster.members.length < cfg.minCaseOccurrences) continue;
+      if (result.candidates.length >= cfg.maxCandidates) break;
+
+      // Compute average intra-cluster similarity for scoring
+      const avgSim = computeAverageIntraClusterSimilarity(cluster.members);
+
+      result.candidates.push({
+        type: "case_to_pattern",
+        sourceEntries: cluster.members.map(m => ({
+          id: m.id,
+          text: m.text,
+          score: avgSim,
+        })),
+        suggestedName: extractName(cluster.seed.text),
+        suggestedDescription: summarizeCluster(cluster.members),
+        confidence: cluster.members.length / (cluster.members.length + 2), // Bayesian smoothing
+      });
+    }
+  }
+
+  // 3. Detect pattern_to_skill candidates
+  for (const pattern of patterns) {
+    if (result.candidates.length >= cfg.maxCandidates) break;
+    if (!hasStructuredSteps(pattern.text)) continue;
+    if (!pattern.vector?.length) continue;
+
+    // Find cases similar to this pattern
+    const similarCases = cases.filter(c => {
+      if (!c.vector?.length) return false;
+      const sim = cosineSimilarity(pattern.vector, c.vector);
+      return sim >= cfg.caseSimilarityThreshold;
+    });
+
+    if (similarCases.length < 2) continue;
+
+    result.candidates.push({
+      type: "pattern_to_skill",
+      sourceEntries: [
+        { id: pattern.id, text: pattern.text, score: 1.0 },
+        ...similarCases.map(c => ({
+          id: c.id,
+          text: c.text,
+          score: cosineSimilarity(pattern.vector, c.vector),
+        })),
+      ],
+      suggestedName: extractName(pattern.text),
+      suggestedDescription: `Skill derived from pattern with ${similarCases.length} supporting cases`,
+      suggestedImplementation: extractSteps(pattern.text),
+      confidence: similarCases.length / (similarCases.length + 2),
+    });
+  }
+
+  // Sort by confidence descending, then truncate
+  result.candidates.sort((a, b) => b.confidence - a.confidence);
+  result.candidates = result.candidates.slice(0, cfg.maxCandidates);
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/** Format scan results for MCP tool output. */
+export function formatPromotionResult(result: PromotionScanResult): string {
+  const lines = [
+    `Promotion scan: ${result.scannedCases} cases, ${result.scannedPatterns} patterns scanned.`,
+  ];
+
+  if (result.candidates.length === 0) {
+    lines.push("No promotion candidates found.");
+    return lines.join("\n");
+  }
+
+  lines.push(`Found ${result.candidates.length} candidate(s):\n`);
+
+  for (const [i, c] of result.candidates.entries()) {
+    lines.push(`### ${i + 1}. [${c.type}] ${c.suggestedName}`);
+    lines.push(`Confidence: ${(c.confidence * 100).toFixed(1)}%`);
+    lines.push(`Description: ${c.suggestedDescription}`);
+    lines.push(`Sources: ${c.sourceEntries.length} entries`);
+    if (c.suggestedImplementation) {
+      lines.push(`Implementation:\n\`\`\`\n${c.suggestedImplementation}\n\`\`\``);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function computeAverageIntraClusterSimilarity(members: MemoryEntry[]): number {
+  if (members.length < 2) return 1.0;
+  let total = 0;
+  let pairs = 0;
+  for (let i = 0; i < members.length; i++) {
+    for (let j = i + 1; j < members.length; j++) {
+      if (members[i].vector?.length && members[j].vector?.length) {
+        total += cosineSimilarity(members[i].vector, members[j].vector);
+        pairs++;
+      }
+    }
+  }
+  return pairs > 0 ? total / pairs : 0;
+}

package/src/skill-schema.ts

@@ -0,0 +1,39 @@
+/**
+ * D-1: Skill Schema — defines the shape of executable skills stored in memory.
+ *
+ * Skills are "what an agent can do" (vs. memories which are "what an agent learned").
+ * Alita/Alita-G showed MCP itself is a natural skill representation format.
+ */
+
+import { z } from "zod";
+
+export const SkillImplementationTypeSchema = z.enum([
+  "bash", "python", "mcp_tool_chain", "instruction_sequence",
+]);
+
+export type SkillImplementationType = z.infer<typeof SkillImplementationTypeSchema>;
+
+export const SkillInputSchema = z.object({
+  name: z.string().min(1).max(120).describe("Unique skill identifier (e.g. 'deploy_production')"),
+  description: z.string().min(1).max(500).describe("Natural language description (used for retrieval)"),
+  triggerPattern: z.string().min(1).max(300).describe("When to suggest this skill"),
+  implementationType: SkillImplementationTypeSchema,
+  implementation: z.string().min(1).max(5000).describe("Executable content"),
+  inputSchema: z.record(z.string(), z.unknown()).optional().describe("Parameter definition (JSON Schema)"),
+  verification: z.string().max(500).optional().describe("How to verify execution success"),
+  scope: z.string().min(1).max(160).describe("Project scope"),
+  source: z.enum(["manual", "agent", "api"]).default("manual"),
+  tags: z.array(z.string().max(60)).max(6).default([]),
+});
+
+export type SkillInput = z.infer<typeof SkillInputSchema>;
+
+export const StoredSkillRecordSchema = SkillInputSchema.extend({
+  id: z.string(),
+  storedAt: z.string().datetime(),
+  successCount: z.number().default(0),
+  failureCount: z.number().default(0),
+  lastRefinedAt: z.string().datetime().optional(),
+});
+
+export type StoredSkillRecord = z.infer<typeof StoredSkillRecordSchema>;