cognitive-core 0.0.2 → 0.1.2

package/src/types/index.ts

@@ -0,0 +1,286 @@
+// Core types
+export {
+  type Task,
+  type VerificationSpec,
+  TaskSchema,
+  VerificationSpecSchema,
+  createTask,
+} from './task.js';
+
+export {
+  type Step,
+  StepSchema,
+  createStep,
+} from './step.js';
+
+export {
+  type Outcome,
+  OutcomeSchema,
+  successOutcome,
+  failureOutcome,
+  partialOutcome,
+} from './outcome.js';
+
+export {
+  type Trajectory,
+  TrajectorySchema,
+  createTrajectory,
+  isSuccessful,
+  getKeySteps,
+} from './trajectory.js';
+
+// Memory types
+export {
+  type Experience,
+  type CodeConcept,
+  type Strategy,
+  type Skill,
+  ExperienceSchema,
+  CodeConceptSchema,
+  StrategySchema,
+  SkillSchema,
+  createExperience,
+  createConcept,
+  createStrategy,
+  createSkill,
+} from './memory.js';
+
+// Playbook types (replaces Strategy + Skill)
+export {
+  type Playbook,
+  type PlaybookApplicability,
+  type PlaybookGuidance,
+  type PlaybookVerification,
+  type PlaybookEvolution,
+  type PlaybookProvenance,
+  type PlaybookOrigin,
+  type FailureRecord,
+  type Refinement,
+  type PlaybookComplexity,
+  createPlaybook,
+  bumpPlaybookVersion,
+  getPlaybookSuccessRate,
+  hasReliableStats,
+} from './playbook.js';
+
+// Meta-learning types
+export {
+  type MetaObservation,
+  type RoutingObservation,
+  type RoutingDecisionType,
+  type MemoryUsageObservation,
+  type RetrievalQuality,
+  type ExecutionObservation,
+  type OutcomeObservation,
+  type OutcomeQuality,
+  type LessonsLearned,
+  type MetaStrategy,
+  type MetaStrategyCondition,
+  type MetaStrategyAdjustment,
+  type RoutingAnalysis,
+  type RetrievalAnalysis,
+  type MetaStats,
+  type MetaContext,
+  createMetaObservation,
+  createMetaStrategy,
+} from './meta.js';
+
+// Team trajectory types
+export {
+  type TeamTrajectory,
+  type TeamEvent,
+  type TeamEventType,
+  type InteractionEdge,
+  type CoordinationMetrics,
+  type MemberOutcome,
+  type TeamOutcome,
+  type InteractionType,
+  type InteractionTag,
+  type ExpectedInteractionPattern,
+  type TeamTrajectoryInput,
+  type MemberTrajectoryInput,
+  type MemberTrajectory,
+  type AgentInteraction,
+  type GraphStructuralMetrics,
+  createTeamTrajectory,
+  isTeamSuccessful,
+  buildInteractionGraph,
+  buildTeamTrajectory,
+} from './team-trajectory.js';
+
+// Team playbook types
+export {
+  type TeamPlaybook,
+  type TeamPlaybookApplicability,
+  type TeamCompositionGuidance,
+  type TeamRoleSpec,
+  type TeamCoordinationGuidance,
+  type TeamChannelSpec,
+  type InteractionPattern,
+  type TeamPlaybookVerification,
+  type TeamPlaybookEvolution,
+  type TeamRefinement,
+  type RolePlaybook,
+  type RoleTeamContext,
+  type RoleGuidance,
+  type RoleInteractionGuidance,
+  type RoleDecisionFramework,
+  type RolePlaybookEvolution,
+  type RolePlaybookReference,
+  type RelatedTaskPlaybook,
+  createTeamPlaybook,
+  createRolePlaybook,
+  getTeamPlaybookSuccessRate,
+  getRolePlaybookSuccessRate,
+} from './team-playbook.js';
+
+// Team meta-learning types
+export {
+  type TeamMetaObservation,
+  type FormationObservation,
+  type CompositionObservation,
+  type CoordinationObservation,
+  type TeamOutcomeObservation,
+  type TeamLessonsLearned,
+  type TeamMetaStrategy,
+  type TeamMetaCondition,
+  type TeamMetaAdjustment,
+  createTeamMetaObservation,
+  createTeamMetaStrategy,
+} from './team-meta.js';
+
+// Knowledge types
+export {
+  type KnowledgeNoteFrontmatter,
+  type KnowledgeNote,
+  type KnowledgeMatch,
+  type KnowledgeSource,
+  type KnowledgeLink,
+  type NoteType,
+  type LinkRelation,
+  type SourceOrigin,
+  type GraphLayerName,
+  type EntityUpdate,
+  type Contradiction,
+  type PlaybookLink as KnowledgePlaybookLink,
+  type NewLink,
+  type ExtractedKnowledge,
+  type InboxResult,
+  type DefragResult,
+  type DecayResult,
+  type KnowledgeStats,
+  KnowledgeNoteFrontmatterSchema,
+  NoteTypeSchema,
+  LinkRelationSchema,
+  GraphLayerNameSchema,
+  AllLinkRelations,
+  inferLayerFromRelation,
+  createObservation,
+  createEntityNote,
+  createDomainSummary,
+} from './knowledge.js';
+
+// Knowledge graph types
+export {
+  type GraphNode,
+  type GraphEdge,
+  type GraphLayer,
+  type KnowledgeMultiGraph,
+  type GraphLayerOperations,
+  type GraphNodeFilter,
+  type NeighborOptions,
+  type KnowledgeGraphManagerInterface,
+  type GraphConfig,
+  DEFAULT_GRAPH_CONFIG,
+  SEMANTIC_RELATIONS,
+  TEMPORAL_RELATIONS,
+  CAUSAL_RELATIONS,
+  ENTITY_RELATIONS,
+} from './knowledge-graph.js';
+
+// Trajectory source types
+export {
+  type TrajectorySource,
+  type TrajectoryWithAnalysis,
+  type TrajectoryLoadOptions,
+} from './trajectory-source.js';
+
+// DataClaw types (dataclaw JSONL trajectory exports)
+export {
+  type DataclawSession,
+  type DataclawMessage,
+  type DataclawToolUse,
+  type DataclawStats,
+  type DataclawMetadata,
+  DataclawSessionSchema,
+  DataclawMessageSchema,
+  DataclawToolUseSchema,
+  DataclawStatsSchema,
+  DataclawMetadataSchema,
+} from './dataclaw.js';
+
+// Configuration types
+export {
+  type CreditStrategy,
+  type PatternExtractor,
+  type LearningConfig,
+  type RouterConfig,
+  type MemoryConfig,
+  type MemoryCapacityConfig,
+  type StorageConfig,
+  type EmbeddingProviderType,
+  type EmbeddingConfig,
+  type ExecutionBackend,
+  type ExecutionConfig,
+  type RefinementConfig,
+  type SkillPromotionConfig,
+  type SkillLimitsConfig,
+  type SkillContextConfig,
+  type SkillDemotionConfig,
+  type SkillLibraryConfig,
+  type MCPServerConfig,
+  type CompressionConfig,
+  type TeamLearningConfig,
+  type AgenticTaskRunnerConfig,
+  type KnowledgeBankConfig,
+  type KnowledgeExtractionConfig,
+  type KnowledgeSurfacingConfig,
+  type ConfidenceConfig,
+  type GraphConfigType,
+  type DefragConfig,
+  type SkillTreeConfig,
+  type SessionBankConfig,
+  type AtlasConfig,
+  SessionBankConfigSchema,
+  KnowledgeBankConfigSchema,
+  KnowledgeExtractionConfigSchema,
+  KnowledgeSurfacingConfigSchema,
+  ConfidenceConfigSchema,
+  GraphConfigSchema,
+  DefragConfigSchema,
+  CreditStrategySchema,
+  PatternExtractorSchema,
+  LearningConfigSchema,
+  RouterConfigSchema,
+  MemoryConfigSchema,
+  MemoryCapacityConfigSchema,
+  StorageConfigSchema,
+  EmbeddingProviderTypeSchema,
+  EmbeddingConfigSchema,
+  ExecutionBackendSchema,
+  ExecutionConfigSchema,
+  RefinementConfigSchema,
+  SkillPromotionConfigSchema,
+  SkillLimitsConfigSchema,
+  SkillContextConfigSchema,
+  SkillDemotionConfigSchema,
+  SkillLibraryConfigSchema,
+  MCPServerConfigSchema,
+  CompressionConfigSchema,
+  TeamLearningConfigSchema,
+  AgenticTaskRunnerConfigSchema,
+  SkillTreeConfigSchema,
+  AtlasConfigSchema,
+  createDefaultConfig,
+  mergeConfig,
+} from './config.js';

