cognitive-core 0.1.0 → 0.2.0

package/.claude/settings.json

@@ -0,0 +1,88 @@
+{
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code post-task"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code post-todo"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code pre-task"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code session-end"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code session-start"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code stop"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code user-prompt-submit"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "deny": [
+      "Read(./.entire/metadata/**)"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run test:run:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/.entire/settings.json

@@ -0,0 +1,4 @@
+{
+  "strategy": "manual-commit",
+  "enabled": true
+}

package/CLAUDE.md

@@ -0,0 +1,233 @@
+# CLAUDE.md
+
+Project conventions and architecture for Claude Code working on cognitive-core.
+
+## Build & Test
+
+```bash
+npm run build          # tsc — compile TypeScript
+npm run test:run       # vitest run — run tests once
+npm test               # vitest — watch mode
+npm run typecheck      # tsc --noEmit — type checking without emit
+npm run lint           # eslint src --ext .ts
+```
+
+Tests use Vitest. All test files are in `tests/` mirroring the `src/` structure.
+
+Pre-existing build warnings exist for `skill-tree` module resolution (3 files in `src/surfacing/`) and some unused variables — these are known issues.
+
+## Project Structure
+
+```
+src/
+├── index.ts                    # Root exports (17 subsystems)
+├── atlas.ts                    # Main orchestrator (Atlas class)
+├── factory.ts                  # Factory interface for external integration
+│
+├── types/                      # Shared type definitions + Zod schemas
+│   ├── task.ts, step.ts, outcome.ts, trajectory.ts, playbook.ts
+│   ├── knowledge.ts, knowledge-graph.ts, memory.ts, meta.ts, config.ts
+│   └── team-trajectory.ts, team-playbook.ts, team-meta.ts
+│
+├── memory/                     # Memory stores
+│   ├── system.ts               # MemorySystem aggregator
+│   ├── experience.ts           # ExperienceMemory (domain-partitioned, InvertedIndex)
+│   ├── playbook.ts             # PlaybookLibrary (domain-partitioned, InvertedIndex)
+│   ├── knowledge-bank.ts       # KnowledgeBank (Markdown + YAML frontmatter)
+│   ├── knowledge-graph.ts      # Multi-layer graph overlay
+│   ├── knowledge-defrag.ts     # Knowledge note deduplication
+│   ├── meta.ts                 # MetaMemory (routing/retrieval observations)
+│   ├── reflexion.ts            # ReflexionMemory (self-reflection episodes)
+│   ├── reasoning-bank.ts       # ReasoningBank (K-means++ clustering)
+│   ├── causal-store.ts         # CausalStore (cause→effect edges)
+│   ├── coherence.ts            # CoherenceChecker (contradiction detection)
+│   ├── temporal-compressor.ts  # TemporalCompressor (Hot/Warm/Cold/Evicted tiers)
+│   ├── candidate-retrieval.ts  # Shared InvertedIndex → fallback retrieval
+│   ├── team-experience.ts      # TeamExperienceMemory
+│   ├── graph-layers/           # Knowledge graph layers (semantic, temporal, causal, entity)
+│   └── search-provider.ts      # SearchProvider strategy (TextSimilarity, Minimem)
+│
+├── learning/                   # Learning pipeline
+│   ├── unified-pipeline.ts     # UnifiedLearningPipeline (three-speed: immediate + batch + maintenance)
+│   ├── analyzer.ts             # TrajectoryAnalyzer (credit assignment + error patterns)
+│   ├── playbook-extractor.ts   # PlaybookExtractor (heuristic generation)
+│   ├── knowledge-extractor.ts  # KnowledgeExtractor (4 heuristic strategies)
+│   ├── reflexion-generator.ts  # ReflexionGenerator (structured self-critique)
+│   ├── meta-learner.ts         # MetaLearner (routing/retrieval effectiveness)
+│   ├── usage-inference.ts      # PlaybookUsageInference
+│   ├── effectiveness.ts        # LearningEffectivenessTracker
+│   ├── instant-loop.ts         # InstantLoop (hot-path, <200ms, no LLM)
+│   ├── energy-evaluator.ts     # EnergyEvaluator (batch trigger logic)
+│   ├── maintenance-scheduler.ts # MaintenanceScheduler (circadian-gated)
+│   ├── healing-orchestrator.ts # HealingOrchestrator (anomaly detection + repair)
+│   ├── team-pipeline.ts        # TeamLearningPipeline
+│   ├── team-ingester.ts        # TeamTrajectoryIngester
+│   ├── team-meta-learner.ts    # TeamMetaLearner
+│   └── trajectory-sources/     # InMemory, File, Pipeline, Entire, Dataclaw, HuggingFace
+│
+├── search/                     # Routing and solving
+│   ├── router.ts               # TaskRouter (strategy selection)
+│   ├── moe-gate.ts             # MoEGate (learned routing via softmax gate)
+│   ├── solver.ts               # DirectSolver
+│   ├── refinement-loop.ts      # RefinementLoop (up to 3 retries)
+│   ├── evaluator.ts            # SolutionEvaluator
+│   ├── verification-runner.ts  # VerificationRunner (command execution)
+│   └── team-router.ts          # TeamRouter (composition recommender)
+│
+├── runtime/                    # Agent execution
+│   ├── manager.ts              # AgentManager (spawning + knowledge injection)
+│   ├── compute-provider.ts     # ComputeProvider (cost tiers)
+│   ├── subprocess.ts           # SubprocessBackend
+│   ├── acp.ts                  # ACPBackend
+│   ├── mock.ts                 # MockBackend
+│   ├── macro-agent.ts          # MacroAgentBackendAdapter
+│   └── learning.ts, validation.ts  # LearningFlow, ValidationFlow
+│
+├── surfacing/                  # Skill library + publishing
+│   ├── skill-library.ts        # SkillLibrary (Core/Domain/Contextual/OnDemand tiers)
+│   ├── skill-publisher.ts      # SkillPublisher (playbook → skill-tree format)
+│   ├── sqlite-storage-adapter.ts  # SQLite persistence for skill-tree
+│   └── team-skill-library.ts   # TeamSkillLibrary
+│
+├── embeddings/                 # Vector search
+│   ├── manager.ts              # EmbeddingManager (multi-provider)
+│   ├── inverted-index.ts       # InvertedIndex (candidate narrowing)
+│   ├── bm25.ts                 # BM25Index (text search fallback)
+│   ├── vector-store.ts         # SqliteVectorStore (sqlite-vec)
+│   └── provider.ts             # OpenAI, Voyage, Local embedding providers
+│
+├── workspace/                  # Agentic analysis
+│   ├── runner.ts               # AgenticTaskRunner
+│   ├── skill-converter.ts      # Playbook ↔ Skill markdown conversion
+│   └── templates/              # 10 workspace templates
+│
+├── session-bank/               # Claude Code CLI integration
+│   ├── session-bank.ts         # SessionBank
+│   ├── git-reader.ts           # EntireGitReader
+│   └── parser.ts               # EntireTranscriptParser
+│
+├── mcp/                        # MCP server (deprecated)
+│   └── playbook-server.ts
+│
+├── persistence/                # Unified SQLite persistence
+│   ├── sqlite-persistence.ts   # SqlitePersistence (WAL mode, prepared statements, CRUD)
+│   ├── serializers.ts          # Date/embedding/JSON serialization helpers
+│   ├── migrator.ts             # One-time JSON→SQLite migration
+│   └── index.ts                # Barrel exports
+│
+├── utils/                      # Shared utilities
+│   ├── similarity.ts           # cosine, jaccard, text, ngram similarity + tokenize
+│   ├── storage.ts              # JsonStore, saveJson, loadJson, ensureDir (legacy)
+│   ├── partitioned-store.ts    # PartitionedStore (legacy, replaced by SqlitePersistence)
+│   ├── validation.ts           # Zod schemas + validators
+│   ├── frontmatter.ts          # YAML frontmatter parsing for knowledge notes
+│   ├── error-classifier.ts     # Unified error classification (shared by analyzer, reflexion, etc.)
+│   └── trajectory-helpers.ts   # Shared action repetition + tool name extraction
+│
+└── bin/
+    └── cognitive-core.ts       # CLI entry point
+```
+
+## Key Architectural Patterns
+
+### Solve pipeline
+`atlas.solve(task)` is the main entry point. After the agent produces a trajectory, processing runs in this order:
+1. **Post-execution subsystems** (per-solve, synchronous) — PlaybookUsageInference, MetaLearner reflection, EffectivenessTracker annotation. These require `RoutingDecision` + injected playbook context, so they only run via `solve()`, NOT via `processTrajectory()`.
+2. **Unified pipeline** — delegates to `UnifiedLearningPipeline` which manages three speeds:
+   - **Immediate** (InstantLoop, <200ms): store experience, bump playbook confidence, extract lightweight knowledge, causal edges, reflexion episodes
+   - **Batch**: triggered by energy evaluation (not just count). Runs full analysis, playbook extraction, temporal compression, re-clustering, pruning
+   - **Maintenance** (circadian-gated): knowledge defrag, healing orchestrator, meta-strategy generation
+
+Atlas delegates all learning to `UnifiedLearningPipeline`. The pipeline owns InstantLoop, EnergyEvaluator, MaintenanceScheduler, and HealingOrchestrator internally.
+
+### processTrajectory() vs solve()
+`atlas.processTrajectory(trajectory)` runs only the unified learning pipeline (immediate + batch + maintenance). The post-execution subsystems (UsageInference, MetaLearner, EffectivenessTracker) do NOT run — they need routing context from `solve()`. Use `processTrajectory()` for feeding external trajectories.
+
+### Shared candidate retrieval
+`memory/candidate-retrieval.ts` implements the "InvertedIndex narrow → fallback to full scan" pattern used by ExperienceMemory, PlaybookLibrary, and CausalStore. Don't duplicate this pattern.
+
+### Shared error classification
+`utils/error-classifier.ts` provides canonical error types used by TrajectoryAnalyzer and ReflexionGenerator. Don't create local error classification — use `classifyError()` or `classifyErrorType()`.
+
+### Shared trajectory helpers
+`utils/trajectory-helpers.ts` provides `detectRepeatedActions()` and `extractToolNames()` used by analyzer, reflexion-generator, and meta-learner. Don't duplicate action counting or tool name regex.
+
+### Unified SQLite persistence
+All system-internal data lives in a single SQLite database (`.atlas/cognitive-core.db`) managed by `SqlitePersistence`. This includes experiences, playbooks, reflexion episodes, causal edges, meta observations/strategies, playbook version history, and system state (MoEGate weights, ReasoningBank clusters, TemporalCompressor pending demotions).
+
+Two persistence layers, separated by audience:
+
+| Layer | What | Format | Managed by |
+|-------|------|--------|------------|
+| **SQLite DB** (system-internal) | Experiences, playbooks, causal edges, meta state, routing weights, version history | `.atlas/cognitive-core.db` | SqlitePersistence |
+| **Files** (agent-accessible) | Knowledge notes | Markdown + YAML frontmatter | KnowledgeBank |
+| | Published skills | skill-tree format | SkillPublisher / SqliteStorageAdapter (own `skills.db`) |
+| | Session transcripts | git orphan branch | SessionBank |
+
+Memory stores (ExperienceMemory, PlaybookLibrary, ReflexionMemory, CausalStore, MetaMemory) use write-through to SQLite — no dirty tracking, immediate INSERT/UPDATE. InvertedIndex is an in-memory cache rebuilt from SQLite on `init()`.
+
+System state for stateful subsystems (MoEGate, ReasoningBank, TemporalCompressor) is persisted via the `system_state` key-value table and restored on startup via `loadPersistedState()`.
+
+Playbook versioning: `snapshotPlaybookVersion()` captures pre-mutation snapshots to `playbook_versions` table on `recordSuccess`, `recordFailure`, and `evolve` calls.
+
+### JSON→SQLite migration
+`persistence/migrator.ts` auto-detects old JSON files on first startup and migrates them to SQLite. Old directories are renamed to `{collection}.migrated/` as backup.
+
+### Knowledge storage
+Knowledge notes are Markdown files with YAML frontmatter. Types: observation, entity, domain-summary. Stored in `knowledge/{observations,entities,domains}/`. Any filesystem-aware agent can read them directly.
+
+### Factory pattern for external consumers
+`factory.ts` provides `CognitiveCoreFactory` for skill-tree and other external integrations. Prefer using factory for external consumers rather than direct imports.
+
+## Coding Conventions
+
+- **TypeScript strict mode** — `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch` all enabled
+- **ES modules** — all imports use `.js` extensions (TypeScript ESM convention)
+- **Target**: ES2022, module: ESNext, moduleResolution: bundler
+- **Creator functions** — every class has a `createX()` factory function exported alongside it (e.g., `createAnalyzer()`, `createMetaLearner()`)
+- **Config pattern** — classes take `Partial<Config>` and merge with `DEFAULT_CONFIG` using spread
+- **Type-only imports** — use `import type { ... }` for types that aren't used at runtime
+- **Re-exports** — each directory has an `index.ts` barrel file; root `index.ts` re-exports everything
+- **No default exports** — all exports are named
+
+## Testing
+
+- Framework: Vitest with `globals: true`
+- Test files mirror source structure: `tests/learning/analyzer.test.ts` tests `src/learning/analyzer.ts`
+- Helper factories for test data: `createTrajectory()`, `createTask()`, `createStep()`, `successOutcome()`, `failureOutcome()`
+- Tests are unit-level; `tests/integration/` has e2e tests
+- Test timeout: 10s default
+
+## Dependencies
+
+Key runtime dependencies:
+- `agent-workspace` — workspace management (WorkspaceManager, WorkspaceHandle)
+- `better-sqlite3` + `sqlite-vec` — unified SQLite persistence + vector store
+- `yaml` — YAML frontmatter parsing
+- `zod` — schema validation
+- `acp-factory` — Agent Communication Protocol
+- `minimem` — optional hybrid search
+- `skill-tree` — skill publishing (has unresolved import issues in surfacing/)
+
+## Common Tasks
+
+### Adding a new memory store
+1. Create `src/memory/my-store.ts` with the store class
+2. Constructor takes `SqlitePersistence` — add table DDL in `sqlite-persistence.ts` `createTables()`
+3. Add to `src/memory/index.ts` barrel exports
+4. Wire into `MemorySystem` in `src/memory/system.ts`
+5. Use `getCandidates()` from `candidate-retrieval.ts` for retrieval if using InvertedIndex
+6. Add to root `src/index.ts` exports
+
+### Adding a new workspace template
+1. Create `src/workspace/templates/my-template.ts`
+2. Export the template constant
+3. Wire into `src/workspace/index.ts`
+
+### Adding a new learning component
+1. Create in `src/learning/`
+2. Wire into `LearningPipeline.batch()` or `InstantLoop.process()` as appropriate
+3. If shared logic exists, add to `utils/error-classifier.ts` or `utils/trajectory-helpers.ts`
+
+### Modifying error classification
+Update `src/utils/error-classifier.ts` — this is the single source of truth. Don't add local error classification logic in consumers.