cognitive-core 0.1.2 → 0.2.0

package/README.md

@@ -9,9 +9,13 @@ A TypeScript learning system for AI agents. Records how agents solve problems, e
 - [Quick Start](#quick-start)
 - [How It Works](#how-it-works)
 - [Knowledge Bank](#knowledge-bank)
+- [Learning Pipeline](#learning-pipeline)
+- [Three-Speed Pipeline Detail](#three-speed-learning-pipeline)
 - [CLI](#cli)
 - [Agent Backends](#agent-backends)
 - [Skill Library](#skill-library)
+- [Session Bank](#session-bank)
+- [Workspace Templates](#workspace-templates)
 - [Configuration](#configuration)
 - [Core Types](#core-types)
 - [Research References](#research-references)
@@ -27,8 +31,11 @@ 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
+4. **Routing** matches incoming tasks to relevant playbooks before the agent starts working, using a learned MoE gating function
 5. **Meta-learning** tracks which playbooks helped and adjusts routing over time
+6. **Three-speed learning** — immediate per-trajectory updates (<200ms), energy-triggered batch extraction, and circadian-gated maintenance — all managed by a single `UnifiedLearningPipeline`
+7. **Temporal compression** — experiences flow through Hot/Warm/Cold/Evicted tiers based on access frequency, keeping memory bounded
+8. **Unified persistence** — all system state lives in a single SQLite database with WAL mode, including learned MoE routing weights, experience clusters, and playbook version history that survive restarts
 
 The result: agents that get measurably better at recurring problem types without fine-tuning or prompt engineering.
 
@@ -38,7 +45,7 @@ The result: agents that get measurably better at recurring problem types without
 npm install cognitive-core
 ```
 
-Requires Node.js 18+.
+Requires Node.js 22+.
 
 ## Quick Start
 
@@ -98,7 +105,9 @@ const trajectory = createTrajectory({
 });
 
 const result = await atlas.processTrajectory(trajectory);
-console.log(result.abstractable);  // true - system can extract a playbook from this
+// result.instantLoop.experienceId  — stored experience
+// result.batchTriggered             — whether batch learning was auto-triggered
+// result.maintenanceTriggered       — whether maintenance cycle ran
 
 await atlas.close();
 ```
@@ -126,40 +135,148 @@ Every call to `atlas.solve(task)` runs through this pipeline:
 
 ```mermaid
 flowchart TD
-    Task[Task arrives] --> Router[TaskRouter]
+    Task[Task arrives] --> Router[TaskRouter + MoEGate]
 
     Router -->|queries| Memory[MemorySystem]
     Memory --> Exp[ExperienceMemory]
     Memory --> PB[PlaybookLibrary]
     Memory --> KB[KnowledgeBank]
     Memory --> Meta[MetaMemory]
+    Memory --> RB[ReasoningBank]
+    Memory --> CS[CausalStore]
 
     Router --> Decision{RoutingDecision}
 
-    Decision --> Agent[AgentManager]
-    Agent -->|injects playbooks + knowledge| Backend[Backend]
+    Decision --> Skills[SkillLibrary + KnowledgeBank surfacing]
+    Skills -->|injects playbooks + knowledge| Agent[AgentManager]
+    Agent --> Backend[Backend]
     Backend -->|returns trajectory| Session[AgentSession]
 
     Session --> Check{Succeeded?}
-    Check -->|Yes| Learn[LearningPipeline]
+    Check -->|Yes| PostExec[Post-execution]
     Check -->|No| Refine{Retry?}
     Refine -->|Yes, max 3x| Agent
-    Refine -->|No| Learn
+    Refine -->|No| PostExec
+
+    PostExec --> Usage[PlaybookUsageInference]
+    PostExec --> MetaReflect[MetaLearner reflection]
+    PostExec --> Effective[EffectivenessTracker annotate]
+
+    PostExec --> Pipeline[UnifiedLearningPipeline]
+
+    Pipeline --> Immediate[Speed 1: Immediate]
+    Immediate --> Store[Store experience]
+    Immediate --> Bump[Bump playbook confidence]
+    Immediate --> QuickK[Extract knowledge notes]
+    Immediate --> Causal[Extract causal edges]
+    Immediate --> Reflexion[Generate reflexion episode]
+
+    Pipeline --> Energy{EnergyEvaluator}
+    Energy -->|threshold reached| Batch[Speed 2: Batch]
+    Energy -->|below threshold| Done[Done]
+    Batch --> Extract[PlaybookExtractor]
+    Batch --> DeepK[Batch knowledge extraction]
+    Batch --> Compress[TemporalCompressor]
+    Batch --> Cluster[ReasoningBank re-cluster]
+    Batch --> Prune[ExperienceMemory prune]
+
+    Batch --> MaintCheck{Maintenance due?}
+    MaintCheck -->|Yes| Maint[Speed 3: Maintenance]
+    MaintCheck -->|No| Done
+    Maint --> Heal[HealingOrchestrator]
+    Maint --> Defrag[Knowledge defrag]
+    Maint --> MetaStrat[Meta-strategy generation]
+    Maint --> Done
+
+    Done -.->|next task| Router
+```
 
-    Learn --> Analyze[TrajectoryAnalyzer]
-    Learn --> Extract[PlaybookExtractor]
-    Learn --> KnowExtract[KnowledgeExtractor]
-    Learn --> Usage[UsageInference]
-    Learn --> MetaLearn[MetaLearner]
+### Post-execution subsystems
 
-    Analyze --> Updated[Memory updated]
-    Extract --> Updated
-    KnowExtract --> Updated
-    Usage --> Updated
-    MetaLearn --> Updated
+After every `solve()` call, three subsystems run synchronously on the trajectory before it enters the learning pipeline. These require the `RoutingDecision` and injected playbook context, so they **only run via `solve()`** — not via `processTrajectory()`.
 
-    Updated -.->|next task| Router
-```
+| Subsystem | What it does |
+|-----------|--------------|
+| **PlaybookUsageInference** | Infers which injected playbooks were actually used by the agent. Records outcomes to SkillLibrary for tier management. |
+| **MetaLearner** | Generates a meta-reflection on routing/retrieval effectiveness. Stores observations and periodically generates meta-strategies. |
+| **EffectivenessTracker** | Annotates the trajectory with which playbooks were surfaced vs. applied and which experiences were retrieved. |
+
+All three use workspace templates (LLM-assisted) when an `AgenticTaskRunner` is set, with heuristic fallback otherwise.
+
+### Three-speed learning pipeline
+
+All learning is managed by the `UnifiedLearningPipeline`, which consolidates InstantLoop, batch extraction, energy-based triggering, maintenance scheduling, and healing into a single orchestrator.
+
+#### Speed 1: Immediate (<200ms, no LLM)
+
+Fires on **every trajectory**. The InstantLoop performs lightweight, synchronous updates:
+
+| Operation | Target |
+|-----------|--------|
+| Store experience | ExperienceMemory |
+| Bump matched playbook confidence | PlaybookLibrary |
+| Extract lightweight knowledge notes | KnowledgeBank |
+| Extract causal edges | CausalStore |
+| Generate reflexion episode | ReflexionMemory |
+
+After the instant loop, the trajectory is analyzed (heuristic or workspace template) and accumulated for batch.
+
+#### Speed 2: Batch (energy-triggered)
+
+Triggered by the `EnergyEvaluator` — not just a count threshold. The evaluator computes an energy score from signals:
+
+| Signal | Weight | Trigger condition |
+|--------|--------|-------------------|
+| Count threshold | — | `pendingCount >= countThreshold` (default: `minTrajectories`) |
+| Contradiction detected | 0.4 | Coherence checker flagged a conflict |
+| Novel domain | 0.3 | First trajectory in an unseen domain |
+| High error rate | 0.2 | Recent failure rate exceeds 60% |
+| Pattern shift | 0.1 | External signal (e.g., from caller) |
+
+Batch triggers when `pendingCount >= countThreshold` **or** `energy >= energyThreshold (0.7)`, subject to a debounce interval (`minIntervalMs`, default: 30s).
+
+When batch runs:
+
+1. **Playbook extraction** — extract new playbooks from trajectory clusters, refine existing ones
+2. **Batch knowledge extraction** — richer than instant-loop extraction, covers all accumulated trajectories
+3. **Temporal compression** — promote/demote/evict experiences across Hot/Warm/Cold/Evicted tiers
+4. **Re-clustering** — ReasoningBank rebuilds K-means++ clusters from current experiences
+5. **Pruning** — ExperienceMemory prunes beyond `maxExperiences`
+6. **Meta-learning** — MetaLearner generates routing strategies
+
+After batch completes, accumulated trajectories are cleared and the energy evaluator resets.
+
+#### Speed 3: Maintenance (circadian-gated)
+
+Runs after batch when the `MaintenanceScheduler` signals readiness. Three scheduling modes:
+
+| Mode | When maintenance runs |
+|------|----------------------|
+| `manual` | Only via explicit `runMaintenance({ force: true })` |
+| `afterNBatches` | After every N batch cycles (e.g., `batchInterval: 2`) |
+| `periodic` | After a time interval since last maintenance |
+
+Built-in maintenance tasks:
+
+| Task | What it does |
+|------|--------------|
+| **healing-cycle** | `HealingOrchestrator` runs anomaly detectors (PlaybookDriftDetector, MemoryBloatDetector) and applies repair strategies |
+| **knowledge-defrag** | KnowledgeBank merges duplicate/overlapping notes |
+| **meta-strategy-generation** | MetaLearner generates new routing strategies from accumulated observations |
+
+Custom maintenance tasks and anomaly detectors can be registered via `registerMaintenanceTask()` and `addAnomalyDetector()`.
+
+#### `solve()` vs `processTrajectory()`
+
+| | `atlas.solve(task)` | `atlas.processTrajectory(trajectory)` |
+|---|---|---|
+| **Routing** | Yes — TaskRouter + MoEGate | No |
+| **Agent execution** | Yes — AgentManager + refinement | No (trajectory provided externally) |
+| **Post-execution** | Yes — UsageInference, MetaLearner, EffectivenessTracker | No (requires routing context) |
+| **Three-speed pipeline** | Yes | Yes |
+| **Returns** | `SolveResult` (trajectory, routing, playbook usage) | `ImmediateResult` (instant loop, energy eval, batch/maintenance results) |
+
+Use `solve()` when Atlas owns execution. Use `processTrajectory()` to feed in external trajectories — the full three-speed pipeline still runs, but post-execution subsystems that require routing context are skipped.
 
 ### Playbook lifecycle
 
@@ -187,7 +304,7 @@ stateDiagram-v2
 
 ### Memory architecture
 
-The four memory stores serve different retrieval patterns:
+Seven memory stores serve different retrieval patterns:
 
 ```mermaid
 graph LR
@@ -196,9 +313,13 @@ graph LR
         P[PlaybookLibrary]
         K[KnowledgeBank]
         M[MetaMemory]
+        RB[ReasoningBank]
+        CS[CausalStore]
+        RF[ReflexionMemory]
     end
 
     subgraph Search
+        II[InvertedIndex]
         BM[BM25 Index]
         VS[sqlite-vec]
         TS[Text Similarity]
@@ -211,35 +332,55 @@ graph LR
         MM[minimem optional]
     end
 
+    E --> II
     E --> BM
     E --> VS
+    P --> II
     P --> BM
     P --> VS
     K --> TS
     K -.-> MM
+    CS --> II
+    CS --> TS
+    RB --> TS
     VS -.-> OAI
     VS -.-> VOY
     VS -.-> HF
 
     subgraph Storage
-        JSON[JSON files]
-        SQL[SQLite]
+        SQL[SQLite — cognitive-core.db]
         MD[Markdown + YAML]
+        SKILL[SQLite — skills.db]
     end
 
-    E --> JSON
-    P --> JSON
-    M --> JSON
-    K --> MD
+    E --> SQL
+    P --> SQL
+    M --> SQL
+    CS --> SQL
+    RF --> SQL
+    RB -.->|system_state| SQL
     VS --> SQL
+    K --> MD
 ```
 
 | Store | Purpose | Format |
 |-------|---------|--------|
-| **ExperienceMemory** | Episodic — *what happened* | JSON |
-| **PlaybookLibrary** | Procedural — *how to do things* | JSON |
+| **ExperienceMemory** | Episodic — *what happened* | SQLite |
+| **PlaybookLibrary** | Procedural — *how to do things* | SQLite (with version history) |
 | **KnowledgeBank** | Semantic — *facts, concepts, relationships* | Markdown + YAML frontmatter |
-| **MetaMemory** | Meta-learning — *what worked* | JSON |
+| **MetaMemory** | Meta-learning — *what worked* | SQLite |
+| **ReasoningBank** | Clustered experience retrieval (K-means++) | SQLite (system_state) |
+| **CausalStore** | Cause-effect relationships | SQLite |
+| **ReflexionMemory** | Structured self-reflections | SQLite |
+
+### Candidate retrieval
+
+All memory stores use a shared two-phase retrieval pattern:
+
+1. **InvertedIndex narrowing** — tokenize the query, find candidate IDs via posting lists (fast, O(query tokens))
+2. **Fallback to full scan** — if the index returns fewer candidates than needed, fall back to the full store or domain partition
+
+This is implemented once in `memory/candidate-retrieval.ts` and shared by ExperienceMemory, PlaybookLibrary, and CausalStore.
 
 ### Search and matching
 
@@ -247,6 +388,32 @@ Memory search uses BM25 text matching by default. For higher-quality retrieval,
 
 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.
 
+### MoE routing gate
+
+The TaskRouter uses a **Mixture-of-Experts inspired gating function** to select routing strategies. Instead of fixed threshold rules, a learned linear gate computes `softmax(W · features)` over the four strategies (direct, adapt, explore, fallback). Weights are updated online from outcome feedback, with per-domain specialization. Cold start falls back to uniform weights (equivalent to the original threshold logic).
+
+### Temporal compression
+
+Experiences flow through four tiers based on their access frequency:
+
+| Tier | Fidelity | Threshold |
+|------|----------|-----------|
+| **Hot** | Full data preserved | accessScore > 0.5 |
+| **Warm** | Key steps only (solutionOutput stripped) | accessScore > 0.2 |
+| **Cold** | Single-paragraph summary | accessScore > 0.05 |
+| **Evicted** | Removed (pattern captured in ReasoningBank) | accessScore < 0.05 |
+
+Hysteresis prevents oscillation: an experience must stay below a threshold for 2 consecutive compression passes before demotion.
+
+### Coherence checking
+
+Before inserting new knowledge notes, the `CoherenceChecker` detects contradictions using a simplified sheaf-inspired approach:
+
+1. Filter existing notes to the same entity/domain
+2. Compute text similarity between new and candidate notes
+3. Detect sentiment conflicts via negation heuristics (e.g., "always" vs "never", "use" vs "avoid")
+4. Flag contradictions where `residualEnergy = similarity × sentimentConflict` exceeds threshold
+
 ## 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.
@@ -303,9 +470,10 @@ Trajectory → KnowledgeExtractor → Observations (confidence: 0.3)
 
 Knowledge evolves through:
 - **Reinforcement** — same fact observed again increases confidence
-- **Contradiction detection** — conflicting facts are flagged and resolved
+- **Contradiction detection** — conflicting facts are flagged by the CoherenceChecker and resolved
 - **Consolidation** — observations about the same entity merge into entity notes
 - **Decay** — unvalidated knowledge gradually loses confidence
+- **Defragmentation** — the KnowledgeDefragmenter merges duplicate/overlapping notes
 
 ### Knowledge surfacing
 
@@ -327,47 +495,150 @@ When [minimem](https://github.com/alexngai/minimem) is available, the knowledge
 
 See [Design Doc](docs/DESIGN-semantic-memory-knowledge-bank.md) for the full architecture.
 
+## Learning Pipeline
+
+### Knowledge extraction
+
+The `KnowledgeExtractor` runs four heuristic strategies per trajectory:
+
+1. **Error patterns** — extracts observations from error signatures and suggested fixes
+2. **Config facts** — detects reads/writes of config files (package.json, tsconfig, etc.) and captures versions
+3. **Causal chains** — identifies failure→recovery step sequences and creates causal links
+4. **Entity identification** — matches known entities in observations and produces entity updates
+
+### Reflexion generation
+
+The `ReflexionGenerator` creates structured self-reflection episodes from completed trajectories. Each episode includes:
+- Outcome classification (success/partial/failure)
+- Self-critique (wasted effort, thrashing detection)
+- Key insights (tools used, file paths, error patterns)
+- Strategy assessment against matched playbooks
+- Suggested playbook updates
+
+### Shared utilities
+
+Common analysis patterns are consolidated into shared utilities to avoid duplication:
+
+| Utility | Used by |
+|---------|---------|
+| `classifyError()` / `classifyErrorType()` | TrajectoryAnalyzer, ReflexionGenerator |
+| `detectRepeatedActions()` | TrajectoryAnalyzer, ReflexionGenerator, MetaLearner |
+| `extractToolNames()` | ReflexionGenerator, MetaLearner |
+| `getCandidates()` | ExperienceMemory, PlaybookLibrary, CausalStore |
+
 ## CLI
 
-cognitive-core ships a CLI for querying playbooks and storing trajectories without writing code.
+cognitive-core ships a CLI for operating the learning system — ingesting trajectories, querying memory, and running maintenance. Available as both `cogcore` (short) and `cognitive-core`.
+
+```bash
+npm install -g cognitive-core
+cogcore help
+```
+
+### Daemon mode
+
+The primary operational command. Polls SessionLog for new coding sessions and feeds them through the learning pipeline automatically.
+
+```bash
+# Continuous mode — watch for new sessions and process them
+cogcore run --repo /path/to/repo --interval 30
+
+# One-shot mode — process all unprocessed sessions and exit
+cogcore run --once --repo /path/to/repo
+```
+
+The flow: `SessionBank.discover()` → filter unprocessed → `SessionTrajectorySource.synthesize()` → `atlas.processTrajectory()` → `bank.markProcessed()`. Supports graceful shutdown via SIGINT/SIGTERM.
+
+### Playbook commands
 
 ```bash
 # Initialize storage
-cognitive-core init --dir .cognitive-core
+cogcore init
 
 # Store a trajectory from a JSON file
-cognitive-core store ./trajectory.json
+cogcore store ./trajectory.json
 
 # Search for relevant playbooks
-cognitive-core search "fix typescript import errors" --domain code
+cogcore 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
+cogcore get playbook-abc123
 
-# List domains with playbooks
-cognitive-core domains
+# List domains with playbook counts
+cogcore domains
 
-# View memory statistics
-cognitive-core stats
-# Experiences: 47
-# Playbooks: 12
-# Meta-observations: 31
+# View system statistics
+cogcore stats
 ```
 
-All commands support `--json` for structured output:
+### Knowledge bank
+
+Query and manage the semantic memory store (observations, entities, domain summaries).
 
 ```bash
-cognitive-core search "debug async errors" --json | jq '.results[0].strategy'
+cogcore kb search "prisma migration"
+cogcore kb list                        # all notes
+cogcore kb list --type entities        # entity notes only
+cogcore kb list --type domains         # domain summaries only
+cogcore kb get prisma                  # by ID, entity name, or domain name
+cogcore kb stats                       # observation/entity/domain counts, graph stats
+cogcore kb defrag                      # deduplicate, process inbox, run decay
+```
+
+### Sessions
+
+Inspect SessionLog checkpoint data from git orphan branches. SessionBank is standalone — it reads directly from the git repo without Atlas.
+
+```bash
+cogcore sessions list --repo .
+cogcore sessions get 2026-02-15-aabbccdd-1122-3344-5566-778899aabbcc
+cogcore sessions query --agent "Claude Code" --since 2026-01-01 --limit 10
+```
+
+### Learning pipeline
+
+Operator controls for the three-speed learning pipeline.
+
+```bash
+cogcore learn stats                    # processed count, pending, batch/maintenance cycles
+cogcore learn batch                    # force batch learning on accumulated trajectories
+cogcore learn maintenance              # force maintenance cycle (defrag, healing, meta-strategies)
+```
+
+### Skill library
+
+Inspect and manage the tiered skill system.
+
+```bash
+cogcore skills list                    # all skills with tier, confidence, success rate
+cogcore skills list --tier core        # core skills only (always in system prompt)
+cogcore skills list --tier domain      # domain skills only
+cogcore skills stats                   # core/domain counts, last refresh
+cogcore skills refresh                 # trigger tier re-evaluation (promotions/demotions)
+```
+
+### Global options
+
+All commands support these flags:
+
+| Flag | Description |
+|------|-------------|
+| `--dir <path>` | Storage directory (default: `.cognitive-core`) |
+| `--json` | Machine-readable JSON output |
+| `--limit <n>` | Maximum results |
+| `--domain <d>` | Filter by domain |
+| `--repo <path>` | Git repository path (for sessions/run) |
+
+```bash
+# Pipe JSON output to jq
+cogcore search "debug async errors" --json | jq '.[0].strategy'
+cogcore kb stats --json | jq '.observationCount'
 ```
 
 ## Agent Backends
@@ -467,12 +738,57 @@ const skills = await atlas.getSkillLibrary()?.getSkillsForAgent(task);
 // skills.contextual - matched to this specific task
 ```
 
+### skill-tree integration
+
+When `skillTree.enabled` is true (default), playbooks are published to a `skill-tree` SQLite database via `SqliteStorageAdapter`, making them available to external consumers.
+
+### Team skill library
+
+For multi-agent systems, the `TeamSkillLibrary` surfaces team-level and role-specific playbooks with ELO-based ranking from team outcome feedback.
+
+## Session Bank
+
+The session bank provides integration with the Claude Code CLI, enabling cognitive-core to learn from real coding sessions.
+
+```typescript
+import { SessionBank, EntireGitReader, EntireTranscriptParser } from 'cognitive-core';
+```
+
+Components:
+- **EntireGitReader** — reads session transcripts from Claude Code's git-based storage
+- **EntireTranscriptParser** — parses raw transcripts into structured `SessionRecord` objects
+- **SessionBank** — manages session records with querying by date range, domain, and outcome
+
+The `EntireTrajectorySource` bridges session bank records into trajectories for the learning pipeline.
+
+## Workspace Templates
+
+The workspace system provides LLM-assisted analysis via structured templates. Each template defines inputs, outputs, and a processing prompt. The `AgenticTaskRunner` executes templates against a workspace.
+
+Available templates:
+
+| Template | Purpose |
+|----------|---------|
+| `trajectory-analysis` | Deep trajectory analysis with LLM |
+| `playbook-extraction` | Extract playbooks from trajectory clusters |
+| `knowledge-extraction` | LLM-assisted knowledge extraction |
+| `usage-inference` | Infer which playbooks were actually used |
+| `meta-reflection` | Generate meta-learning observations |
+| `solution-evaluation` | Evaluate solution quality |
+| `refinement-analysis` | Analyze refinement opportunities |
+| `knowledge-defrag` | Merge overlapping knowledge notes |
+| `team-playbook-extraction` | Extract team-level playbooks |
+| `team-trajectory-analysis` | Analyze multi-agent trajectories |
+
+Templates can run in heuristic mode (no LLM, pattern matching only) or agentic mode (LLM-assisted, higher quality).
+
 ## Configuration
 
 ```typescript
 const atlas = createAtlasWithAgents([backend], {
   storage: {
     baseDir: '.cognitive-core',
+    dbName: 'cognitive-core.db',   // SQLite database filename
     persistenceEnabled: true,
   },
   learning: {
@@ -607,16 +923,16 @@ cognitive-core draws from several lines of research on agent memory and learning
 - **[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
+- **ruvector** - Inspiration for infrastructure improvements: ReasoningBank (K-means++ clustering), MoE routing gate, CoherenceChecker (sheaf-inspired), TemporalCompressor (tiered memory), InstantLoop (hot-path learning)
 
 ## 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.
+- **Cold start**. The system needs ~10 trajectories before batch learning kicks in and playbooks start appearing. The instant loop provides per-trajectory updates immediately, and knowledge extraction works per-trajectory, so some learning is available sooner.
+- **Text-based matching by default**. BM25 and inverted index candidate narrowing work but miss 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, confidence model, and temporal compression help, but don't solve the garbage-in problem.
+- **Single-machine storage**. All system-internal data lives in a single SQLite database (`cognitive-core.db` with WAL mode), knowledge notes are Markdown files, and skills use a separate `skills.db`. 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
 

package/dist/atlas.d.ts

@@ -1,13 +1,13 @@
 import type { Task, Trajectory, TeamTrajectory, TeamPlaybook, AtlasConfig, Playbook } from './types/index.js';
 import type { KnowledgeMatch } from './types/knowledge.js';
 import { MemorySystem, type TeamExperience } from './memory/index.js';
-import { LearningPipeline, type ProcessResult, type BatchResult } from './learning/index.js';
+import { UnifiedLearningPipeline, type ImmediateResult, type UnifiedBatchResult } from './learning/unified-pipeline.js';
 import { TeamLearningPipeline, type TeamBatchResult, type TeamProcessResult } from './learning/team-pipeline.js';
 import { TeamMetaLearner } from './learning/team-meta-learner.js';
 import { TeamRouter, type TeamRecommendation, type TeamRecommendationInput } from './search/team-router.js';
 import { TeamSkillLibrary, type TeamOutcomeFeedback } from './surfacing/team-skill-library.js';
-import { MetaLearner } from './learning/meta-learner.js';
-import { LearningEffectivenessTracker } from './learning/effectiveness.js';
+import type { MetaLearner } from './learning/meta-learner.js';
+import type { LearningEffectivenessTracker } from './learning/effectiveness.js';
 import { type RoutingDecision } from './search/router.js';
 import { RefinementLoop } from './search/refinement-loop.js';
 import type { RefinementResult } from './search/refinement-types.js';
@@ -98,7 +98,7 @@ export interface SolveResult {
  */
 export declare class Atlas {
     private memory;
-    private learning;
+    private unifiedPipeline;
     private router;
     private solver;
     private agentManager;
@@ -111,14 +111,13 @@ export declare class Atlas {
     private skillTreeStorage;
     private usageInference;
     private mcpServer;
-    private metaLearner;
-    private effectivenessTracker;
     private taskRunner;
     private workspaceManager;
     private teamLearning;
     private teamRouter;
     private teamMetaLearner;
     private teamSkillLibrary;
+    private persistence;
     constructor(config?: Partial<AtlasConfig>);
     /**
      * Initialize Atlas (load persisted data)
@@ -175,9 +174,10 @@ export declare class Atlas {
      */
     solveBatch(tasks: Task[]): Promise<SolveResult[]>;
     /**
-     * Process an external trajectory (from another agent)
+     * Process an external trajectory (from another agent).
+     * Runs the instant loop first (hot path), then feeds into the batch pipeline.
      */
-    processTrajectory(trajectory: Trajectory): Promise<ProcessResult>;
+    processTrajectory(trajectory: Trajectory): Promise<ImmediateResult>;
     /**
      * Process a team trajectory through the full team learning pipeline.
      * Ingests, analyzes (heuristic or agentic), stores, and accumulates
@@ -246,7 +246,7 @@ export declare class Atlas {
     /**
      * Run batch learning explicitly
      */
-    runBatchLearning(): Promise<BatchResult>;
+    runBatchLearning(): Promise<UnifiedBatchResult>;
     /**
      * Query memory for relevant context
      */
@@ -270,7 +270,7 @@ export declare class Atlas {
     /**
      * Get the learning pipeline for direct access
      */
-    getLearning(): LearningPipeline;
+    getLearning(): UnifiedLearningPipeline;
     /**
      * Get the skill library for direct access
      */