cognitive-core 0.0.2 → 0.1.2

package/README.md

@@ -1,6 +1,36 @@
 # cognitive-core
 
-TypeScript client for [Cognitive Core](https://github.com/alexngai/meta-learning-engine) - A meta-learning framework for learning from agent trajectories.
+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.
+
+## Table of Contents
+
+- [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)
+
+## Motivation
+
+
+cognitive-core gives agents persistent, structured memory:
+
+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
 
@@ -8,169 +38,595 @@ TypeScript client for [Cognitive Core](https://github.com/alexngai/meta-learning
 npm install cognitive-core
 ```
 
-**Prerequisites:** Python 3.10+
+Requires Node.js 18+.
 
-## Setup
+## Quick Start
 
-The package can automatically set up a Python virtual environment and install dependencies:
+### Solve a task with memory-augmented agents
 
 ```typescript
-import { setup, CognitiveCore } from "cognitive-core";
+import { createAtlasWithAgents, createTask, createMockBackend } from 'cognitive-core';
 
-// One-time setup (creates .cognitive-core/ venv)
-const { pythonPath, version } = await setup();
-console.log(`Installed cognitive-core ${version}`);
+const atlas = createAtlasWithAgents(
+  [createMockBackend()],
+  { storage: { baseDir: '.cognitive-core' } }
+);
 
-// CognitiveCore automatically uses the venv
-const core = new CognitiveCore();
-await core.start();
+await atlas.init();
+
+const result = await atlas.solve(createTask({
+  domain: 'code',
+  description: 'Fix the TypeScript compilation error in auth.ts',
+}));
+
+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
+
+await atlas.close();
 ```
 
-### Setup Options
+### Feed trajectories from external agents
+
+cognitive-core can learn from trajectories produced by external agents. Record what happened elsewhere and feed it in.
 
 ```typescript
-await setup({
-  // Custom venv location (default: ".cognitive-core")
-  venvDir: "./my-venv",
+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',
+});
+
+const result = await atlas.processTrajectory(trajectory);
+console.log(result.abstractable);  // true - system can extract a playbook from this
 
-  // Install optional features
-  extras: ["arc", "embeddings", "llm"],
+await atlas.close();
+```
 
-  // Specific version
-  version: "0.1.0",
+### Query memory directly
 
-  // Quiet mode
-  verbose: false,
+```typescript
+const context = await atlas.queryMemory('typescript import resolution error', {
+  domains: ['code'],
+  includePlaybooks: true,
 });
+
+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(', ')}`);
+}
 ```
 
-### Manual Installation
+## How It Works
 
-If you prefer to manage Python yourself:
+### Solve flow
 
-```bash
-pip install cognitive-core
+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
+```
+
+### 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
 ```
 
-Then use the system Python:
+### 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
+```
+
+| 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 |
+
+### 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)
+```
+
+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
+```
+
+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
-const core = new CognitiveCore({ pythonPath: "python3" });
+const result = await atlas.solve(task);
+console.log(result.surfacedKnowledge?.length);  // knowledge notes injected
 ```
 
-## Quick Start
+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
+```
+
+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
-import { CognitiveCore } from "cognitive-core";
-
-const core = new CognitiveCore();
-
-// Start the Python subprocess
-await core.start();
-
-// Get version
-const version = await core.version();
-console.log(`Running cognitive-core v${version}`);
-
-// Create an environment
-const env = await core.env.create("arc");
-
-// Reset with a task
-const { observation } = await core.env.reset(env.envId, {
-  id: "task-1",
-  domain: "arc",
-  description: "Transform the input grid",
-  context: {
-    grids: {
-      train: [
-        [[[0, 1], [1, 0]], [[1, 0], [0, 1]]],
-      ],
-      test: [
-        [[[0, 0], [1, 1]], [[1, 1], [0, 0]]],
-      ],
-    },
+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,
   },
 });
+```
 
-// Verify a solution
-const outcome = await core.env.verify(env.envId, [[1, 1], [0, 0]]);
-console.log(`Success: ${outcome.success}, Score: ${outcome.partialScore}`);
+### ACP backend
 
-// Stop the subprocess
-await core.stop();
+Uses the [Agent Communication Protocol](https://www.npmjs.com/package/acp-factory) for richer interaction with ACP-compatible agents.
+
+```typescript
+import { createACPBackend, claudeCodeACPConfig } from 'cognitive-core';
+
+const backend = createACPBackend({
+  'claude-code': claudeCodeACPConfig,  // Uses npx claude-code-acp
+});
 ```
 
-## API
+### Custom backends
 
-### CognitiveCore
+Implement the `AgentBackend` interface:
+
+```typescript
+import type { AgentBackend, AgentSpawnConfig, AgentSession } from 'cognitive-core';
+
+class MyBackend implements AgentBackend {
+  readonly name = 'my-agent';
+  readonly supportedTypes = ['my-agent'];
+
+  async isAvailable(): Promise<boolean> { return true; }
+
+  async spawn(config: AgentSpawnConfig): Promise<AgentSession> {
+    // 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(id: string): Promise<AgentSession | undefined> { /* ... */ }
+  async terminate(id: string): Promise<void> { /* ... */ }
+}
+```
 
-Main client class.
+### Observing agent execution
 
 ```typescript
-const core = new CognitiveCore(options?: CognitiveCoreOptions);
+const manager = atlas.getAgentManager();
+
+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);
+    console.log('Steps:', trajectory.steps.length);
+  },
+});
 ```
 
-**Options:**
-- `pythonPath`: Path to Python executable (default: `"python"`)
-- `cwd`: Working directory for Python process
-- `env`: Environment variables for Python process
-- `timeout`: Command timeout in milliseconds (default: `30000`)
+## Skill Library
 
-**Methods:**
-- `start()`: Start the Python subprocess
-- `stop()`: Stop the Python subprocess
-- `version()`: Get Python package version
-- `isRunning`: Check if client is running
+The skill library manages how playbooks are surfaced to agents across four tiers:
 
-### Environment API (`core.env`)
+| 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 |
 
-- `create(domain)`: Create a new environment
-- `reset(envId, task)`: Reset environment with a task
-- `step(envId, action)`: Execute an action
-- `verify(envId, solution)`: Verify a solution
+Playbooks are automatically promoted and demoted based on usage outcomes. Three consecutive failures trigger demotion review.
 
-### Memory API (`core.memory`)
+```typescript
+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
+```
 
-- `searchExperiences(query, k)`: Search for similar experiences
-- `searchStrategies(query, k)`: Search for relevant strategies
-- `searchConcepts(query, k)`: Search for code concepts
-- `store(trajectory)`: Store a trajectory
+## Configuration
 
-### Search API (`core.search`)
+```typescript
+const atlas = createAtlasWithAgents([backend], {
+  storage: {
+    baseDir: '.cognitive-core',
+    persistenceEnabled: true,
+  },
+  learning: {
+    creditStrategy: 'simple',        // 'simple' | 'contribution'
+    minTrajectories: 10,             // batch learning threshold
+    deduplicationThreshold: 0.9,     // prevent duplicate playbooks
+  },
+  router: {
+    similarityThreshold: 0.85,       // match confidence threshold
+    useDomainRouting: true,
+  },
+  memory: {
+    maxExperiences: 4,               // k for experience retrieval
+    maxContextTokens: 4000,
+    capacity: {
+      maxExperiences: 1000,          // total stored experiences
+      maxPlaybooks: 200,
+      autoPrune: true,
+      preserveDomainCoverage: 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,
+  },
+});
+```
 
-- `solve(task)`: Solve a task using configured search strategy
+## Core Types
 
-## Low-Level Client
+### Playbook
 
-For advanced usage, access the raw subprocess client:
+The central learning unit. Combines when to apply, what to do, and how to verify results.
 
 ```typescript
-import { CognitiveCoreClient } from "cognitive-core";
+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';
+}
+```
 
-const client = new CognitiveCoreClient();
-await client.start();
+### Trajectory
 
-// Execute arbitrary commands
-const result = await client.execute("custom.command", { arg: "value" });
+A recorded problem-solving session in ReAct format.
 
-await client.stop();
+```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;
+}
 ```
 
-## Types
+### RoutingDecision
 
-Full TypeScript types are included for all data structures:
+How the system decides to approach a task.
 
 ```typescript
-import type {
-  Task,
-  Trajectory,
-  Outcome,
-  Experience,
-  Strategy,
-  CodeConcept,
-  Grid,
-  ARCTask,
-} from "cognitive-core";
+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:
+
+- **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
+
+## 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