cognitive-core 0.2.5 → 0.3.1

package/src/types/knowledge.ts

@@ -1,388 +0,0 @@
-import { z } from 'zod';
-
-// ============================================================================
-// Link Relations (organized by graph layer)
-// ============================================================================
-
-/** Semantic layer relations */
-const SemanticRelations = [
-  'related-to',
-  'depends-on',
-  'specializes',
-  'generalizes',
-  'supports',
-] as const;
-
-/** Temporal layer relations */
-const TemporalRelations = [
-  'observed-before',
-  'observed-after',
-  'co-occurred',
-  'supersedes',
-] as const;
-
-/** Causal layer relations */
-const CausalRelations = [
-  'caused-by',
-  'led-to',
-  'broke',
-  'enabled',
-  'prevented',
-] as const;
-
-/** Entity layer relations */
-const EntityRelations = [
-  'uses',
-  'part-of',
-  'interacts-with',
-  'contradicts',
-  'created-by',
-] as const;
-
-export const AllLinkRelations = [
-  ...SemanticRelations,
-  ...TemporalRelations,
-  ...CausalRelations,
-  ...EntityRelations,
-] as const;
-
-export const LinkRelationSchema = z.enum(AllLinkRelations);
-export type LinkRelation = z.infer<typeof LinkRelationSchema>;
-
-/** Map relation to its natural graph layer */
-export function inferLayerFromRelation(
-  relation: LinkRelation
-): 'semantic' | 'temporal' | 'causal' | 'entity' {
-  if ((SemanticRelations as readonly string[]).includes(relation))
-    return 'semantic';
-  if ((TemporalRelations as readonly string[]).includes(relation))
-    return 'temporal';
-  if ((CausalRelations as readonly string[]).includes(relation))
-    return 'causal';
-  return 'entity';
-}
-
-// ============================================================================
-// Note Types
-// ============================================================================
-
-export const NoteTypeSchema = z.enum([
-  'observation',
-  'entity',
-  'domain-summary',
-]);
-export type NoteType = z.infer<typeof NoteTypeSchema>;
-
-export const SourceOriginSchema = z.enum([
-  'extracted',
-  'agent-authored',
-  'imported',
-]);
-export type SourceOrigin = z.infer<typeof SourceOriginSchema>;
-
-export const GraphLayerNameSchema = z.enum([
-  'semantic',
-  'temporal',
-  'causal',
-  'entity',
-]);
-export type GraphLayerName = z.infer<typeof GraphLayerNameSchema>;
-
-// ============================================================================
-// Knowledge Note Frontmatter Schema
-// ============================================================================
-
-export const KnowledgeLinkSchema = z.object({
-  target: z.string(),
-  relation: LinkRelationSchema,
-  layer: GraphLayerNameSchema.optional(),
-});
-export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>;
-
-export const KnowledgeSourceSchema = z.object({
-  origin: SourceOriginSchema,
-  trajectories: z.array(z.string()).optional(),
-  playbooks: z.array(z.string()).optional(),
-  agentId: z.string().optional(),
-});
-export type KnowledgeSource = z.infer<typeof KnowledgeSourceSchema>;
-
-export const KnowledgeNoteFrontmatterSchema = z.object({
-  /** Unique identifier (kebab-case, prefixed with k- for observations) */
-  id: z.string(),
-  /** Note type determines organization and lifecycle */
-  type: NoteTypeSchema,
-  /** Knowledge domains this note belongs to */
-  domain: z.array(z.string()).default([]),
-  /** Specific entities (tools, libraries, patterns) referenced */
-  entities: z.array(z.string()).default([]),
-  /** Freeform tags for additional categorization */
-  tags: z.array(z.string()).default([]),
-  /** Confidence in this knowledge (0-1) */
-  confidence: z.number().min(0).max(1).default(0.5),
-  /** Where this knowledge came from */
-  source: KnowledgeSourceSchema,
-  /** Explicit links to other knowledge notes */
-  links: z.array(KnowledgeLinkSchema).default([]),
-  /** ISO 8601 creation timestamp */
-  created: z.string(),
-  /** ISO 8601 last updated timestamp */
-  updated: z.string(),
-  /** If this note replaces a previous one (contradiction resolution) */
-  supersedes: z.string().nullable().optional(),
-});
-
-export type KnowledgeNoteFrontmatter = z.infer<
-  typeof KnowledgeNoteFrontmatterSchema
->;
-
-// ============================================================================
-// Knowledge Note (frontmatter + body + file path)
-// ============================================================================
-
-export interface KnowledgeNote {
-  /** Parsed frontmatter */
-  frontmatter: KnowledgeNoteFrontmatter;
-  /** Markdown body content (after frontmatter) */
-  body: string;
-  /** Resolved file path (derived from type + name, not stored in frontmatter) */
-  filePath: string;
-}
-
-// ============================================================================
-// Search & Retrieval
-// ============================================================================
-
-export interface KnowledgeMatch {
-  note: KnowledgeNote;
-  score: number;
-  matchType?: 'domain' | 'entity' | 'semantic' | 'graph';
-}
-
-// ============================================================================
-// Extraction & Evolution Types (used in Phase 2-3, defined now for stability)
-// ============================================================================
-
-export interface EntityUpdate {
-  /** Entity note ID to update */
-  entityId: string;
-  /** Section to append */
-  section: string;
-  /** Evidence source trajectory ID */
-  trajectoryId: string;
-}
-
-export interface Contradiction {
-  /** Existing note that is contradicted */
-  existingNoteId: string;
-  /** New observation that contradicts it */
-  newObservation: KnowledgeNote;
-  /** How they conflict */
-  conflictDescription: string;
-  /** Recommendation */
-  resolution: 'supersede' | 'coexist' | 'review';
-}
-
-export interface PlaybookLink {
-  /** Knowledge note ID */
-  noteId: string;
-  /** Playbook ID */
-  playbookId: string;
-  /** Relationship direction */
-  relation: 'supports' | 'contradicts' | 'contextualizes';
-}
-
-export interface NewLink {
-  from: string;
-  to: string;
-  relation: LinkRelation;
-  layer?: GraphLayerName;
-  weight?: number;
-}
-
-export interface ExtractedKnowledge {
-  /** New observations to create */
-  observations: KnowledgeNote[];
-  /** Updates to existing entity notes (append sections) */
-  entityUpdates: EntityUpdate[];
-  /** Contradictions detected with existing knowledge */
-  contradictions: Contradiction[];
-  /** New links to add to the graph */
-  links: NewLink[];
-  /** Cross-references to playbooks */
-  playbookLinks: PlaybookLink[];
-}
-
-// ============================================================================
-// Lifecycle Result Types
-// ============================================================================
-
-export interface InboxResult {
-  /** Total files processed */
-  processed: number;
-  /** Files that failed to parse/move */
-  failed: number;
-  /** Files moved to observations/ */
-  movedToObservations: number;
-  /** Files moved to entities/ */
-  movedToEntities: number;
-  /** Files moved to domains/ */
-  movedToDomains: number;
-}
-
-export interface DefragResult {
-  /** Inbox processing results */
-  inbox: InboxResult;
-  /** Number of observations consolidated into entity notes */
-  consolidated: number;
-  /** Number of contradictions detected */
-  contradictions: number;
-  /** Whether the graph was rebuilt */
-  graphRebuilt: boolean;
-  /** Number of domain summaries regenerated */
-  domainSummariesRegenerated: number;
-  /** Decay results */
-  decay: DecayResult;
-}
-
-export interface DecayResult {
-  /** Notes with reduced confidence */
-  decayed: number;
-  /** Notes newly marked as stale */
-  newlyStale: number;
-  /** Notes already marked stale */
-  alreadyStale: number;
-}
-
-// ============================================================================
-// Knowledge Bank Stats
-// ============================================================================
-
-export interface KnowledgeStats {
-  observationCount: number;
-  entityCount: number;
-  domainCount: number;
-  inboxCount: number;
-  graph: {
-    nodeCount: number;
-    edgeCountByLayer: Record<string, number>;
-    enabledLayers: string[];
-  };
-  avgConfidence: number;
-  staleCount: number;
-  domainBreakdown: Record<string, number>;
-}
-
-// ============================================================================
-// Factory Functions
-// ============================================================================
-
-let noteCounter = 0;
-
-function generateNoteId(prefix: string): string {
-  const timestamp = Date.now().toString(36);
-  const counter = (noteCounter++).toString(36);
-  return `${prefix}-${timestamp}-${counter}`;
-}
-
-/**
- * Create a new observation note
- */
-export function createObservation(input: {
-  id?: string;
-  title: string;
-  body: string;
-  domain: string[];
-  entities: string[];
-  tags?: string[];
-  confidence?: number;
-  source: KnowledgeSource;
-  links?: KnowledgeLink[];
-}): KnowledgeNote {
-  const now = new Date().toISOString();
-  const id = input.id ?? generateNoteId('k');
-
-  return {
-    frontmatter: {
-      id,
-      type: 'observation',
-      domain: input.domain,
-      entities: input.entities,
-      tags: input.tags ?? [],
-      confidence: input.confidence ?? 0.3,
-      source: input.source,
-      links: input.links ?? [],
-      created: now,
-      updated: now,
-      supersedes: null,
-    },
-    body: `# ${input.title}\n\n${input.body}`,
-    filePath: `knowledge/observations/${id}.md`,
-  };
-}
-
-/**
- * Create a new entity note
- */
-export function createEntityNote(input: {
-  entityName: string;
-  body: string;
-  domain: string[];
-  tags?: string[];
-  confidence?: number;
-  source: KnowledgeSource;
-  links?: KnowledgeLink[];
-}): KnowledgeNote {
-  const now = new Date().toISOString();
-  const slug = input.entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-
-  return {
-    frontmatter: {
-      id: slug,
-      type: 'entity',
-      domain: input.domain,
-      entities: [input.entityName],
-      tags: input.tags ?? [],
-      confidence: input.confidence ?? 0.5,
-      source: input.source,
-      links: input.links ?? [],
-      created: now,
-      updated: now,
-      supersedes: null,
-    },
-    body: `# ${input.entityName}\n\n${input.body}`,
-    filePath: `knowledge/entities/${slug}.md`,
-  };
-}
-
-/**
- * Create a new domain summary note
- */
-export function createDomainSummary(input: {
-  domainName: string;
-  body: string;
-  entities?: string[];
-  tags?: string[];
-  source: KnowledgeSource;
-}): KnowledgeNote {
-  const now = new Date().toISOString();
-  const slug = input.domainName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-
-  return {
-    frontmatter: {
-      id: slug,
-      type: 'domain-summary',
-      domain: [input.domainName],
-      entities: input.entities ?? [],
-      tags: input.tags ?? [],
-      confidence: 1.0,
-      source: input.source,
-      links: [],
-      created: now,
-      updated: now,
-      supersedes: null,
-    },
-    body: `# ${input.domainName}\n\n${input.body}`,
-    filePath: `knowledge/domains/${slug}.md`,
-  };
-}