package/src/types/knowledge-graph.ts

@@ -0,0 +1,246 @@
+import type { GraphLayerName, KnowledgeNote, LinkRelation } from './knowledge.js';
+
+// ============================================================================
+// Graph Node (shared across all layers)
+// ============================================================================
+
+export interface GraphNode {
+  /** Knowledge note ID */
+  id: string;
+  /** Relative file path from memory root */
+  file: string;
+  /** Note type */
+  type: 'observation' | 'entity' | 'domain-summary';
+  /** Domains for fast filtering */
+  domains: string[];
+  /** Entities for fast filtering */
+  entities: string[];
+  /** Tags for fast filtering */
+  tags: string[];
+  /** Current confidence */
+  confidence: number;
+  /** Last updated timestamp (ISO 8601) */
+  updated: string;
+}
+
+// ============================================================================
+// Graph Edge (within a specific layer)
+// ============================================================================
+
+export interface GraphEdge {
+  /** Source note ID */
+  from: string;
+  /** Target note ID */
+  to: string;
+  /** Relationship type */
+  relation: string;
+  /** Edge weight (0-1, for ranked traversal) */
+  weight: number;
+  /** When this edge was established (ISO 8601) */
+  created: string;
+  /** Whether this edge crosses into another system */
+  crossSystem?: 'playbook' | 'experience';
+  /** Source trajectory that produced this edge, if any */
+  sourceTrajectory?: string;
+}
+
+// ============================================================================
+// Graph Layer
+// ============================================================================
+
+export interface GraphLayer {
+  /** Layer identifier */
+  name: GraphLayerName;
+  /** Whether this layer is currently enabled */
+  enabled: boolean;
+  /** Edges in this layer */
+  edges: GraphEdge[];
+}
+
+// ============================================================================
+// Multi-Graph Structure (top-level persisted format)
+// ============================================================================
+
+export interface KnowledgeMultiGraph {
+  /** Schema version for migration */
+  version: number;
+  /** Last rebuild timestamp */
+  lastRebuilt: string;
+  /** Shared node registry */
+  nodes: Record<string, GraphNode>;
+  /** Graph layers — each independently toggleable */
+  layers: Record<GraphLayerName, GraphLayer>;
+}
+
+// ============================================================================
+// Layer Operations Interface
+// ============================================================================
+
+export interface GraphLayerOperations {
+  /** Layer name */
+  readonly name: GraphLayerName;
+
+  /** Whether this layer is enabled */
+  readonly enabled: boolean;
+
+  /** Get edges from/to a node in this layer */
+  getEdges(
+    nodeId: string,
+    direction?: 'outgoing' | 'incoming' | 'both'
+  ): GraphEdge[];
+
+  /** BFS neighbors within this layer */
+  neighbors(nodeId: string, depth?: number): string[];
+
+  /** Shortest path between two nodes within this layer */
+  pathBetween(fromId: string, toId: string): string[] | null;
+
+  /** Add an edge to this layer */
+  addEdge(edge: GraphEdge): void;
+
+  /** Remove an edge from this layer */
+  removeEdge(fromId: string, toId: string, relation: string): void;
+
+  /** Get all edges in this layer */
+  getAllEdges(): GraphEdge[];
+
+  /** Get edge count */
+  edgeCount(): number;
+
+  /** Rebuild this layer from knowledge notes */
+  rebuild(notes: KnowledgeNote[]): void;
+
+  /** Clear all edges */
+  clear(): void;
+}
+
+// ============================================================================
+// Graph Manager Interface
+// ============================================================================
+
+export interface GraphNodeFilter {
+  domains?: string[];
+  entities?: string[];
+  tags?: string[];
+  type?: GraphNode['type'];
+  minConfidence?: number;
+}
+
+export interface NeighborOptions {
+  depth?: number;
+  layers?: GraphLayerName[];
+  minWeight?: number;
+}
+
+export interface KnowledgeGraphManagerInterface {
+  /** Get a specific layer */
+  getLayer(name: GraphLayerName): GraphLayerOperations | null;
+
+  /** Query across all enabled layers (union of edges) */
+  neighbors(nodeId: string, options?: NeighborOptions): GraphNode[];
+
+  /** Cross-layer path: can traverse edges from any enabled layer */
+  pathBetween(
+    fromId: string,
+    toId: string,
+    options?: { layers?: GraphLayerName[] }
+  ): Array<{ node: GraphNode; edge: GraphEdge; layer: GraphLayerName }> | null;
+
+  /** Filter nodes by criteria */
+  filterNodes(filter: GraphNodeFilter): GraphNode[];
+
+  /** Get cross-system links (to playbooks/experiences) */
+  crossSystemLinks(nodeId: string): GraphEdge[];
+
+  /** Add a node to the shared registry */
+  addNode(node: GraphNode): void;
+
+  /** Remove a node from the shared registry and all layers */
+  removeNode(nodeId: string): void;
+
+  /** Get a node by ID */
+  getNode(nodeId: string): GraphNode | undefined;
+
+  /** Get all nodes */
+  getAllNodes(): GraphNode[];
+
+  /** Rebuild all enabled layers from notes */
+  rebuildAll(notes: KnowledgeNote[]): void;
+
+  /** Load graph from disk */
+  loadFromDisk(dir: string): Promise<void>;
+
+  /** Save graph to disk */
+  saveToDisk(dir: string): Promise<void>;
+
+  /** Get statistics */
+  getStats(): {
+    nodeCount: number;
+    edgeCountByLayer: Record<string, number>;
+    enabledLayers: string[];
+  };
+}
+
+// ============================================================================
+// Graph Configuration
+// ============================================================================
+
+export interface GraphConfig {
+  /** Which graph layers to enable */
+  enabledLayers: GraphLayerName[];
+  /** Whether to auto-infer temporal edges from timestamps */
+  inferTemporalEdges: boolean;
+  /** Whether to auto-infer causal edges from failure-recovery patterns */
+  inferCausalEdges: boolean;
+  /** Whether to auto-infer entity edges from shared entity tags */
+  inferEntityEdges: boolean;
+  /** Split layer files by domain when node count exceeds this */
+  domainSplitThreshold: number;
+  /** Promote to SQLite when total edge count exceeds this */
+  sqlitePromotionThreshold: number;
+}
+
+/** Default graph configuration */
+export const DEFAULT_GRAPH_CONFIG: GraphConfig = {
+  enabledLayers: ['semantic'],
+  inferTemporalEdges: true,
+  inferCausalEdges: true,
+  inferEntityEdges: true,
+  domainSplitThreshold: 500,
+  sqlitePromotionThreshold: 10000,
+};
+
+// ============================================================================
+// Valid relation sets per layer (for layer implementations)
+// ============================================================================
+
+export const SEMANTIC_RELATIONS: readonly LinkRelation[] = [
+  'related-to',
+  'depends-on',
+  'specializes',
+  'generalizes',
+  'supports',
+];
+
+export const TEMPORAL_RELATIONS: readonly LinkRelation[] = [
+  'observed-before',
+  'observed-after',
+  'co-occurred',
+  'supersedes',
+];
+
+export const CAUSAL_RELATIONS: readonly LinkRelation[] = [
+  'caused-by',
+  'led-to',
+  'broke',
+  'enabled',
+  'prevented',
+];
+
+export const ENTITY_RELATIONS: readonly LinkRelation[] = [
+  'uses',
+  'part-of',
+  'interacts-with',
+  'contradicts',
+  'created-by',
+];