cognitive-core 0.0.2 → 0.1.2

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

package/dist/agents/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent types and protocols for Atlas
+ */
+/**
+ * Message in a conversation
+ */
+export interface Message {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * LLM completion options
+ */
+export interface CompletionOptions {
+    temperature?: number;
+    maxTokens?: number;
+    stopSequences?: string[];
+}
+/**
+ * LLM provider interface
+ * Implement this to use different LLM backends
+ */
+export interface LLMProvider {
+    /**
+     * Generate a completion
+     */
+    complete(messages: Message[], options?: CompletionOptions): Promise<string>;
+    /**
+     * Get the provider name
+     */
+    readonly name: string;
+}
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+    /** Name of this agent */
+    name: string;
+    /** System prompt */
+    systemPrompt: string;
+    /** LLM provider to use */
+    provider: LLMProvider;
+    /** Default completion options */
+    defaultOptions?: CompletionOptions;
+}
+/**
+ * Base agent class
+ */
+export declare abstract class Agent {
+    protected config: AgentConfig;
+    protected conversationHistory: Message[];
+    constructor(config: AgentConfig);
+    /**
+     * Reset the agent state
+     */
+    reset(): void;
+    /**
+     * Send a message and get a response
+     */
+    chat(content: string, options?: CompletionOptions): Promise<string>;
+    /**
+     * Get conversation history
+     */
+    getHistory(): Message[];
+    /**
+     * Get agent name
+     */
+    get name(): string;
+}
+/**
+ * Tool definition for function calling
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Tool call result
+ */
+export interface ToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Agent with tool use capabilities
+ */
+export interface ToolAgent extends Agent {
+    /**
+     * Available tools
+     */
+    readonly tools: ToolDefinition[];
+    /**
+     * Execute a tool
+     */
+    executeTool(call: ToolCall): Promise<unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,QAAQ,CACN,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,QAAQ,EAAE,WAAW,CAAC;IACtB,iCAAiC;IACjC,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;GAEG;AACH,8BAAsB,KAAK;IACzB,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC;IAC9B,SAAS,CAAC,mBAAmB,EAAE,OAAO,EAAE,CAAM;gBAElC,MAAM,EAAE,WAAW;IAK/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAazE;;OAEG;IACH,UAAU,IAAI,OAAO,EAAE;IAIvB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IAEjC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/C"}

package/dist/agents/types.js

@@ -0,0 +1,44 @@
+/**
+ * Agent types and protocols for Atlas
+ */
+/**
+ * Base agent class
+ */
+export class Agent {
+    config;
+    conversationHistory = [];
+    constructor(config) {
+        this.config = config;
+        this.reset();
+    }
+    /**
+     * Reset the agent state
+     */
+    reset() {
+        this.conversationHistory = [
+            { role: 'system', content: this.config.systemPrompt },
+        ];
+    }
+    /**
+     * Send a message and get a response
+     */
+    async chat(content, options) {
+        this.conversationHistory.push({ role: 'user', content });
+        const response = await this.config.provider.complete(this.conversationHistory, { ...this.config.defaultOptions, ...options });
+        this.conversationHistory.push({ role: 'assistant', content: response });
+        return response;
+    }
+    /**
+     * Get conversation history
+     */
+    getHistory() {
+        return [...this.conversationHistory];
+    }
+    /**
+     * Get agent name
+     */
+    get name() {
+        return this.config.name;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoDH;;GAEG;AACH,MAAM,OAAgB,KAAK;IACf,MAAM,CAAc;IACpB,mBAAmB,GAAc,EAAE,CAAC;IAE9C,YAAY,MAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,mBAAmB,GAAG;YACzB,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;SACtD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,OAA2B;QACrD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAEzD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAClD,IAAI,CAAC,mBAAmB,EACxB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,OAAO,EAAE,CAC9C,CAAC;QAEF,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAExE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF"}