package/src/types/memory.ts

@@ -1,300 +0,0 @@
-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),
-  /** Composite access score — decays over time, bumped on retrieval/success */
-  accessScore: z.number().default(0),
-  /** Number of times this experience was a findSimilar() hit */
-  retrievalCount: z.number().default(0),
-  /** Creation timestamp */
-  createdAt: z.date().default(() => new Date()),
-  /** Last accessed timestamp */
-  lastAccessedAt: z.date().optional(),
-  /** Memory tier — determines fidelity and compression level */
-  tier: z.enum(['hot', 'warm', 'cold']).default('hot'),
-  /** Compressed representation (populated for warm/cold tiers) */
-  compressed: z.object({
-    keySteps: z.array(z.string()),
-    summary: z.string(),
-    originalStepCount: z.number(),
-  }).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>;
-
-/**
- * ReflexionEpisode — structured self-reflection on a completed trajectory.
- * Generated by the ReflexionGenerator after each trajectory completion.
- */
-export interface ReflexionEpisode {
-  id: string;
-  trajectoryId: string;
-  taskSummary: string;
-  outcome: 'success' | 'partial' | 'failure';
-  selfCritique: string;
-  keyInsights: string[];
-  strategyAssessment: string;
-  suggestedPlaybookUpdates: string[];
-  domain: string;
-  createdAt: Date;
-}
-
-/**
- * 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,
-    accessScore: params.success ? 1.0 : 0.3,
-    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(),
-  });
-}