cognitive-core 0.0.2 → 0.1.0

package/README.md

@@ -1,6 +1,29 @@
-# cognitive-core
+# Atlas
 
-TypeScript client for [Cognitive Core](https://github.com/alexngai/meta-learning-engine) - A meta-learning framework for learning from agent trajectories.
+**Adaptive Trajectory Learning and Abstraction System**
+
+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.
+
+## Features
+
+- **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
+
+- **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)
+
+- **Task Router**: Smart routing based on memory similarity
+- **Lightweight Persistence**: JSON file-based storage
 
 ## Installation
 
@@ -8,170 +31,333 @@ TypeScript client for [Cognitive Core](https://github.com/alexngai/meta-learning
 npm install cognitive-core
 ```
 
-**Prerequisites:** Python 3.10+
-
-## Setup
+## Quick Start
 
-The package can automatically set up a Python virtual environment and install dependencies:
+### Using with Agent Backends (Recommended)
 
 ```typescript
-import { setup, CognitiveCore } from "cognitive-core";
+import { createAtlasWithAgents, createTask, createMockBackend } from 'cognitive-core';
+
+// Create Atlas with agent backends
+const atlas = createAtlasWithAgents(
+  [createMockBackend()],  // Use mock backend for testing
+  { storage: { baseDir: '.atlas' } }
+);
+
+// Initialize (loads persisted data)
+await atlas.init();
+
+// Create and solve a task
+const task = createTask({
+  domain: 'code',
+  description: 'Write a function that checks if a number is prime',
+});
 
-// One-time setup (creates .cognitive-core/ venv)
-const { pythonPath, version } = await setup();
-console.log(`Installed cognitive-core ${version}`);
+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);
 
-// CognitiveCore automatically uses the venv
-const core = new CognitiveCore();
-await core.start();
+// Get stats
+const stats = await atlas.getStats();
+console.log('Memory stats:', stats.memory);
+console.log('Backends:', stats.execution?.backends);
+
+// Close (persists data)
+await atlas.close();
 ```
 
-### Setup Options
+### Setting Up Real Agent Backends
 
 ```typescript
-await setup({
-  // Custom venv location (default: ".cognitive-core")
-  venvDir: "./my-venv",
+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'],
+});
 
-  // Install optional features
-  extras: ["arc", "embeddings", "llm"],
+// 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,
+  },
+});
 
-  // Specific version
-  version: "0.1.0",
+await atlas.init();
 
-  // Quiet mode
-  verbose: false,
-});
+// Solve with memory-augmented context
+const result = await atlas.solve(createTask({
+  domain: 'code',
+  description: 'Fix the TypeScript compilation error in auth.ts',
+}));
 ```
 
-### Manual Installation
+## Architecture
 
-If you prefer to manage Python yourself:
-
-```bash
-pip install cognitive-core
+```
+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
 ```
 
-Then use the system Python:
+## Core Types
 
+### Task
 ```typescript
-const core = new CognitiveCore({ pythonPath: "python3" });
+interface Task {
+  id: string;
+  domain: string;          // e.g., 'code', 'reasoning', 'arc'
+  description: string;
+  context: Record<string, unknown>;
+  verification?: VerificationSpec;
+}
 ```
 
-## Quick Start
-
+### Trajectory
 ```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]]],
-      ],
-    },
-  },
-});
+interface Trajectory {
+  id: string;
+  task: Task;
+  steps: Step[];           // ReAct-style steps
+  outcome: Outcome;
+  agentId: string;
+  llmCalls: number;
+  totalTokens: number;
+  wallTimeSeconds: number;
+}
+```
 
-// Verify a solution
-const outcome = await core.env.verify(env.envId, [[1, 1], [0, 0]]);
-console.log(`Success: ${outcome.success}, Score: ${outcome.partialScore}`);
+### Strategy
+```typescript
+interface Strategy {
+  situation: string;       // When to apply
+  suggestion: string;      // What to do
+  parameters: Parameter[];
+  confidence: number;
+  successRate: number;
+}
+```
 
-// Stop the subprocess
-await core.stop();
+### Skill
+```typescript
+interface Skill {
+  name: string;
+  description: string;     // Rich, for semantic matching
+  problem: string;
+  triggers: string[];      // Specific conditions
+  solution: string[];      // Step-by-step
+  verification?: string;
+}
 ```
 
-## API
+## Agent Backend System
+
+Atlas uses an agent backend system for real execution. Backends handle spawning, managing, and extracting trajectories from agents.
 
-### CognitiveCore
+### Creating Custom Backends
 
