cognitive-core 0.0.2 → 0.1.0

package/src/types/memory.ts

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+
+/**
+ * Experience - Task-level retrieval unit (ReMem-style)
+ * Stores complete (task, solution, feedback) tuples
+ */
+export const ExperienceSchema = z.object({
+  id: z.string(),
+  /** Original task input/description */
+  taskInput: z.string(),
+  /** The solution that was produced */
+  solutionOutput: z.string(),
+  /** Feedback/verification result */
+  feedback: z.string(),
+  /** Whether the experience was successful */
+  success: z.boolean(),
+  /** Domain this experience belongs to */
+  domain: z.string(),
+  /** Embedding for similarity search */
+  embedding: z.array(z.number()).optional(),
+  /** Link back to original trajectory */
+  trajectoryId: z.string(),
+  /** Usage statistics */
+  usageCount: z.number().default(0),
+  /** Creation timestamp */
+  createdAt: z.date().default(() => new Date()),
+  /** Last accessed timestamp */
+  lastAccessedAt: z.date().optional(),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type Experience = z.infer<typeof ExperienceSchema>;
+
+/**
+ * CodeConcept - Reusable code patterns (Stitch/LILO-style)
+ * Three types: primitive (base), learned (extracted), composed (combined)
+ */
+export const CodeConceptSchema = z.object({
+  id: z.string(),
+  /** Human-readable name */
+  name: z.string(),
+  /** Description of what this concept does */
+  description: z.string(),
+  /** The code/pattern itself */
+  code: z.string(),
+  /** Function signature if applicable */
+  signature: z.string().optional(),
+  /** Usage examples: [input, output] pairs */
+  examples: z.array(z.tuple([z.string(), z.string()])).default([]),
+  /** How the concept was created */
+  source: z.enum(['primitive', 'learned', 'composed']),
+  /** Usage statistics */
+  usageCount: z.number().default(0),
+  /** Success rate when used */
+  successRate: z.number().min(0).max(1).default(0),
+  /** Domain this concept belongs to */
+  domain: z.string().optional(),
+  /** Embedding for similarity search */
+  embedding: z.array(z.number()).optional(),
+  /** Parent concepts if composed */
+  parentIds: z.array(z.string()).default([]),
+  /** Creation timestamp */
+  createdAt: z.date().default(() => new Date()),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type CodeConcept = z.infer<typeof CodeConceptSchema>;
+
+/**
+ * Strategy - High-level reasoning patterns (ArcMemo-style)
+ * Abstract "when/what" rules for problem-solving
+ */
+export const StrategySchema = z.object({
+  id: z.string(),
+  /** Situation description: when to apply this strategy */
+  situation: z.string(),
+  /** Suggestion: what to do in this situation */
+  suggestion: z.string(),
+  /** Parameters that can vary in application */
+  parameters: z.array(z.object({
+    name: z.string(),
+    description: z.string(),
+    type: z.string().optional(),
+    defaultValue: z.unknown().optional(),
+  })).default([]),
+  /** Usage statistics */
+  usageCount: z.number().default(0),
+  /** Success rate when applied */
+  successRate: z.number().min(0).max(1).default(0),
+  /** Domain this strategy belongs to */
+  domain: z.string().optional(),
+  /** Embedding for similarity search */
+  embedding: z.array(z.number()).optional(),
+  /** Source trajectories this was extracted from */
+  sourceTrajectoryIds: z.array(z.string()).default([]),
+  /** Creation timestamp */
+  createdAt: z.date().default(() => new Date()),
+  /** Confidence in this strategy */
+  confidence: z.number().min(0).max(1).default(0.5),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type Strategy = z.infer<typeof StrategySchema>;
+
+/**
+ * Skill - A more concrete, actionable form of strategy
+ * Combines situation awareness with specific steps (Claudeception-inspired)
+ */
+export const SkillSchema = z.object({
+  id: z.string(),
+  /** Unique name (kebab-case) */
+  name: z.string(),
+  /** Rich description for semantic matching */
+  description: z.string(),
+  /** The problem this skill solves */
+  problem: z.string(),
+  /** Trigger conditions (specific symptoms, error messages, etc.) */
+  triggers: z.array(z.string()).default([]),
+  /** Step-by-step solution */
+  solution: z.array(z.string()),
+  /** How to verify the skill worked */
+  verification: z.string().optional(),
+  /** Concrete example */
+  example: z.string().optional(),
+  /** Version for tracking updates */
+  version: z.string().default('1.0.0'),
+  /** Domain this skill belongs to */
+  domain: z.string().optional(),
+  /** Embedding for similarity search */
+  embedding: z.array(z.number()).optional(),
+  /** Usage statistics */
+  usageCount: z.number().default(0),
+  /** Success rate */
+  successRate: z.number().min(0).max(1).default(0),
+  /** Creation timestamp */
+  createdAt: z.date().default(() => new Date()),
+  /** Last updated */
+  updatedAt: z.date().default(() => new Date()),
+  /** Additional metadata */
+  metadata: z.record(z.unknown()).default({}),
+});
+
+export type Skill = z.infer<typeof SkillSchema>;
+
+/**
+ * Create a new experience
+ */
+export function createExperience(params: {
+  id?: string;
+  taskInput: string;
+  solutionOutput: string;
+  feedback: string;
+  success: boolean;
+  domain: string;
+  trajectoryId: string;
+  embedding?: number[];
+  metadata?: Record<string, unknown>;
+}): Experience {
+  return ExperienceSchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    taskInput: params.taskInput,
+    solutionOutput: params.solutionOutput,
+    feedback: params.feedback,
+    success: params.success,
+    domain: params.domain,
+    trajectoryId: params.trajectoryId,
+    embedding: params.embedding,
+    metadata: params.metadata ?? {},
+    createdAt: new Date(),
+  });
+}
+
+/**
+ * Create a new code concept
+ */
+export function createConcept(params: {
+  id?: string;
+  name: string;
+  description: string;
+  code: string;
+  signature?: string;
+  source: 'primitive' | 'learned' | 'composed';
+  domain?: string;
+  examples?: [string, string][];
+  parentIds?: string[];
+  metadata?: Record<string, unknown>;
+}): CodeConcept {
+  return CodeConceptSchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    name: params.name,
+    description: params.description,
+    code: params.code,
+    signature: params.signature,
+    source: params.source,
+    domain: params.domain,
+    examples: params.examples ?? [],
+    parentIds: params.parentIds ?? [],
+    metadata: params.metadata ?? {},
+    createdAt: new Date(),
+  });
+}
+
+/**
+ * Create a new strategy
+ */
+export function createStrategy(params: {
+  id?: string;
+  situation: string;
+  suggestion: string;
+  parameters?: Array<{
+    name: string;
+    description: string;
+    type?: string;
+    defaultValue?: unknown;
+  }>;
+  domain?: string;
+  sourceTrajectoryIds?: string[];
+  confidence?: number;
+  metadata?: Record<string, unknown>;
+}): Strategy {
+  return StrategySchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    situation: params.situation,
+    suggestion: params.suggestion,
+    parameters: params.parameters ?? [],
+    domain: params.domain,
+    sourceTrajectoryIds: params.sourceTrajectoryIds ?? [],
+    confidence: params.confidence ?? 0.5,
+    metadata: params.metadata ?? {},
+    createdAt: new Date(),
+  });
+}
+
+/**
+ * Create a new skill
+ */
+export function createSkill(params: {
+  id?: string;
+  name: string;
+  description: string;
+  problem: string;
+  triggers?: string[];
+  solution: string[];
+  verification?: string;
+  example?: string;
+  domain?: string;
+  embedding?: number[];
+  version?: string;
+  metadata?: Record<string, unknown>;
+}): Skill {
+  return SkillSchema.parse({
+    id: params.id ?? crypto.randomUUID(),
+    name: params.name,
+    description: params.description,
+    problem: params.problem,
+    triggers: params.triggers ?? [],
+    solution: params.solution,
+    verification: params.verification,
+    example: params.example,
+    domain: params.domain,
+    embedding: params.embedding,
+    version: params.version ?? '1.0.0',
+    metadata: params.metadata ?? {},
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  });
+}

