cognitive-core 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,364 @@
-# cognitive-core
+# Atlas
 
-> Coming soon
+**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
+
+```bash
+npm install cognitive-core
+```
+
+## Quick Start
+
+### Using with Agent Backends (Recommended)
+
+```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' } }
+);
+
+// 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',
+});
+
+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);
+
+// 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();
+```
+
+### Setting Up Real Agent Backends
+
+```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'],
+});
+
+// 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,
+  },
+});
+
+await atlas.init();
+
+// Solve with memory-augmented context
+const result = await atlas.solve(createTask({
+  domain: 'code',
+  description: 'Fix the TypeScript compilation error in auth.ts',
+}));
+```
+
+## Architecture
+
+```
+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
+```
+
+## Core Types
+
+### Task
+```typescript
+interface Task {
+  id: string;
+  domain: string;          // e.g., 'code', 'reasoning', 'arc'
+  description: string;
+  context: Record<string, unknown>;
+  verification?: VerificationSpec;
+}
+```
+
+### Trajectory
+```typescript
+interface Trajectory {
+  id: string;
+  task: Task;
+  steps: Step[];           // ReAct-style steps
+  outcome: Outcome;
+  agentId: string;
+  llmCalls: number;
+  totalTokens: number;
+  wallTimeSeconds: number;
+}
+```
+
+### Strategy
+```typescript
+interface Strategy {
+  situation: string;       // When to apply
+  suggestion: string;      // What to do
+  parameters: Parameter[];
+  confidence: number;
+  successRate: number;
+}
+```
+
+### 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;
+}
+```
+
+## Agent Backend System
+
+Atlas uses an agent backend system for real execution. Backends handle spawning, managing, and extracting trajectories from agents.
+
+### Creating Custom Backends
+
+Implement the `AgentBackend` interface:
+
+```typescript
+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()]);
+```
+
+### Using the AgentManager Directly
+
+```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' }),
+});
+
+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.
+
+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());
+```
+
+## Processing External Trajectories
+
+You can feed trajectories from other agents:
+
+```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);
+```
+
+## Configuration
+
+```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,
+  },
+});
+```
+
+## References
+
+This implementation draws from several research papers:
+
+- **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
+
+MIT

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"}

package/dist/agents/mock-provider.d.ts

@@ -0,0 +1,23 @@
+import type { LLMProvider, Message, CompletionOptions } from './types.js';
+/**
+ * Mock LLM provider for testing
+ * Returns predefined responses based on input patterns
+ */
+export declare class MockLLMProvider implements LLMProvider {
+    readonly name = "mock";
+    private responses;
+    constructor();
+    /**
+     * Add a custom response pattern
+     */
+    addResponse(pattern: RegExp, response: string): void;
+    /**
+     * Generate a completion (mock)
+     */
+    complete(messages: Message[], _options?: CompletionOptions): Promise<string>;
+}
+/**
+ * Create a mock provider for testing
+ */
+export declare function createMockProvider(): MockLLMProvider;
+//# sourceMappingURL=mock-provider.d.ts.map

package/dist/agents/mock-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-provider.d.ts","sourceRoot":"","sources":["../../src/agents/mock-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;GAGG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,QAAQ,CAAC,IAAI,UAAU;IAEvB,OAAO,CAAC,SAAS,CAAkC;;IA8CnD;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpD;;OAEG;IACG,QAAQ,CACZ,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,MAAM,CAAC;CAiBnB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD"}

package/dist/agents/mock-provider.js

@@ -0,0 +1,71 @@
+/**
+ * Mock LLM provider for testing
+ * Returns predefined responses based on input patterns
+ */
+export class MockLLMProvider {
+    name = 'mock';
+    responses = new Map();
+    constructor() {
+        // Default mock responses
+        this.addResponse(/extract.*strateg/i, `STRATEGY:
+- Situation: When facing a debugging task with unclear error messages
+- Suggestion: Start by reproducing the issue, then use binary search to isolate the problem
+- Parameters: error_message, codebase_size
+- Confidence: 0.7`);
+        this.addResponse(/extract.*concept/i, `CONCEPT:
+- Name: error-handler
+- Description: Generic error handling wrapper function
+- Code: \`\`\`typescript
+function handleError<T>(fn: () => T): T | null {
+  try {
+    return fn();
+  } catch (e) {
+    console.error(e);
+    return null;
+  }
+}
+\`\`\`
+- Signature: (() => T) -> T | null`);
+        this.addResponse(/extract.*skill|codify.*skill/i, `SKILL:
+- Name: fix-typescript-import-error
+- Problem: Resolve TypeScript module import errors
+- Triggers: Cannot find module, Module not found, TS2307
+- Steps:
+  1. Check if the module is installed in package.json
+  2. Verify the import path is correct
+  3. Check tsconfig.json module resolution settings
+  4. Run npm install or yarn if module is missing
+- Verification: Run tsc --noEmit to verify no import errors`);
+    }
+    /**
+     * Add a custom response pattern
+     */
+    addResponse(pattern, response) {
+        this.responses.set(pattern, response);
+    }
+    /**
+     * Generate a completion (mock)
+     */
+    async complete(messages, _options) {
+        // Get the last user message
+        const lastMessage = messages.filter((m) => m.role === 'user').pop();
+        if (!lastMessage) {
+            return 'No user message found.';
+        }
+        // Check patterns
+        for (const [pattern, response] of this.responses) {
+            if (pattern.test(lastMessage.content)) {
+                return response;
+            }
+        }
+        // Default response
+        return 'No matching pattern found for this request.';
+    }
+}
+/**
+ * Create a mock provider for testing
+ */
+export function createMockProvider() {
+    return new MockLLMProvider();
+}
+//# sourceMappingURL=mock-provider.js.map

package/dist/agents/mock-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-provider.js","sourceRoot":"","sources":["../../src/agents/mock-provider.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,MAAM,CAAC;IAEf,SAAS,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEnD;QACE,yBAAyB;QACzB,IAAI,CAAC,WAAW,CACd,mBAAmB,EACnB;;;;kBAIY,CACb,CAAC;QAEF,IAAI,CAAC,WAAW,CACd,mBAAmB,EACnB;;;;;;;;;;;;;mCAa6B,CAC9B,CAAC;QAEF,IAAI,CAAC,WAAW,CACd,+BAA+B,EAC/B;;;;;;;;;4DASsD,CACvD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAAe,EAAE,QAAgB;QAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CACZ,QAAmB,EACnB,QAA4B;QAE5B,4BAA4B;QAC5B,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC;QACpE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,wBAAwB,CAAC;QAClC,CAAC;QAED,iBAAiB;QACjB,KAAK,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACjD,IAAI,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtC,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,OAAO,6CAA6C,CAAC;IACvD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,eAAe,EAAE,CAAC;AAC/B,CAAC"}