-Main client class.
+Implement the `AgentBackend` interface:
 
 ```typescript
-const core = new CognitiveCore(options?: CognitiveCoreOptions);
+import type { AgentBackend, AgentSpawnConfig, AgentSession } from 'cognitive-core';
+
+class MyAgentBackend implements AgentBackend {
+  readonly name = 'my-agent';
+  readonly supportedTypes = ['my-agent', 'custom'];
+
+  async isAvailable(): Promise<boolean> {
+    // Check if agent is available
+    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,
+    });
+    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();
+  }
+}
+
+// Register with Atlas
+const atlas = createAtlasWithAgents([new MyAgentBackend()]);
 ```
 
-**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`)
+### Using the AgentManager Directly
 
-**Methods:**
-- `start()`: Start the Python subprocess
-- `stop()`: Stop the Python subprocess
-- `version()`: Get Python package version
-- `isRunning`: Check if client is running
+```typescript
+const manager = atlas.getAgentManager();
 
-### Environment API (`core.env`)
+// 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),
+});
 
-- `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
+// Compare with/without memory augmentation
+const comparison = await manager.compareWithKnowledge({
+  agentType: 'claude-code',
+  task: createTask({ domain: 'code', description: 'Fix the bug' }),
+});
 
-### Memory API (`core.memory`)
+console.log('Time saved:', comparison.improvement.timeDelta, 'ms');
+console.log('Fewer tool calls:', comparison.improvement.toolCallDelta);
+```
 
-- `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
+### Legacy: LLM Provider (Deprecated)
 
-### Search API (`core.search`)
+> **Note**: The `setProvider()` API is deprecated. Use `createAtlasWithAgents()` instead.
 
-- `solve(task)`: Solve a task using configured search strategy
+For simple testing without real agent execution:
 
-## Low-Level Client
+```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());
+```
 
-For advanced usage, access the raw subprocess client:
+## Processing External Trajectories
+
+You can feed trajectories from other agents:
 
 ```typescript
-import { CognitiveCoreClient } from "cognitive-core";
+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',
+});
 
