cognitive-core 0.0.2 → 0.1.2

package/src/types/knowledge.ts

@@ -0,0 +1,388 @@
+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

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