cognitive-core 0.1.0 → 0.1.2

package/README.md

@@ -1,29 +1,36 @@
-# Atlas
+# cognitive-core
 
-**Adaptive Trajectory Learning and Abstraction System**
+A TypeScript learning system for AI agents. Records how agents solve problems, extracts reusable playbooks and factual knowledge from trajectories, and injects relevant guidance into future tasks.
 
-A TypeScript-native cognitive core for building AI agents that learn from experience. Atlas extracts strategies, concepts, and skills from problem-solving trajectories to improve future performance.
+## Table of Contents
 
-## Features
+- [Motivation](#motivation)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Knowledge Bank](#knowledge-bank)
+- [CLI](#cli)
+- [Agent Backends](#agent-backends)
+- [Skill Library](#skill-library)
+- [Configuration](#configuration)
+- [Core Types](#core-types)
+- [Research References](#research-references)
+- [Limitations](#limitations)
+- [Contributing](#contributing)
+- [License](#license)
 
-- **Memory System**: Four complementary memory types for different abstraction levels
-  - **Experience Memory** (ReMem-style): Task-level retrieval of similar past experiences
-  - **Concept Library** (Stitch/LILO-style): Reusable code patterns and abstractions
-  - **Strategy Bank** (ArcMemo-style): High-level reasoning patterns
-  - **Skill Store** (Claudeception-inspired): Actionable skills with specific triggers
+## Motivation
 
-- **Learning Engine**: Automatic extraction of knowledge from trajectories
-  - Credit assignment for identifying key steps
-  - Pattern extraction using text analysis or LLM agents
-  - Deduplication to prevent redundant learning
 
-- **Agent-Based Extractors**: LLM-powered extraction of:
-  - Strategies (when/what rules)
-  - Code concepts (reusable patterns)
-  - Skills (concrete solutions with triggers)
+cognitive-core gives agents persistent, structured memory:
 
-- **Task Router**: Smart routing based on memory similarity
-- **Lightweight Persistence**: JSON file-based storage
+1. **Trajectories** record what the agent did (ReAct-style thought/action/observation steps)
+2. **Playbooks** distill trajectories into reusable guidance (strategy, tactics, verification criteria)
+3. **Knowledge Bank** extracts and organizes factual knowledge — what agents learn about tools, libraries, and patterns
+4. **Routing** matches incoming tasks to relevant playbooks before the agent starts working
+5. **Meta-learning** tracks which playbooks helped and adjusts routing over time
+
+The result: agents that get measurably better at recurring problem types without fine-tuning or prompt engineering.
 
 ## Installation
 
@@ -31,333 +38,596 @@ A TypeScript-native cognitive core for building AI agents that learn from experi
 npm install cognitive-core
 ```
 
+Requires Node.js 18+.
+
 ## Quick Start
 
-### Using with Agent Backends (Recommended)
+### Solve a task with memory-augmented agents
 
 ```typescript
 import { createAtlasWithAgents, createTask, createMockBackend } from 'cognitive-core';
 
-// Create Atlas with agent backends
 const atlas = createAtlasWithAgents(
-  [createMockBackend()],  // Use mock backend for testing
-  { storage: { baseDir: '.atlas' } }
+  [createMockBackend()],
+  { storage: { baseDir: '.cognitive-core' } }
 );
 
-// Initialize (loads persisted data)
 await atlas.init();
 
-// Create and solve a task
-const task = createTask({
+const result = await atlas.solve(createTask({
   domain: 'code',
-  description: 'Write a function that checks if a number is prime',
-});
-
-const result = await atlas.solve(task);
-console.log('Success:', result.trajectory.outcome.success);
-console.log('Routing strategy:', result.routing?.strategy);
-console.log('Used refinement:', !!result.refinement);
+  description: 'Fix the TypeScript compilation error in auth.ts',
+}));
 
-// Get stats
-const stats = await atlas.getStats();
-console.log('Memory stats:', stats.memory);
-console.log('Backends:', stats.execution?.backends);
+console.log(result.trajectory.outcome.success);  // true
+console.log(result.routing?.strategy);            // 'direct' | 'adapt' | 'explore' | 'fallback'
+console.log(result.injectedPlaybooks?.length);    // number of playbooks injected
 
-// Close (persists data)
 await atlas.close();
 ```
 
-### Setting Up Real Agent Backends
+### Feed trajectories from external agents
+
+cognitive-core can learn from trajectories produced by external agents. Record what happened elsewhere and feed it in.
 
 ```typescript
-import {
-  createAtlasWithAgents,
-  createSubprocessBackend,
-  createTask
-} from 'cognitive-core';
-
-// Create a subprocess backend for Claude Code or other CLI agents
-const claudeBackend = createSubprocessBackend({
-  name: 'claude-code',
-  command: 'claude',
-  args: ['--print'],
-  supportedTypes: ['claude-code', 'default'],
+import { createAtlas, createTrajectory, createTask, createStep, successOutcome } from 'cognitive-core';
+
+const atlas = createAtlas({ storage: { baseDir: '.cognitive-core' } });
+await atlas.init();
+
+const trajectory = createTrajectory({
+  task: createTask({
+    domain: 'code',
+    description: 'Fix the null pointer exception in user service',
+  }),
+  steps: [
+    createStep({
+      thought: 'Check where the null value originates',
+      action: 'Read src/services/user.ts',
+      observation: 'getUserById returns undefined when user not found',
+    }),
+    createStep({
+      thought: 'Add a guard clause before accessing user properties',
+      action: 'Edit src/services/user.ts to add null check',
+      observation: 'Added: if (!user) return null',
+    }),
+  ],
+  outcome: successOutcome('Fixed by adding null check in getUserById'),
+  agentId: 'claude-code',
 });
 
-// Create Atlas with real backends
-const atlas = createAtlasWithAgents([claudeBackend], {
-  storage: { baseDir: '.atlas' },
-  execution: {
-    defaultAgentType: 'claude-code',
-    maxExecutionTime: 300,  // 5 minutes
-    captureToolCalls: true,
-  },
-  refinement: {
-    useAgentEvaluation: true,
-    maxIterations: 3,
-  },
+const result = await atlas.processTrajectory(trajectory);
+console.log(result.abstractable);  // true - system can extract a playbook from this
+
+await atlas.close();
+```
+
+### Query memory directly
+
+```typescript
+const context = await atlas.queryMemory('typescript import resolution error', {
+  domains: ['code'],
+  includePlaybooks: true,
 });
 
-await atlas.init();
+for (const { playbook, score } of context.playbooks) {
+  console.log(`${playbook.name} (${Math.round(score * 100)}% match)`);
+  console.log(`  Strategy: ${playbook.guidance.strategy}`);
+  console.log(`  Tactics: ${playbook.guidance.tactics.join(', ')}`);
+}
+```
 
-// Solve with memory-augmented context
-const result = await atlas.solve(createTask({
-  domain: 'code',
-  description: 'Fix the TypeScript compilation error in auth.ts',
-}));
+## How It Works
+
+### Solve flow
+
+Every call to `atlas.solve(task)` runs through this pipeline:
+
+```mermaid
+flowchart TD
+    Task[Task arrives] --> Router[TaskRouter]
+
+    Router -->|queries| Memory[MemorySystem]
+    Memory --> Exp[ExperienceMemory]
+    Memory --> PB[PlaybookLibrary]
+    Memory --> KB[KnowledgeBank]
+    Memory --> Meta[MetaMemory]
+
+    Router --> Decision{RoutingDecision}
+
+    Decision --> Agent[AgentManager]
+    Agent -->|injects playbooks + knowledge| Backend[Backend]
+    Backend -->|returns trajectory| Session[AgentSession]
+
+    Session --> Check{Succeeded?}
+    Check -->|Yes| Learn[LearningPipeline]
+    Check -->|No| Refine{Retry?}
+    Refine -->|Yes, max 3x| Agent
+    Refine -->|No| Learn
+
+    Learn --> Analyze[TrajectoryAnalyzer]
+    Learn --> Extract[PlaybookExtractor]
+    Learn --> KnowExtract[KnowledgeExtractor]
+    Learn --> Usage[UsageInference]
+    Learn --> MetaLearn[MetaLearner]
+
+    Analyze --> Updated[Memory updated]
+    Extract --> Updated
+    KnowExtract --> Updated
+    Usage --> Updated
+    MetaLearn --> Updated
+
+    Updated -.->|next task| Router
 ```
 
-## Architecture
+### Playbook lifecycle
+
+A playbook starts with low confidence (0.3) after extraction from a cluster of similar trajectories. Each time it's injected into an agent and the task succeeds, confidence grows. After enough successful uses (default: 5 successes, 80%+ success rate), it gets promoted to a **core skill** that's always in the system prompt. If it starts failing in specific contexts, the system records refinements rather than discarding the playbook entirely.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Extracted : pattern found across trajectories
+
+    Extracted --> Contextual : confidence above 0.3
+    Contextual --> Domain : tagged to domain
+
+    Contextual --> Contextual : success
+    Domain --> Domain : success
+
+    Domain --> Core : 0.85+ confidence, 5+ successes, 80%+ rate
+    Core --> Core : success
+
+    Core --> Domain : 3 consecutive failures
+    Domain --> Contextual : confidence drops
 
+    Contextual --> Refined : failure in specific context
+    Refined --> Contextual : refinement recorded
 ```
-Atlas
-├── Memory System
-│   ├── ExperienceMemory    # Task-level retrieval (k=4)
-│   ├── PlaybookLibrary     # Actionable playbooks with triggers
-│   └── MetaMemory          # Meta-learning observations
-│
-├── Learning Engine
-│   ├── TrajectoryAnalyzer  # Credit assignment
-│   ├── PlaybookExtractor   # Pattern discovery & playbook creation
-│   ├── MetaLearner         # Adaptive routing improvements
-│   ├── UsageInference      # Track playbook effectiveness
-│   └── LearningPipeline    # Batch learning orchestration
-│
-├── Surfacing
-│   ├── SkillLibrary        # Tiered skill management (core/domain/contextual)
-│   └── PlaybookMCPServer   # MCP protocol for on-demand access
-│
-├── Runtime
-│   ├── AgentManager        # Spawn and observe agents
-│   ├── Backends            # Mock, Subprocess, ACP backends
-│   └── KnowledgeInjector   # Format memory for agent context
-│
-├── Search/Routing
-│   ├── TaskRouter          # Smart routing with meta-learning
-│   ├── RefinementLoop      # Iterative solution improvement
-│   └── SolutionEvaluator   # Quality assessment
-│
-└── Integration
-    └── skill-tree          # Federated skill library management
+
+### Memory architecture
+
+The four memory stores serve different retrieval patterns:
+
+```mermaid
+graph LR
+    subgraph MemorySystem
+        E[ExperienceMemory]
+        P[PlaybookLibrary]
+        K[KnowledgeBank]
+        M[MetaMemory]
+    end
+
+    subgraph Search
+        BM[BM25 Index]
+        VS[sqlite-vec]
+        TS[Text Similarity]
+    end
+
+    subgraph Providers
+        OAI[OpenAI]
+        VOY[Voyage]
+        HF[HuggingFace local]
+        MM[minimem optional]
+    end
+
+    E --> BM
+    E --> VS
+    P --> BM
+    P --> VS
+    K --> TS
+    K -.-> MM
+    VS -.-> OAI
+    VS -.-> VOY
+    VS -.-> HF
+
+    subgraph Storage
+        JSON[JSON files]
+        SQL[SQLite]
+        MD[Markdown + YAML]
+    end
+
+    E --> JSON
+    P --> JSON
+    M --> JSON
+    K --> MD
+    VS --> SQL
 ```
 
-## Core Types
+| Store | Purpose | Format |
+|-------|---------|--------|
+| **ExperienceMemory** | Episodic — *what happened* | JSON |
+| **PlaybookLibrary** | Procedural — *how to do things* | JSON |
+| **KnowledgeBank** | Semantic — *facts, concepts, relationships* | Markdown + YAML frontmatter |
+| **MetaMemory** | Meta-learning — *what worked* | JSON |
 
-### Task
-```typescript
-interface Task {
-  id: string;
-  domain: string;          // e.g., 'code', 'reasoning', 'arc'
-  description: string;
-  context: Record<string, unknown>;
-  verification?: VerificationSpec;
-}
+### Search and matching
+
+Memory search uses BM25 text matching by default. For higher-quality retrieval, plug in an embedding provider (OpenAI, Voyage, or local via `@huggingface/transformers`) and cognitive-core switches to hybrid BM25 + vector search backed by `sqlite-vec`.
+
+Knowledge bank search uses text similarity by default, with optional delegation to [minimem](https://github.com/alexngai/minimem) for hybrid vector + BM25 search when available.
+
+## Knowledge Bank
+
+The knowledge bank is a **semantic memory** store for facts, concepts, and relationships that agents learn from experience. While playbooks capture *how* to do things, the knowledge bank captures *what agents know* — facts about tools, libraries, version-specific behavior, and causal relationships.
+
+### Knowledge note types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Observation** | Atomic fact learned from experience | "Prisma requires `db push` before `migrate dev` when schema has drifted" |
+| **Entity** | Living document about a tool/library/pattern | "Everything I know about Prisma" |
+| **Domain summary** | High-level overview of a knowledge domain | "Database knowledge overview" |
+
+### How knowledge is stored
+
+Knowledge notes are plain Markdown files with structured YAML frontmatter, organized on the filesystem:
+
+```
+knowledge/
+├── observations/    # Atomic facts (k-*.md)
+├── entities/        # Living entity docs (prisma.md, vitest.md)
+└── domains/         # Domain summaries (database.md, testing.md)
 ```
 
-### Trajectory
-```typescript
-interface Trajectory {
-  id: string;
-  task: Task;
-  steps: Step[];           // ReAct-style steps
-  outcome: Outcome;
-  agentId: string;
-  llmCalls: number;
-  totalTokens: number;
-  wallTimeSeconds: number;
-}
+Any agent with filesystem access can browse, grep, and read knowledge directly — no special API required.
+
+### Multi-layer knowledge graph
+
+Relationships between knowledge notes are tracked in a multi-layer graph overlay (inspired by [MAGMA](https://arxiv.org/abs/2601.03236)):
+
+| Layer | Captures | Example |
+|-------|----------|---------|
+| **Semantic** | Conceptual relationships | "Prisma *depends-on* PostgreSQL" |
+| **Temporal** | When knowledge was learned | "Observation A *supersedes* B" |
+| **Causal** | Cause-effect chains | "Upgrading TS 5.4 *broke* enum const exports" |
+| **Entity** | Tool/component interactions | "Next.js *uses* React" |
+
+### Knowledge lifecycle
+
+```
+Trajectory → KnowledgeExtractor → Observations (confidence: 0.3)
+                                        │
+                              reinforced by more trajectories
+                                        │
+                                  Observations (confidence: 0.5-0.8)
+                                        │
+                              consolidated into entity notes
+                                        │
+                                  Entity Notes (living docs)
+                                        │
+                              domain summaries regenerated
+                                        │
+                                  Domain Summaries
 ```
 
-### Strategy
+Knowledge evolves through:
+- **Reinforcement** — same fact observed again increases confidence
+- **Contradiction detection** — conflicting facts are flagged and resolved
+- **Consolidation** — observations about the same entity merge into entity notes
+- **Decay** — unvalidated knowledge gradually loses confidence
+
+### Knowledge surfacing
+
+During `atlas.solve()`, relevant knowledge is surfaced alongside playbooks as an independent context section:
+
 ```typescript
-interface Strategy {
-  situation: string;       // When to apply
-  suggestion: string;      // What to do
-  parameters: Parameter[];
-  confidence: number;
-  successRate: number;
-}
+const result = await atlas.solve(task);
+console.log(result.surfacedKnowledge?.length);  // knowledge notes injected
+```
+
+Three-tier retrieval:
+1. **Domain match** — if the task domain matches a knowledge domain, include the domain summary
+2. **Entity match** — if the task mentions known entities, include their notes
+3. **Semantic match** — text similarity search for contextually relevant observations
+
+### minimem integration
+
+When [minimem](https://github.com/alexngai/minimem) is available, the knowledge bank can delegate search to minimem's hybrid search (vector + BM25) for higher-quality retrieval. Set `minimemAware: true` in config to enable. The two systems communicate via file conventions only — no cross-package imports.
+
+See [Design Doc](docs/DESIGN-semantic-memory-knowledge-bank.md) for the full architecture.
+
+## CLI
+
+cognitive-core ships a CLI for querying playbooks and storing trajectories without writing code.
+
+```bash
+# Initialize storage
+cognitive-core init --dir .cognitive-core
+
+# Store a trajectory from a JSON file
+cognitive-core store ./trajectory.json
+
+# Search for relevant playbooks
+cognitive-core search "fix typescript import errors" --domain code
+# Found 2 playbook(s) matching "fix typescript import errors":
+#
+# Match: 92% (trigger)
+# ## typescript-import-resolution
+# Confidence: 85%
+# Strategy: Check tsconfig.json paths configuration
+# Tactics:
+#   - Verify moduleResolution setting
+#   - Check baseUrl and paths mapping
+#   - Inspect file extensions (.js vs .ts)
+
+# Get full playbook details
+cognitive-core get playbook-abc123
+
+# List domains with playbooks
+cognitive-core domains
+
+# View memory statistics
+cognitive-core stats
+# Experiences: 47
+# Playbooks: 12
+# Meta-observations: 31
 ```
 
-### Skill
+All commands support `--json` for structured output:
+
+```bash
+cognitive-core search "debug async errors" --json | jq '.results[0].strategy'
+```
+
+## Agent Backends
+
+cognitive-core delegates execution to backends that handle spawning, message passing, and trajectory extraction.
+
+### Subprocess backend
+
+Spawns agents as child processes. Works with any CLI agent.
+
 ```typescript
-interface Skill {
-  name: string;
-  description: string;     // Rich, for semantic matching
-  problem: string;
-  triggers: string[];      // Specific conditions
-  solution: string[];      // Step-by-step
-  verification?: string;
-}
+import { createAtlasWithAgents, createSubprocessBackend, claudeCodeConfig } from 'cognitive-core';
+
+const backend = createSubprocessBackend({
+  'claude-code': claudeCodeConfig,  // Pre-configured for Claude Code CLI
+});
+
+const atlas = createAtlasWithAgents([backend], {
+  execution: {
+    defaultAgentType: 'claude-code',
+    maxExecutionTime: 300,
+    captureToolCalls: true,
+  },
+});
 ```
 
-## Agent Backend System
+### ACP backend
 
-Atlas uses an agent backend system for real execution. Backends handle spawning, managing, and extracting trajectories from agents.
+Uses the [Agent Communication Protocol](https://www.npmjs.com/package/acp-factory) for richer interaction with ACP-compatible agents.
 
-### Creating Custom Backends
+```typescript
+import { createACPBackend, claudeCodeACPConfig } from 'cognitive-core';
+
+const backend = createACPBackend({
+  'claude-code': claudeCodeACPConfig,  // Uses npx claude-code-acp
+});
+```
+
+### Custom backends
 
 Implement the `AgentBackend` interface:
 
 ```typescript
 import type { AgentBackend, AgentSpawnConfig, AgentSession } from 'cognitive-core';
 
-class MyAgentBackend implements AgentBackend {
+class MyBackend implements AgentBackend {
   readonly name = 'my-agent';
-  readonly supportedTypes = ['my-agent', 'custom'];
+  readonly supportedTypes = ['my-agent'];
 
-  async isAvailable(): Promise<boolean> {
-    // Check if agent is available
-    return true;
-  }
+  async isAvailable(): Promise<boolean> { return true; }
 
   async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
-    // Spawn the agent with task and injected knowledge
-    const session = await launchMyAgent({
-      task: config.task,
-      systemPrompt: config.systemPromptAdditions,
-      timeout: config.timeout,
-    });
+    // config.task - the task to solve
+    // config.systemPromptAdditions - playbook context to inject
+    // config.timeout - max execution time
+    const session = await launchMyAgent(config);
     return session;
   }
 
-  async getSession(sessionId: string): Promise<AgentSession | undefined> {
-    // Get session status
-    return this.sessions.get(sessionId);
-  }
-
-  async terminate(sessionId: string): Promise<void> {
-    // Terminate a running session
-    await this.sessions.get(sessionId)?.kill();
-  }
+  async getSession(id: string): Promise<AgentSession | undefined> { /* ... */ }
+  async terminate(id: string): Promise<void> { /* ... */ }
 }
-
-// Register with Atlas
-const atlas = createAtlasWithAgents([new MyAgentBackend()]);
 ```
 
-### Using the AgentManager Directly
+### Observing agent execution
 
 ```typescript
 const manager = atlas.getAgentManager();
 
-// Add observers for monitoring
 manager.addObserver({
   onSessionStart: (session) => console.log('Started:', session.id),
   onToolCall: (session, toolCall) => console.log('Tool:', toolCall.name),
-  onSessionEnd: (session, trajectory) => console.log('Done:', trajectory.outcome.success),
-});
-
-// Compare with/without memory augmentation
-const comparison = await manager.compareWithKnowledge({
-  agentType: 'claude-code',
-  task: createTask({ domain: 'code', description: 'Fix the bug' }),
+  onSessionEnd: (session, trajectory) => {
+    console.log('Done:', trajectory.outcome.success);
+    console.log('Steps:', trajectory.steps.length);
+  },
 });
-
-console.log('Time saved:', comparison.improvement.timeDelta, 'ms');
-console.log('Fewer tool calls:', comparison.improvement.toolCallDelta);
 ```
 
-### Legacy: LLM Provider (Deprecated)
-
-> **Note**: The `setProvider()` API is deprecated. Use `createAtlasWithAgents()` instead.
+## Skill Library
 
-For simple testing without real agent execution:
-
-```typescript
-import type { LLMProvider, Message, CompletionOptions } from 'cognitive-core';
-
-class MyProvider implements LLMProvider {
-  readonly name = 'my-provider';
-
-  async complete(
-    messages: Message[],
-    options?: CompletionOptions
-  ): Promise<string> {
-    const response = await myLLMAPI.chat({
-      messages,
-      temperature: options?.temperature,
-      max_tokens: options?.maxTokens,
-    });
-    return response.content;
-  }
-}
-
-// Deprecated - prefer createAtlasWithAgents()
-atlas.setProvider(new MyProvider());
-```
+The skill library manages how playbooks are surfaced to agents across four tiers:
 
-## Processing External Trajectories
+| Tier | When loaded | Criteria |
+|------|-------------|----------|
+| **Core** | Always in system prompt | 85%+ confidence, 5+ successes, 80%+ success rate |
+| **Domain** | When task domain matches | Domain-tagged playbooks |
+| **Contextual** | When task query matches | Semantic/trigger match |
+| **On-demand** | Agent explicitly requests | Available via CLI |
 
-You can feed trajectories from other agents:
+Playbooks are automatically promoted and demoted based on usage outcomes. Three consecutive failures trigger demotion review.
 
 ```typescript
-import { createTrajectory, createTask, createStep, successOutcome } from 'cognitive-core';
-
-const trajectory = createTrajectory({
-  task: createTask({
-    domain: 'code',
-    description: 'Fix the authentication bug',
-  }),
-  steps: [
-    createStep({
-      thought: 'Need to check the token validation',
-      action: 'Read auth.ts',
-      observation: 'Found expired token check missing',
-    }),
-    createStep({
-      thought: 'Adding expiry validation',
-      action: 'Edit auth.ts to add token.exp check',
-      observation: 'Token validation added',
-    }),
-  ],
-  outcome: successOutcome('Fixed by adding token expiry check'),
-  agentId: 'external-agent',
-});
-
-// Process for learning
-const result = await atlas.processTrajectory(trajectory);
-console.log('Abstractable:', result.abstractable);
-console.log('Strategy extracted:', result.strategyExtracted);
+const skills = await atlas.getSkillLibrary()?.getSkillsForAgent(task);
+// skills.core       - always-on playbooks
+// skills.domain     - relevant to task domain
+// skills.contextual - matched to this specific task
 ```
 
 ## Configuration
 
 ```typescript
-const atlas = createAtlas({
+const atlas = createAtlasWithAgents([backend], {
+  storage: {
+    baseDir: '.cognitive-core',
+    persistenceEnabled: true,
+  },
   learning: {
-    creditStrategy: 'simple',      // 'simple' | 'llm' | 'counterfactual'
-    patternExtractor: 'llm',       // 'llm' | 'text' | 'both'
-    minTrajectories: 10,           // Before batch learning
-    deduplicationThreshold: 0.9,
+    creditStrategy: 'simple',        // 'simple' | 'contribution'
+    minTrajectories: 10,             // batch learning threshold
+    deduplicationThreshold: 0.9,     // prevent duplicate playbooks
   },
   router: {
-    similarityThreshold: 0.85,
+    similarityThreshold: 0.85,       // match confidence threshold
     useDomainRouting: true,
   },
   memory: {
-    maxExperiences: 4,             // ReMem paper default
-    maxStrategies: 3,
-    maxConcepts: 5,
-    maxSkills: 3,
+    maxExperiences: 4,               // k for experience retrieval
+    maxContextTokens: 4000,
+    capacity: {
+      maxExperiences: 1000,          // total stored experiences
+      maxPlaybooks: 200,
+      autoPrune: true,
+      preserveDomainCoverage: true,
+    },
   },
-  storage: {
-    baseDir: '.atlas',
-    persistenceEnabled: true,
+  knowledgeBank: {
+    enabled: true,                   // enable semantic memory (default: false)
+    memoryDir: 'memory',
+    extraction: {
+      enabled: true,                 // auto-extract from trajectories
+      useLlmExtraction: false,       // use heuristic extraction
+    },
+    graph: {
+      enabledLayers: ['semantic'],   // semantic | temporal | causal | entity
+    },
+    surfacing: {
+      maxNotesPerTask: 5,
+      maxTokensForKnowledge: 2000,
+    },
+    minimemAware: false,             // set true if using minimem
+  },
+  execution: {
+    defaultAgentType: 'claude-code',
+    maxExecutionTime: 300,
+    captureToolCalls: true,
+  },
+  refinement: {
+    useAgentEvaluation: true,
+    maxIterations: 3,
+    acceptableScore: 0.7,
   },
 });
 ```
 
-## References
+## Core Types
+
+### Playbook
+
+The central learning unit. Combines when to apply, what to do, and how to verify results.
+
+```typescript
+interface Playbook {
+  id: string;
+  name: string;
+  applicability: {
+    situations: string[];    // "debugging async code"
+    triggers: string[];      // "Promise rejection", "TS2307"
+    antiPatterns: string[];  // when NOT to use
+    domains: string[];       // "typescript", "react", "testing"
+  };
+  guidance: {
+    strategy: string;        // high-level approach
+    tactics: string[];       // mid-level steps
+    steps?: string[];        // concrete commands
+    codeExample?: string;
+  };
+  verification: {
+    successIndicators: string[];  // "Tests pass", "No errors"
+    failureIndicators: string[];  // "Same error persists"
+    rollbackStrategy?: string;
+  };
+  evolution: {
+    version: string;
+    successCount: number;
+    failureCount: number;
+    refinements: Refinement[];    // context-specific adaptations
+    failures: FailureRecord[];
+  };
+  confidence: number;             // 0-1, grows with successful use
+  complexity: 'simple' | 'moderate' | 'complex';
+}
+```
+
+### Trajectory
+
+A recorded problem-solving session in ReAct format.
+
+```typescript
+interface Trajectory {
+  id: string;
+  task: Task;
+  steps: Step[];              // thought -> action -> observation
+  outcome: Outcome;           // success/failure + solution
+  agentId: string;
+  llmCalls: number;
+  totalTokens: number;
+  wallTimeSeconds: number;
+}
+```
+
+### RoutingDecision
+
+How the system decides to approach a task.
+
+```typescript
+interface RoutingDecision {
+  strategy: 'direct' | 'adapt' | 'explore' | 'fallback';
+  confidence: number;
+  memoryContext: MemoryQueryResultV2;
+  estimatedBudget: number;
+  reasoning: string;
+}
+```
+
+## Research References
+
+cognitive-core draws from several lines of research on agent memory and learning:
 
-This implementation draws from several research papers:
+- **ArcMemo** - Concept-level memory outperforms instance-level at all compute scales
+- **ReMem** - Experience retrieval with k=4, iterative refinement loops
+- **Stitch** - Library learning through compression
+- **LILO** - AutoDoc for concept naming
+- **Voyager** - Ever-growing skill libraries with verification
+- **Claudeception** - Lightweight skill persistence for code agents
+- **[A-MEM](https://arxiv.org/abs/2502.12110)** - Zettelkasten-inspired structured notes with dynamic linking (knowledge note format)
+- **[MAGMA](https://arxiv.org/abs/2601.03236)** - Multi-graph decomposition into semantic, temporal, causal, entity layers (graph overlay design)
+- **[Zep](https://arxiv.org/pdf/2501.13956)** - Entity extraction, community detection, temporal tracking
+- **[Memory Survey](https://arxiv.org/abs/2512.13564)** - Comprehensive survey and taxonomy of factual/experiential/procedural memory
 
-- **ArcMemo**: Concept-level memory beats instance-level at all compute scales
-- **ReMem**: Experience retrieval with k=4, refinement loop
-- **Stitch**: Library learning via compression
-- **LILO**: AutoDoc for concept naming
-- **Voyager**: Ever-growing skill libraries
-- **Claudeception**: Lightweight skill persistence for Claude Code
+## Limitations
+
+- **No cross-domain transfer**. A playbook learned in the `code` domain won't surface for `testing` tasks even if the underlying pattern is the same. Domain tags are string-matched, not semantically compared.
+- **Cold start**. The system needs ~10 trajectories before batch learning kicks in and playbooks start appearing. Until then, agents run without memory augmentation. Knowledge extraction works per-trajectory, so knowledge is available sooner.
+- **Text-based matching by default**. BM25 works but misses semantic similarity. Vector search requires configuring an embedding provider and adds latency. Knowledge bank search uses text similarity unless minimem is available.
+- **No trajectory quality filtering**. The system stores all trajectories, including ones from poorly-performing agents. Low-quality trajectories can produce low-quality playbooks and knowledge. The deduplication threshold and confidence model help, but don't solve the garbage-in problem.
+- **Single-machine storage**. Persistence is JSON file-based (experiences, playbooks), Markdown file-based (knowledge), and SQLite (vector store). There's no built-in replication, multi-agent concurrency, or cloud storage.
+- **Extraction is heuristic by default**. Without an LLM extractor configured, both playbook and knowledge extraction use text pattern matching, which produces lower-quality results. LLM-assisted extraction is available via workspace templates.
+- **Knowledge extraction is not auto-wired into the learning pipeline**. Knowledge must be extracted explicitly via `KnowledgeBank.extractFromTrajectory()`. This is by design — it allows callers to control when extraction runs.
+
+## Contributing
+
+Contributions welcome. The test suite uses Vitest:
+
+```bash
+npm install
+npm run test:run    # run tests once
+npm run test        # watch mode
+npm run typecheck   # type checking without emit
+```
 
 ## License