-const client = new CognitiveCoreClient();
-await client.start();
+// Process for learning
+const result = await atlas.processTrajectory(trajectory);
+console.log('Abstractable:', result.abstractable);
+console.log('Strategy extracted:', result.strategyExtracted);
+```
 
-// Execute arbitrary commands
-const result = await client.execute("custom.command", { arg: "value" });
+## Configuration
 
-await client.stop();
+```typescript
+const atlas = createAtlas({
+  learning: {
+    creditStrategy: 'simple',      // 'simple' | 'llm' | 'counterfactual'
+    patternExtractor: 'llm',       // 'llm' | 'text' | 'both'
+    minTrajectories: 10,           // Before batch learning
+    deduplicationThreshold: 0.9,
+  },
+  router: {
+    similarityThreshold: 0.85,
+    useDomainRouting: true,
+  },
+  memory: {
+    maxExperiences: 4,             // ReMem paper default
+    maxStrategies: 3,
+    maxConcepts: 5,
+    maxSkills: 3,
+  },
+  storage: {
+    baseDir: '.atlas',
+    persistenceEnabled: true,
+  },
+});
 ```
 
-## Types
+## References
 
-Full TypeScript types are included for all data structures:
+This implementation draws from several research papers:
 
-```typescript
-import type {
-  Task,
-  Trajectory,
-  Outcome,
-  Experience,
-  Strategy,
-  CodeConcept,
-  Grid,
-  ARCTask,
-} from "cognitive-core";
-```
+- **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
 
 ## License
 

package/SKILL.md

@@ -0,0 +1,193 @@
+# Cognitive Core Skill
+
+Use this skill when the user asks you to leverage learned strategies, playbooks, or experience-based knowledge to solve problems more effectively.
+
+## Overview
+
+Cognitive Core (Atlas) is a learning system that helps agents solve problems by:
+- Storing successful problem-solving trajectories
+- Extracting reusable playbooks from those trajectories
+- Providing relevant strategies and tactics for new problems
+
+## When to Use This Skill
+
+Activate this skill when:
+- You need guidance on how to approach a complex problem
+- You want to check if there are established strategies for a task domain
+- You've successfully solved a problem and want to record the approach
+- The user explicitly asks about learned strategies or playbooks
+
+## CLI Commands
+
+The cognitive-core CLI provides access to the learning system:
+
+### Search for Relevant Playbooks
+
+```bash
+cognitive-core search "<your problem description>"
+cognitive-core search "fix typescript errors" --domain code
+cognitive-core search "write unit tests" --limit 3
+cognitive-core search "refactor function" --json
+```
+
+Use search when you need guidance. The system returns:
+- Strategy: High-level approach to the problem
+- Tactics: Specific techniques to apply
+- Success indicators: How to know if you succeeded
+- Confidence: How reliable this playbook is
+
+### Get Playbook Details
+
+```bash
+cognitive-core get <playbook-id>
+cognitive-core get playbook-abc123 --json
+```
+
+Use this to get full details including steps, when-to-use conditions, and failure patterns to avoid.
+
+### List Available Domains
+
+```bash
+cognitive-core domains
+cognitive-core domains --json
+```
+
+Shows all problem domains that have playbooks available.
+
+### Check System Stats
+
+```bash
+cognitive-core stats
+cognitive-core stats --json
+```
+
+Shows how many experiences and playbooks are stored.
+
+### Store a Trajectory
+
+```bash
+cognitive-core store ./trajectory.json
+```
+
+Store a problem-solving trajectory to help the system learn.
+
+## Trajectory Format
+
+When storing trajectories, use this JSON format:
+
+```json
+{
+  "id": "unique-trajectory-id",
+  "task": {
+    "domain": "code",
+    "description": "Fix the null pointer exception in user service",
+    "context": {
+      "file": "src/services/user.ts",
+      "error": "TypeError: Cannot read property 'id' of null"
+    }
+  },
+  "steps": [
+    {
+      "thought": "First, I need to understand where the null value is coming from",
+      "action": "read src/services/user.ts",
+      "observation": "Found the function getUserById which doesn't handle missing users"
+    },
+    {
+      "thought": "The function should check if user exists before accessing properties",
+      "action": "edit src/services/user.ts to add null check",
+      "observation": "Added guard clause: if (!user) return null"
+    }
+  ],
+  "outcome": {
+    "success": true,
+    "solution": "Added null check in getUserById function"
+  },
+  "agentId": "your-agent-id"
+}
+```
+
+## Workflow Integration
+
+### Before Starting a Task
+
+1. Search for relevant playbooks:
+   ```bash
+   cognitive-core search "description of your task"
+   ```
+
+2. If playbooks are found, review the strategy and tactics
+
+3. Apply the suggested approach, adapting as needed
+
+### After Completing a Task
+
+1. If the solution was novel or particularly effective, store it:
+   - Create a trajectory JSON file documenting your steps
+   - Store it: `cognitive-core store ./my-trajectory.json`
+
+2. This helps the system learn from your experience
+
+## Best Practices
+
+1. **Search First**: Before tackling complex problems, check if there are existing strategies
+
+2. **Be Specific**: More specific queries get better matches
+   - Good: "fix TypeScript null reference error in async function"
+   - Less Good: "fix error"
+
+3. **Use Domains**: Filter by domain for more relevant results
+   - `--domain code` for programming tasks
+   - `--domain testing` for test-related tasks
+   - `--domain refactoring` for code restructuring
+
+4. **Record Success**: Store trajectories for:
+   - Problems that were particularly tricky
+   - Novel solutions you discovered
+   - Patterns you want to remember
+
+5. **Include Context**: When storing trajectories, include:
+   - Your reasoning (thoughts)
+   - The specific actions taken
+   - What you observed at each step
+
+## Example Session
+
+```bash
+# User asks: "Help me fix this failing test"
+
+# 1. Search for relevant strategies
+cognitive-core search "fix failing test" --domain testing
+
+# Output shows:
+# ## Debug Test Failures
+# Strategy: Systematically isolate and identify the cause of test failures
+# Tactics:
+#   - Read the full error message and stack trace
+#   - Check if the test worked before recent changes
+#   - Isolate the failing assertion
+#   - Verify test data and mocks are correct
+
+# 2. Apply the strategy while working on the problem
+# ... work through the tactics ...
+
+# 3. If you found a novel approach, store it
+cognitive-core store ./test-fix-trajectory.json
+```
+
+## Configuration
+
+The CLI uses `.cognitive-core` directory in the current working directory by default. Override with:
+
+```bash
+cognitive-core search "query" --dir /path/to/memory
+```
+
+## JSON Output
+
+For programmatic access, use `--json` or `--format json`:
+
+```bash
+cognitive-core search "typescript error" --json | jq '.results[0].strategy'
+```
+
+This returns structured data suitable for parsing.

package/dist/agents/index.d.ts

@@ -0,0 +1,3 @@
+export { Agent, type LLMProvider, type Message, type CompletionOptions, type AgentConfig, type ToolDefinition, type ToolCall, type ToolAgent, } from './types.js';
+export { MockLLMProvider, createMockProvider } from './mock-provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,5 @@
+// Types and base classes
+export { Agent, } from './types.js';
+// Mock provider for testing
+export { MockLLMProvider, createMockProvider } from './mock-provider.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,OAAO,EACL,KAAK,GAQN,MAAM,YAAY,CAAC;AAEpB,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}