package/src/types/meta.ts

@@ -0,0 +1,218 @@
+/**
+ * Meta Memory Types
+ *
+ * Types for meta-learning - learning about learning itself
+ * Tracks routing decisions, memory effectiveness, and execution patterns
+ */
+
+/**
+ * MetaObservation - Records for learning about learning
+ * Captures what happened during task execution for later analysis
+ */
+export interface MetaObservation {
+  id: string;
+  trajectoryId: string;
+
+  // === ROUTING DECISION ===
+  routing: RoutingObservation;
+
+  // === MEMORY EFFECTIVENESS ===
+  memoryUsage: MemoryUsageObservation;
+
+  // === EXECUTION PATH ===
+  execution: ExecutionObservation;
+
+  // === OUTCOME ===
+  outcome: OutcomeObservation;
+
+  // === LESSONS (LLM-generated reflection) ===
+  lessons: LessonsLearned;
+
+  timestamp: Date;
+}
+
+/**
+ * Observation about the routing decision
+ */
+export interface RoutingObservation {
+  decision: RoutingDecisionType;
+  confidence: number;
+  reasoning: string;
+}
+
+export type RoutingDecisionType = 'adapt' | 'direct' | 'explore' | 'fallback';
+
+/**
+ * Observation about memory retrieval effectiveness
+ */
+export interface MemoryUsageObservation {
+  experiencesRetrieved: number;
+  playbooksApplied: string[]; // IDs of playbooks used
+  retrievalQuality: RetrievalQuality;
+}
+
+export type RetrievalQuality = 'helpful' | 'neutral' | 'misleading';
+
+/**
+ * Observation about the execution path
+ */
+export interface ExecutionObservation {
+  decompositionUsed: boolean;
+  refinementIterations: number;
+  backtrackingOccurred: boolean;
+  toolsUsed: string[];
+}
+
+/**
+ * Observation about the outcome
+ */
+export interface OutcomeObservation {
+  success: boolean;
+  quality: OutcomeQuality;
+  effortActual: number; // Actual LLM calls
+  effortEstimate: number; // What router predicted
+}
+
+export type OutcomeQuality = 'excellent' | 'good' | 'acceptable' | 'poor';
+
+/**
+ * Lessons learned from the execution
+ */
+export interface LessonsLearned {
+  whatWorked: string[];
+  whatFailed: string[];
+  suggestions: string[]; // How to do better next time
+}
+
+/**
+ * MetaStrategy - Learned patterns about learning itself
+ * Used to adjust routing and retrieval based on context
+ */
+export interface MetaStrategy {
+  id: string;
+  name: string;
+
+  // When to apply this meta-strategy
+  condition: MetaStrategyCondition;
+
+  // What to do differently
+  adjustment: MetaStrategyAdjustment;
+
+  // Track effectiveness
+  applicationCount: number;
+  successRate: number;
+
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Conditions for applying a meta-strategy
+ */
+export interface MetaStrategyCondition {
+  taskCharacteristics: string[]; // "multi-file change", "unfamiliar domain"
+  memoryState: string[]; // "no similar experiences", "low confidence"
+}
+
+/**
+ * Adjustments to make when meta-strategy applies
+ */
+export interface MetaStrategyAdjustment {
+  routingBias: Partial<Record<RoutingDecisionType, number>>;
+  retrievalModification: string; // "expand query", "include adjacent domains"
+  executionHint: string; // "prefer decomposition", "verify incrementally"
+}
+
+/**
+ * Analysis of routing effectiveness
+ */
+export interface RoutingAnalysis {
+  byDecision: Record<string, { total: number; successful: number }>;
+  recommendations: string[];
+}
+
+/**
+ * Analysis of retrieval quality
+ */
+export interface RetrievalAnalysis {
+  helpfulPatterns: string[];
+  misleadingPatterns: string[];
+  recommendations: string[];
+}
+
+/**
+ * Statistics about meta-learning
+ */
+export interface MetaStats {
+  totalObservations: number;
+  totalStrategies: number;
+  observationsByRouting: Record<RoutingDecisionType, number>;
+  averageSuccessRate: number;
+  recentTrend: 'improving' | 'stable' | 'declining';
+}
+
+/**
+ * Context for meta-learning queries
+ */
+export interface MetaContext {
+  taskCharacteristics: string[];
+  memoryState: string[];
+}
+
+/**
+ * Create a new meta-observation with defaults
+ */
+export function createMetaObservation(
+  input: Partial<MetaObservation> & {
+    trajectoryId: string;
+    routing: RoutingObservation;
+    outcome: OutcomeObservation;
+  }
+): MetaObservation {
+  return {
+    id: input.id ?? `meta-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    trajectoryId: input.trajectoryId,
+    routing: input.routing,
+    memoryUsage: input.memoryUsage ?? {
+      experiencesRetrieved: 0,
+      playbooksApplied: [],
+      retrievalQuality: 'neutral',
+    },
+    execution: input.execution ?? {
+      decompositionUsed: false,
+      refinementIterations: 0,
+      backtrackingOccurred: false,
+      toolsUsed: [],
+    },
+    outcome: input.outcome,
+    lessons: input.lessons ?? {
+      whatWorked: [],
+      whatFailed: [],
+      suggestions: [],
+    },
+    timestamp: input.timestamp ?? new Date(),
+  };
+}
+
+/**
+ * Create a new meta-strategy with defaults
+ */
+export function createMetaStrategy(
+  input: Partial<MetaStrategy> & {
+    name: string;
+    condition: MetaStrategyCondition;
+    adjustment: MetaStrategyAdjustment;
+  }
+): MetaStrategy {
+  const now = new Date();
+  return {
+    id: input.id ?? `meta-strategy-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    name: input.name,
+    condition: input.condition,
+    adjustment: input.adjustment,
+    applicationCount: input.applicationCount ?? 0,
+    successRate: input.successRate ?? 0,
+    createdAt: input.createdAt ?? now,
+    updatedAt: input.updatedAt ?? now,
+  };
+}

package/src/types/outcome.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+/**
+ * Outcome - The result of a task attempt
+ */
+export const OutcomeSchema = z.object({
+  /** Whether the task was completed successfully */
+  success: z.boolean(),
+  /** Partial progress score (0.0-1.0) */
+  partialScore: z.number().min(0).max(1).default(0),
+  /** Error information if failed */
+  errorInfo: z.string().optional(),
+  /** Detailed verification results */
+  verificationDetails: z.record(z.unknown()).default({}),
+  /** The final solution/output */
+  solution: z.unknown().optional(),
+});
+
+export type Outcome = z.infer<typeof OutcomeSchema>;
+
+/**
+ * Create a successful outcome
+ */
+export function successOutcome(
+  solution: unknown,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: true,
+    partialScore: 1.0,
+    solution,
+    verificationDetails: details ?? {},
+  });
+}
+
+/**
+ * Create a failed outcome
+ */
+export function failureOutcome(
+  errorInfo: string,
+  partialScore = 0,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: false,
+    partialScore,
+    errorInfo,
+    verificationDetails: details ?? {},
+  });
+}
+
+/**
+ * Create a partial outcome
+ */
+export function partialOutcome(
+  partialScore: number,
+  solution: unknown,
+  details?: Record<string, unknown>
+): Outcome {
+  return OutcomeSchema.parse({
+    success: false,
+    partialScore,
+    solution,
+    verificationDetails: details ?? {},
+  });
+}