cognitive-core 0.0.2 → 0.1.2

package/docs/DESIGN-semantic-memory-knowledge-bank.md

@@ -0,0 +1,1789 @@
+# Design: Semantic Memory & Knowledge Bank
+
+> **Status**: Implemented (Phases 1-5 complete)
+> **Authors**: Alex Ngai, Claude
+> **Date**: 2026-02-18
+> **Related**: [A-MEM](https://arxiv.org/abs/2502.12110), [MAGMA](https://arxiv.org/abs/2601.03236), [Zep](https://arxiv.org/pdf/2501.13956), [Memory Survey](https://arxiv.org/abs/2512.13564)
+
+## 1. Motivation
+
+cognitive-core has strong **procedural memory** (PlaybookLibrary — *how* to do things) and **episodic memory** (ExperienceMemory — *what happened*), but lacks **semantic memory** — a structured knowledge bank that stores *facts, concepts, and relationships* independently of any specific task or procedure.
+
+Today, an agent that learns "Prisma requires `db push` before `migrate dev` when the schema has drifted" can only encode that as:
+- A playbook tactic (procedural — loses the standalone factual nature)
+- An experience tuple (episodic — buried in a specific task context, hard to generalize)
+
+Neither representation lets the agent answer "What do I know about Prisma?" or "What changed about our database setup recently?" These are **semantic queries** that require a dedicated knowledge store.
+
+### The minimem Opportunity
+
+[minimem](https://github.com/alexngai/minimem) already provides a file-based, versioned memory system with hybrid search (vector + BM25). Agents can read and write markdown memory files directly. However, minimem currently lacks:
+
+- **Organization structure** — agents dump unstructured notes with no consistent taxonomy
+- **Relationship tracking** — no links between related knowledge
+- **Extraction pipeline** — knowledge must be manually written, not extracted from experience
+- **Evolution tracking** — no confidence, staleness, or contradiction detection
+
+This design proposes adding a **Knowledge Bank** to cognitive-core that uses the filesystem as its universal primary index (compatible with minimem), while adding extraction, organization, graph indexing, and evolution on top.
+
+## 2. Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     cognitive-core                           │
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐   │
+│  │  Playbook    │  │  Experience │  │  Knowledge Bank   │   │
+│  │  Library     │  │  Memory     │  │  (NEW)            │   │
+│  │  (procedural)│  │  (episodic) │  │  (semantic)       │   │
+│  └──────┬───── ┘  └──────┬──────┘  └───────┬──────────┘   │
+│         │                │                  │               │
+│         │     ┌──────────┴──────────┐       │               │
+│         └─────┤   Learning Pipeline ├───────┘               │
+│               │                     │                       │
+│               │  PlaybookExtractor  │                       │
+│               │  KnowledgeExtractor │  ← NEW                │
+│               │  (parallel paths)   │                       │
+│               └─────────┬───────────┘                       │
+│                         │                                   │
+│                    Trajectories                              │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                    writes/reads
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                  Filesystem (minimem-compatible)             │
+│                                                             │
+│  memory/                                                    │
+│  ├── knowledge/          ← structured by domain/entity      │
+│  │   ├── domains/        ← domain summaries                 │
+│  │   ├── entities/       ← tool/library/pattern notes       │
+│  │   └── observations/   ← atomic facts                     │
+│  ├── episodes/           ← episodic summaries               │
+│  └── .knowledge/         ← graph overlay + index metadata   │
+│      ├── graph.json                                         │
+│      └── manifest.json                                      │
+│                                                             │
+│  (Agent can read/write these files directly via filesystem  │
+│   or minimem MCP. cognitive-core maintains the structure.)  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Filesystem is the universal primary index.** Any agent with filesystem access (or minimem MCP) can browse, grep, and read knowledge — no special API required.
+
+2. **cognitive-core is the organizer, not the gatekeeper.** Agents can write raw notes directly. cognitive-core periodically runs an "index/defragmentation" process to organize, link, and consolidate.
+
+3. **Graph overlay is a derived index.** The graph can be rebuilt from file frontmatter. It accelerates relationship queries but is not the source of truth.
+
+4. **Parallel to playbooks, not a replacement.** Knowledge notes answer "what/why"; playbooks answer "how". They cross-reference each other.
+
+5. **minimem provides versioning and sync.** cognitive-core doesn't reimplement these — it assumes a filesystem that may be backed by minimem for versioning, sync, and hybrid search.
+
+## 3. Knowledge Note Format
+
+Each knowledge unit is a markdown file with structured YAML frontmatter. Inspired by A-MEM's Zettelkasten notes but adapted for file-based storage.
+
+### 3.1 Anatomy of a Knowledge Note
+
+```markdown
+---
+id: k-prisma-schema-push-before-migrate
+type: observation                        # observation | entity | domain-summary
+domain: [database, orm]
+entities: [prisma, postgresql]
+tags: [migration, schema-drift, dev-workflow]
+confidence: 0.85                         # 0-1, grows with reinforcing evidence
+source:
+  origin: extracted                      # extracted | agent-authored | imported
+  trajectories: [t-2025-01-15-abc, t-2025-01-18-def]
+  playbooks: [playbook-prisma-setup]     # cross-references
+links:
+  - target: k-prisma-migration-workflow
+    relation: related-to
+  - target: k-typescript-enum-const-export
+    relation: co-occurred
+created: 2025-01-15T10:30:00Z
+updated: 2025-01-18T14:00:00Z
+supersedes: null                         # ID of note this replaces, if any
+---
+
+# Prisma requires schema push before migrate in dev
+
+When using Prisma with PostgreSQL in development, `prisma db push`
+must be run before `prisma migrate dev` if the schema has diverged
+from the database state. Otherwise the migration will fail with
+a drift detection error.
+
+## Context
+
+- Applies to: Prisma 5.x+, PostgreSQL
+- Does NOT apply to: SQLite (push is the only option for SQLite)
+
+## Evidence
+
+- Observed in project-auth (Jan 15): migration failed until push was run first
+- Confirmed in project-api (Jan 18): same pattern, different schema change
+
+## Related
+
+- See also: [Prisma migration workflow](k-prisma-migration-workflow.md)
+```
+
+### 3.2 Note Types
+
+| Type | Purpose | Granularity | Example |
+|---|---|---|---|
+| `observation` | Atomic factual statement learned from experience | One fact per file | "React 19 changed the compiler model" |
+| `entity` | Accumulated knowledge about a specific tool/lib/pattern | One entity per file, multiple sections | "Everything I know about Prisma" |
+| `domain-summary` | High-level summary of a knowledge domain | One domain per file | "Database knowledge overview" |
+
+**Entity notes** are living documents that grow as more observations are made. They serve as **consolidation targets** — when multiple observations about the same entity accumulate, they get merged into the entity note.
+
+**Domain summaries** are periodically regenerated from entity notes and observations within that domain. They provide high-level orientation ("what do I know about testing?").
+
+### 3.3 Frontmatter Schema
+
+```typescript
+interface KnowledgeNoteFrontmatter {
+  /** Unique identifier (kebab-case, prefixed with k-) */
+  id: string;
+
+  /** Note type determines organization and lifecycle */
+  type: 'observation' | 'entity' | 'domain-summary';
+
+  /** Knowledge domains this note belongs to */
+  domain: string[];
+
+  /** Specific entities (tools, libraries, patterns) referenced */
+  entities: string[];
+
+  /** Freeform tags for additional categorization */
+  tags: string[];
+
+  /** Confidence in this knowledge (0-1) */
+  confidence: number;
+
+  /** Where this knowledge came from */
+  source: {
+    origin: 'extracted' | 'agent-authored' | 'imported';
+    /** Trajectory IDs that contributed to this knowledge */
+    trajectories?: string[];
+    /** Playbook IDs that relate to this knowledge */
+    playbooks?: string[];
+    /** For agent-authored: which agent wrote it */
+    agentId?: string;
+  };
+
+  /** Explicit links to other knowledge notes */
+  links: Array<{
+    target: string;        // ID of linked note
+    relation: LinkRelation;
+    layer?: GraphLayerName; // Which graph layer this edge belongs to (default: inferred from relation)
+  }>;
+
+  created: string;         // ISO 8601
+  updated: string;         // ISO 8601
+
+  /** If this note replaces a previous one (contradiction resolution) */
+  supersedes?: string;
+}
+
+/**
+ * Link relations, organized by which graph layer they naturally belong to.
+ * When `layer` is not specified in frontmatter, the layer is inferred from the relation type.
+ */
+
+// Semantic layer relations (conceptual relationships)
+// 'related-to'       — General association
+// 'depends-on'       — A requires B
+// 'specializes'      — A is a more specific case of B
+// 'generalizes'      — A is a more general case of B
+// 'supports'         — A provides evidence for B (also used for playbook cross-refs)
+
+// Temporal layer relations (when things happened/changed)
+// 'observed-before'  — A was learned before B
+// 'observed-after'   — A was learned after B
+// 'co-occurred'      — Observed together in same trajectory
+// 'supersedes'       — A replaces B (newer/corrected knowledge)
+
+// Causal layer relations (cause-effect chains)
+// 'caused-by'        — A was caused by B
+// 'led-to'           — A led to the discovery/occurrence of B
+// 'broke'            — A broke B (e.g., upgrade broke feature)
+// 'enabled'          — A enabled B to work
+// 'prevented'        — A prevented B from happening
+
+// Entity layer relations (tool/component interactions)
+// 'uses'             — A uses B
+// 'part-of'          — A is a component of B
+// 'interacts-with'   — A interacts with B
+// 'contradicts'      — A conflicts with B (one should be superseded)
+// 'created-by'       — A was created by B
+
+type LinkRelation =
+  // Semantic
+  | 'related-to' | 'depends-on' | 'specializes' | 'generalizes' | 'supports'
+  // Temporal
+  | 'observed-before' | 'observed-after' | 'co-occurred' | 'supersedes'
+  // Causal
+  | 'caused-by' | 'led-to' | 'broke' | 'enabled' | 'prevented'
+  // Entity
+  | 'uses' | 'part-of' | 'interacts-with' | 'contradicts' | 'created-by';
+```
+
+## 4. Filesystem Organization
+
+```
+memory/
+├── knowledge/
+│   ├── domains/                          # Domain summaries
+│   │   ├── database.md                   # Auto-generated from entities + observations
+│   │   ├── typescript.md
+│   │   ├── react.md
+│   │   └── testing.md
+│   │
+│   ├── entities/                         # Entity-level knowledge (living docs)
+│   │   ├── prisma.md                     # Everything about Prisma
+│   │   ├── vitest.md
+│   │   ├── next-js-app-router.md
+│   │   └── typescript-enums.md
+│   │
+│   └── observations/                     # Atomic facts (high volume)
+│       ├── k-prisma-schema-push.md
+│       ├── k-react19-compiler-change.md
+│       ├── k-ts54-enum-const-break.md
+│       └── k-vitest-workspace-config.md
+│
+├── episodes/                             # Episodic summaries (existing minimem pattern)
+│   ├── 2025-01-15.md
+│   └── 2025-01-16.md
+│
+├── inbox/                                # Agent-authored raw notes (pre-organization)
+│   └── *.md                              # Unstructured notes from agent direct writes
+│
+└── .knowledge/                           # Index metadata (derived, rebuildable)
+    ├── graph.json                        # Relationship graph overlay
+    ├── manifest.json                     # Note registry with quick-lookup metadata
+    └── domain-index.json                 # Domain → note ID mapping
+```
+
+### 4.1 Directory Semantics
+
+**`knowledge/observations/`** — High-volume, atomic facts. One fact per file. Created by the extraction pipeline or agent direct writes. Naming convention: `k-{entity}-{descriptor}.md`.
+
+**`knowledge/entities/`** — Medium-volume, living documents. One per notable entity (library, tool, pattern, API). Grows over time as observations consolidate. Naming convention: `{entity-name}.md`.
+
+**`knowledge/domains/`** — Low-volume summaries. One per knowledge domain. Periodically regenerated. Naming convention: `{domain-name}.md`.
+
+**`inbox/`** — Raw agent-authored notes that haven't been organized yet. The defragmentation process reads these, extracts structured knowledge, and moves/merges them into the appropriate locations.
+
+**`.knowledge/`** — Derived index files. Can be fully rebuilt from the markdown files' frontmatter. Not intended for direct agent reading (though it's available if useful).
+
+### 4.2 Why This Structure Works for File-Based Retrieval
+
+An agent without any special tooling can:
+
+```bash
+# "What do I know about Prisma?"
+cat memory/knowledge/entities/prisma.md
+
+# "What domains do I have knowledge about?"
+ls memory/knowledge/domains/
+
+# "Any facts about TypeScript enums?"
+grep -rl "enum" memory/knowledge/observations/
+
+# "What changed recently?"
+ls -lt memory/knowledge/observations/ | head -10
+```
+
+This is the filesystem-as-primary-index principle — the directory structure itself is a queryable taxonomy.
+
+## 5. Graph Overlay (Multi-Graph Architecture)
+
+The graph overlay is a derived data structure that accelerates relationship queries. It is stored as JSON and can be rebuilt from frontmatter. Inspired by MAGMA, the graph is decomposed into **orthogonal layers** that each capture a different dimension of knowledge relationships. Layers are pluggable — each can be independently enabled/disabled.
+
+### 5.1 Multi-Graph Design
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  KnowledgeGraphManager               │
+│                                                     │
+│  Unified query interface over pluggable graph layers │
+│                                                     │
+│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │
+│  │Semantic  │ │Temporal  │ │Causal  │ │Entity    │ │
+│  │Graph     │ │Graph     │ │Graph   │ │Graph     │ │
+│  │(default) │ │(optional)│ │(opt.)  │ │(opt.)    │ │
+│  └─────────┘ └──────────┘ └────────┘ └──────────┘ │
+│       │            │           │           │        │
+│       └────────────┴───────────┴───────────┘        │
+│                        │                             │
+│                  Shared node set                     │
+│            (one GraphNode per knowledge note)        │
+└─────────────────────────────────────────────────────┘
+```
+
+All layers share the same node set (one node per knowledge note). Each layer maintains its own edges, capturing a different relationship dimension. The `KnowledgeGraphManager` provides a unified interface that can query across layers or target a specific one.
+
+| Layer | Edge Semantics | Captures | Example Query |
+|---|---|---|---|
+| **Semantic** | `related-to`, `specializes`, `generalizes`, `depends-on`, `supports` | Conceptual relationships between knowledge | "What concepts relate to Prisma?" |
+| **Temporal** | `observed-before`, `observed-after`, `supersedes`, `co-occurred` | When knowledge was learned, how it evolved | "What changed since last month?" |
+| **Causal** | `caused-by`, `led-to`, `broke`, `enabled`, `prevented` | Cause-effect chains between facts | "Why did the build fail?" |
+| **Entity** | `uses`, `part-of`, `created-by`, `interacts-with`, `contradicts` | Relationships between tools/libs/components | "What does this service depend on?" |
+
+### 5.2 Graph Types
+
+```typescript
+/** Shared node — one per knowledge note, used by all layers */
+interface GraphNode {
+  /** Knowledge note ID */
+  id: string;
+
+  /** Relative file path from memory root */
+  file: string;
+
+  /** Note type */
+  type: 'observation' | 'entity' | 'domain-summary';
+
+  /** Domains for fast filtering */
+  domains: string[];
+
+  /** Entities for fast filtering */
+  entities: string[];
+
+  /** Tags for fast filtering */
+  tags: string[];
+
+  /** Current confidence */
+  confidence: number;
+
+  /** Last updated timestamp */
+  updated: string;
+}
+
+/** Edge within a specific graph layer */
+interface GraphEdge {
+  /** Source note ID */
+  from: string;
+
+  /** Target note ID */
+  to: string;
+
+  /** Relationship type (layer determines valid relation types) */
+  relation: string;
+
+  /** Edge weight (0-1, for ranked traversal) */
+  weight: number;
+
+  /** When this edge was established */
+  created: string;
+
+  /** Whether this edge crosses into another system */
+  crossSystem?: 'playbook' | 'experience';
+
+  /** Source trajectory that produced this edge, if any */
+  sourceTrajectory?: string;
+}
+
+/** A single graph layer */
+interface GraphLayer {
+  /** Layer identifier */
+  name: GraphLayerName;
+
+  /** Whether this layer is currently enabled */
+  enabled: boolean;
+
+  /** Edges in this layer */
+  edges: GraphEdge[];
+}
+
+type GraphLayerName = 'semantic' | 'temporal' | 'causal' | 'entity';
+
+/** Top-level multi-graph structure */
+interface KnowledgeMultiGraph {
+  /** Schema version for migration */
+  version: number;
+
+  /** Last rebuild timestamp */
+  lastRebuilt: string;
+
+  /** Shared node registry */
+  nodes: Record<string, GraphNode>;
+
+  /** Graph layers — each independently toggleable */
+  layers: Record<GraphLayerName, GraphLayer>;
+}
+```
+
+### 5.3 Pluggable Layer Interface
+
+Each graph layer implements the same interface, making them interchangeable and independently testable:
+
+```typescript
+interface GraphLayerOperations {
+  /** Get edges from/to a node in this layer */
+  getEdges(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both'): GraphEdge[];
+
+  /** BFS neighbors within this layer */
+  neighbors(nodeId: string, depth?: number): GraphNode[];
+
+  /** Shortest path between two nodes within this layer */
+  pathBetween(fromId: string, toId: string): GraphNode[] | null;
+
+  /** Add an edge to this layer */
+  addEdge(edge: GraphEdge): void;
+
+  /** Remove an edge from this layer */
+  removeEdge(fromId: string, toId: string, relation: string): void;
+
+  /** Rebuild this layer from frontmatter */
+  rebuild(notes: KnowledgeNote[]): void;
+}
+```
+
+The `KnowledgeGraphManager` aggregates these operations:
+
+```typescript
+interface KnowledgeGraphManager {
+  /** Get a specific layer */
+  getLayer(name: GraphLayerName): GraphLayerOperations | null;
+
+  /** Query across all enabled layers (union of edges) */
+  neighbors(nodeId: string, options?: {
+    depth?: number;
+    layers?: GraphLayerName[];   // restrict to specific layers
+    minWeight?: number;
+  }): GraphNode[];
+
+  /** Cross-layer path: can traverse edges from any enabled layer */
+  pathBetween(fromId: string, toId: string, options?: {
+    layers?: GraphLayerName[];
+  }): Array<{ node: GraphNode; edge: GraphEdge; layer: GraphLayerName }>;
+
+  /** Filter nodes by criteria */
+  filterNodes(filter: {
+    domains?: string[];
+    entities?: string[];
+    tags?: string[];
+    type?: GraphNode['type'];
+    minConfidence?: number;
+  }): GraphNode[];
+
+  /** Get cross-system links (to playbooks/experiences) */
+  crossSystemLinks(nodeId: string): GraphEdge[];
+
+  /** Extract domain-scoped subgraph (all layers) */
+  subgraph(domain: string): KnowledgeMultiGraph;
+
+  /** Rebuild all enabled layers from frontmatter */
+  rebuildAll(notes: KnowledgeNote[]): void;
+}
+```
+
+### 5.4 Layer-Specific Query Patterns
+
+Each layer enables different reasoning patterns:
+
+**Semantic layer** (enabled by default):
+- "What concepts relate to this?" → `semantic.neighbors(id)`
+- "Is A a special case of B?" → check for `specializes` path
+- "What playbooks support this knowledge?" → `semantic.getEdges(id)` filtered by `crossSystem`
+
+**Temporal layer** (optional):
+- "What did I learn recently about X?" → filter by `created` timestamp
+- "What knowledge superseded previous understanding?" → follow `supersedes` edges
+- "What did I learn in the same session?" → follow `co-occurred` edges
+
+**Causal layer** (optional):
+- "What caused this failure?" → follow `caused-by` chain backward
+- "What could break if I change X?" → follow `led-to` / `broke` edges forward
+- "What enabled this to work?" → follow `enabled` edges
+
+**Entity layer** (optional):
+- "What does Prisma interact with?" → `entity.neighbors('prisma')`
+- "What are the components of this system?" → follow `part-of` edges
+- "What tools does this project use?" → filter by `uses` edges
+
+### 5.5 Storage Layout
+
+Each layer is stored in its own JSON file for independent loading and git-friendly diffs:
+
+```
+.knowledge/
+├── nodes.json                     # Shared node registry
+├── layers/
+│   ├── semantic.json              # Semantic relationships (always present)
+│   ├── temporal.json              # Temporal relationships (if enabled)
+│   ├── causal.json                # Causal chains (if enabled)
+│   └── entity.json                # Entity relationships (if enabled)
+├── manifest.json                  # Note registry with quick-lookup metadata
+└── domain-index.json              # Domain → note ID mapping
+```
+
+For large knowledge bases, layers can be further split by domain:
+
+```
+.knowledge/layers/
+├── semantic.json                  # Small: keep flat
+├── semantic-database.json         # Large: split by domain
+├── semantic-typescript.json
+└── semantic-cross-domain.json     # Cross-domain semantic edges
+```
+
+### 5.6 Configuration
+
+```typescript
+interface GraphConfig {
+  /** Which graph layers to enable */
+  enabledLayers: GraphLayerName[];     // default: ['semantic']
+
+  /** Whether to auto-infer temporal edges from timestamps */
+  inferTemporalEdges: boolean;         // default: true (when temporal enabled)
+
+  /** Whether to auto-infer causal edges from failure→recovery patterns */
+  inferCausalEdges: boolean;           // default: true (when causal enabled)
+
+  /** Whether to auto-infer entity edges from shared entity tags */
+  inferEntityEdges: boolean;           // default: true (when entity enabled)
+
+  /** Split layer files by domain when node count exceeds this */
+  domainSplitThreshold: number;        // default: 500
+
+  /** Promote to SQLite when total edge count exceeds this */
+  sqlitePromotionThreshold: number;    // default: 10000
+}
+```
+
+## 6. Knowledge Extraction Pipeline
+
+Runs parallel to the existing PlaybookExtractor within the LearningPipeline.
+
+### 6.1 Extraction Flow
+
+```
+Trajectory
+    │
+    ▼
+TrajectoryAnalyzer (existing)
+    │
+    ├──▶ PlaybookExtractor (existing)
+    │         │
+    │         ▼
+    │    PlaybookLibrary
+    │
+    └──▶ KnowledgeExtractor (NEW)
+              │
+              ▼
+         KnowledgeBank
+              │
+              ├── Create new observations
+              ├── Update existing entity notes
+              ├── Detect contradictions
+              └── Update graph overlay
+```
+
+### 6.2 What Gets Extracted
+
+From a trajectory's steps and outcome, the extractor identifies:
+
+| Signal | Source | Example |
+|---|---|---|
+| **Domain facts** | Step observations, error messages | "Prisma requires push before migrate" |
+| **Version-specific behavior** | Error messages, configs | "Vitest 2.0 changed config format" |
+| **Causal chains** | Failure → recovery sequences | "Upgrading TS 5.4 broke enum const exports" |
+| **Tool/library behavior** | Tool call results | "React 19 compiler eliminates need for useMemo" |
+| **Environment constraints** | Configuration observations | "Node 22 required for sqlite native module" |
+| **Negative knowledge** | Failure modes | "Library X does NOT support feature Y" |
+
+### 6.3 Extraction Strategies
+
+**Heuristic extraction** (no LLM required):
+- Error message patterns → observations about tool behavior
+- Configuration file changes → facts about tool requirements
+- Version strings in errors → version-specific knowledge
+- Repeated patterns across trajectories → reinforcement of existing knowledge
+
+**LLM-assisted extraction** (via workspace template):
+- Analyze trajectory narrative for implicit factual statements
+- Identify causal relationships between steps
+- Generate entity summaries from accumulated observations
+- Detect contradictions with existing knowledge
+
+### 6.4 KnowledgeExtractor Interface
+
+```typescript
+interface ExtractedKnowledge {
+  /** New observations to create */
+  observations: KnowledgeNote[];
+
+  /** Updates to existing entity notes (append sections) */
+  entityUpdates: EntityUpdate[];
+
+  /** Contradictions detected with existing knowledge */
+  contradictions: Contradiction[];
+
+  /** New links to add to the graph */
+  links: NewLink[];
+
+  /** Cross-references to playbooks */
+  playbookLinks: PlaybookLink[];
+}
+
+interface EntityUpdate {
+  /** Entity note ID to update */
+  entityId: string;
+  /** Section to append */
+  section: string;
+  /** Evidence source */
+  trajectoryId: string;
+}
+
+interface Contradiction {
+  /** Existing note that is contradicted */
+  existingNoteId: string;
+  /** New observation that contradicts it */
+  newObservation: KnowledgeNote;
+  /** How they conflict */
+  conflictDescription: string;
+  /** Recommendation */
+  resolution: 'supersede' | 'coexist' | 'review';
+}
+
+interface PlaybookLink {
+  /** Knowledge note ID */
+  noteId: string;
+  /** Playbook ID */
+  playbookId: string;
+  /** Relationship direction */
+  relation: 'supports' | 'contradicts' | 'contextualizes';
+}
+```
+
+### 6.5 Integration with LearningPipeline
+
+> **Implementation note**: In practice, knowledge extraction is **decoupled** from `LearningPipeline.processTrajectory()`. Instead of auto-wiring extraction into the pipeline, callers invoke `KnowledgeBank.extractFromTrajectory()` directly. This keeps the pipeline's contract unchanged and gives callers explicit control over when extraction runs. The original design below shows the auto-wired approach for reference.
+
+```typescript
+// Option A (implemented): Direct invocation by caller
+const knowledge = await knowledgeBank.extractFromTrajectory(trajectory, analysis, taskRunner);
+
+// Option B (original design, not implemented): Auto-wired in pipeline
+// In LearningPipeline.processTrajectory():
+async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+  await this.memory.storeTrajectory(trajectory);
+
+  const analysis = await this.analyzer.analyze(trajectory);
+
+  // Existing: accumulate for batch playbook extraction
+  this.accumulated.push(trajectory);
+  this.accumulatedAnalyses.push(analysis);
+
+  // NEW: extract knowledge (can run per-trajectory, not just batch)
+  if (this.knowledgeExtractor) {
+    const knowledge = await this.knowledgeExtractor.extract(
+      trajectory,
+      analysis,
+      this.knowledgeBank
+    );
+    await this.knowledgeBank.applyExtraction(knowledge);
+  }
+
+  return { /* ... */ };
+}
+```
+
+**Key difference from playbook extraction**: Knowledge extraction can run on every trajectory (not just batches), because individual facts are valuable. Playbook extraction needs pattern frequency across multiple trajectories.
+
+## 7. Knowledge Evolution
+
+Parallel to PlaybookEvolution but adapted for factual knowledge.
+
+### 7.1 Lifecycle
+
+```
+             ┌──────────────────────────────────────┐
+             │                                      │
+             ▼                                      │
+  ┌─────────────────┐                               │
+  │   Observation    │  confidence: 0.3              │
+  │   (extracted)    │  single trajectory source     │
+  └────────┬────────┘                               │
+           │                                        │
+           │ reinforced by more trajectories         │
+           ▼                                        │
+  ┌─────────────────┐                               │
+  │   Observation    │  confidence: 0.5-0.8          │
+  │   (validated)    │  multiple trajectory sources  │
+  └────────┬────────┘                               │
+           │                                        │
+           │ consolidated into entity note           │
+           ▼                                        │
+  ┌─────────────────┐                               │
+  │   Entity Note    │  accumulates observations     │
+  │   (living doc)   │  grows over time              │
+  └────────┬────────┘                               │
+           │                                        │
+           │ domain summary regenerated              │
+           ▼                                        │
+  ┌─────────────────┐                               │
+  │ Domain Summary   │  high-level orientation       │
+  │ (generated)      │  periodically refreshed       │
+  └─────────────────┘                               │
+                                                    │
+  ┌─────────────────┐                               │
+  │  Contradiction   │  new evidence conflicts  ─────┘
+  │  (detected)      │  → supersede or coexist
+  └─────────────────┘
+```
+
+### 7.2 Evolution Operations
+
+**Reinforcement** — Same fact observed again in a different trajectory:
+- Increment confidence (EMA: `newConf = 0.9 * oldConf + 0.1 * 1.0`)
+- Add trajectory ID to sources
+- Update `updated` timestamp
+
+**Contradiction** — New observation conflicts with existing:
+- Create new observation with `supersedes` pointing to old note
+- Lower confidence of old note
+- Add `contradicts` edge in graph
+- If resolution is clear: mark old note superseded
+- If ambiguous: flag for review (both may be context-dependent)
+
+**Consolidation** — Multiple observations about same entity:
+- Merge observation content into entity note as new sections
+- Observations are retained (atomic source of truth) but entity note provides the summary
+- Add `generalizes` links from entity to observations
+
+**Staleness/Decay** — Knowledge not validated in a configurable period:
+- Gradually decrease confidence
+- Mark with `stale` tag after threshold
+- Don't delete — stale knowledge may still be valid, just unconfirmed
+
+**Agent-authored updates** — Agent directly edits a knowledge file:
+- Detect via file watcher or inbox processing
+- Attempt to parse frontmatter; if missing, treat as inbox item for defragmentation
+- Agent-authored notes start at configurable confidence (default: 0.5)
+
+### 7.3 Confidence Model
+
+```typescript
+interface ConfidenceConfig {
+  /** Initial confidence for extracted observations */
+  extractedInitial: number;       // default: 0.3
+
+  /** Initial confidence for agent-authored notes */
+  agentAuthoredInitial: number;   // default: 0.5
+
+  /** EMA alpha for reinforcement */
+  reinforcementAlpha: number;     // default: 0.1
+
+  /** Confidence reduction on contradiction */
+  contradictionPenalty: number;   // default: 0.3
+
+  /** Daily confidence decay rate for unvalidated knowledge */
+  dailyDecayRate: number;         // default: 0.001
+
+  /** Confidence below which to mark as stale */
+  staleThreshold: number;         // default: 0.2
+
+  /** Days without validation before decay begins */
+  decayGracePeriodDays: number;   // default: 90
+}
+```
+
+## 8. Defragmentation Process
+
+The "index/defrag" process that cognitive-core runs periodically to maintain knowledge organization. This is the key differentiator from raw minimem usage.
+
+### 8.1 What Defragmentation Does
+
+```
+1. INBOX PROCESSING
+   - Read raw notes from inbox/
+   - Extract structured frontmatter (or generate it)
+   - Classify into observation/entity/domain-summary
+   - Move to appropriate directory
+   - Add to graph
+
+2. CONSOLIDATION
+   - Find observations that cluster around the same entity
+   - Merge into entity notes (append sections, update summary)
+   - Add generalizes/specializes links
+
+3. CONTRADICTION DETECTION
+   - Compare new observations against existing knowledge
+   - Flag contradictions for review or auto-resolve
+
+4. GRAPH REBUILD
+   - Scan all frontmatter for link declarations
+   - Rebuild graph.json from source of truth
+   - Compute inferred links (co-occurrence, domain proximity)
+
+5. DOMAIN SUMMARY REGENERATION
+   - For each domain with significant changes since last regen
+   - Collect entity notes + observations in that domain
+   - Generate/update domain summary
+
+6. STALENESS SWEEP
+   - Apply confidence decay to knowledge not validated recently
+   - Tag stale items
+   - Optionally archive (move to archive/ subdirectory)
+
+7. MANIFEST UPDATE
+   - Rebuild manifest.json with note registry
+   - Update domain-index.json
+```
+
+### 8.2 Defragmentation Configuration
+
+```typescript
+interface DefragConfig {
+  /** How often to run defrag (milliseconds) */
+  interval: number;                    // default: 3600000 (1 hour)
+
+  /** Minimum inbox items before triggering defrag */
+  minInboxItems: number;              // default: 5
+
+  /** Whether to auto-consolidate observations into entities */
+  autoConsolidate: boolean;           // default: true
+
+  /** Minimum observations about an entity before consolidation */
+  consolidationThreshold: number;     // default: 3
+
+  /** Whether to auto-regenerate domain summaries */
+  autoRegenerateSummaries: boolean;   // default: true
+
+  /** Use LLM for summary generation (vs heuristic concatenation) */
+  llmSummaryGeneration: boolean;      // default: false
+
+  /** Whether to auto-resolve simple contradictions */
+  autoResolveContradictions: boolean; // default: false
+}
+```
+
+### 8.3 Heuristic vs Agentic Defragmentation
+
+Like the existing playbook extraction, defrag has two modes:
+
+**Heuristic** (no LLM):
+- Parse frontmatter, rebuild indexes
+- Detect exact/near-duplicate observations
+- Consolidate by entity name matching
+- Simple contradiction detection (same entity + conflicting statements)
+
+**Agentic** (via workspace template):
+- Semantic similarity for consolidation
+- Natural language contradiction detection
+- Generated domain summaries
+- Inferred relationships between observations
+
+## 9. Retrieval & Surfacing
+
+### 9.1 Retrieval Modes
+
+| Mode | How | Returns | Use Case |
+|---|---|---|---|
+| **File browse** | `ls`, `cat` on filesystem | Raw markdown | Agent exploring knowledge |
+| **Semantic search** | minimem hybrid search | Ranked chunks | "What do I know about X?" |
+| **Graph traversal** | Walk edges from node | Connected notes | "What's related to X?" |
+| **Domain query** | Read domain summary + index | Structured overview | "Brief me on database knowledge" |
+| **Cross-system** | Follow graph edges to playbooks | Knowledge + procedures | "Facts relevant to this playbook" |
+
+### 9.2 Independent Surfacing (Decoupled from Playbooks)
+
+Knowledge surfacing operates **independently** from playbook/skill surfacing. They are separate systems with separate retrieval paths. In practice, agents receive traced, versioned snapshots of skills, playbooks, and knowledge — the input data is colocated at the point of analysis regardless of how it was surfaced.
+
+This means:
+- `SkillLibrary` continues to surface playbooks as it does today (unchanged)
+- `KnowledgeBank` has its own surfacing path with its own retrieval logic
+- Both produce independent context sections that the agent receives
+- The learning pipeline sees both together when analyzing trajectories (colocated for analysis)
+- No coupling between playbook selection and knowledge selection
+
+```typescript
+// Knowledge surfacing is its own independent path:
+class KnowledgeBank {
+  /**
+   * Surface relevant knowledge for a task.
+   * Independent from playbook surfacing — does not reference SkillLibrary.
+   */
+  async getRelevantKnowledge(task: Task, options?: {
+    maxNotes?: number;
+    maxTokens?: number;
+    layers?: GraphLayerName[];   // which graph layers to traverse
+  }): Promise<KnowledgeMatch[]>;
+}
+
+// Agent context assembly happens at a higher level (Atlas or AgentManager):
+// Both systems contribute independently to the agent's context.
+const skillContext = skillLibrary.formatForSystemPrompt(skills);
+const knowledgeContext = knowledgeBank.formatKnowledgeForPrompt(knowledge);
+// Agent receives both as separate sections
+```
+
+**Knowledge surfacing tiers** (parallel to, but independent from, skill tiers):
+
+| Tier | Criteria | Injection |
+|---|---|---|
+| **Domain knowledge** | Task domain matches note domain | Include domain summary |
+| **Entity knowledge** | Task mentions specific entity | Include entity note |
+| **Contextual** | Semantic match to task description | Include top-N observations |
+
+**Traceability:** When an agent executes a task, the trajectory metadata records which knowledge notes were surfaced (by ID and version timestamp), alongside which playbooks were surfaced. The learning pipeline can then analyze effectiveness of both independently or correlate them during trajectory analysis.
+
+### 9.3 Formatting for Agent Consumption
+
+```typescript
+formatKnowledgeForPrompt(notes: KnowledgeNote[]): string {
+  // Returns markdown section:
+  // ## Relevant Knowledge
+  //
+  // ### About Prisma (85% confidence)
+  // - Requires schema push before migrate in dev (Prisma 5.x+, PostgreSQL)
+  // - Migration drift detection triggers on schema divergence
+  //
+  // ### About TypeScript Enums
+  // - TS 5.4 changed const enum export behavior (caution when upgrading)
+}
+```
+
+## 10. KnowledgeBank Interface
+
+The main module that ties everything together.
+
+```typescript
+class KnowledgeBank {
+  /** The multi-graph manager (pluggable layers) */
+  public readonly graph: KnowledgeGraphManager;
+
+  constructor(
+    memoryDir: string,        // Root directory (minimem-compatible)
+    config?: KnowledgeBankConfig
+  );
+
+  // === LIFECYCLE ===
+  async init(): Promise<void>;
+  async close(): Promise<void>;
+
+  // === WRITE ===
+  /** Create a new knowledge note */
+  async addObservation(note: KnowledgeNote): Promise<string>;
+  /** Update an existing entity note */
+  async updateEntity(entityId: string, update: EntityUpdate): Promise<void>;
+  /** Process raw agent-authored content from inbox */
+  async processInbox(): Promise<InboxResult>;
+
+  // === READ ===
+  /** Get a specific note by ID */
+  async getNote(id: string): Promise<KnowledgeNote | null>;
+  /** Get entity note for a named entity */
+  async getEntity(entityName: string): Promise<KnowledgeNote | null>;
+  /** Get domain summary */
+  async getDomainSummary(domain: string): Promise<KnowledgeNote | null>;
+  /** List all known entities */
+  async listEntities(): Promise<string[]>;
+  /** List all known domains */
+  async listDomains(): Promise<string[]>;
+
+  // === SEARCH ===
+  /** Semantic search across all knowledge */
+  async search(query: string, options?: SearchOptions): Promise<KnowledgeMatch[]>;
+  /**
+   * Get knowledge relevant to a task.
+   * Independent from playbook surfacing — does not reference SkillLibrary.
+   */
+  async getRelevantKnowledge(task: Task, options?: {
+    maxNotes?: number;
+    maxTokens?: number;
+    layers?: GraphLayerName[];
+  }): Promise<KnowledgeMatch[]>;
+
+  // === GRAPH (delegates to KnowledgeGraphManager) ===
+  /** Get related notes via multi-layer graph traversal */
+  async getRelated(noteId: string, options?: {
+    depth?: number;
+    layers?: GraphLayerName[];
+    minWeight?: number;
+  }): Promise<KnowledgeMatch[]>;
+  /** Get cross-system links (to playbooks) */
+  async getPlaybookLinks(noteId: string): Promise<PlaybookLink[]>;
+  /** Get knowledge linked to a specific playbook */
+  async getKnowledgeForPlaybook(playbookId: string): Promise<KnowledgeMatch[]>;
+  /** Get causal chain for a note (requires causal layer) */
+  async getCausalChain(noteId: string, direction: 'causes' | 'effects'): Promise<KnowledgeMatch[]>;
+  /** Get temporal neighbors (requires temporal layer) */
+  async getTemporalNeighbors(noteId: string, window?: { before?: number; after?: number }): Promise<KnowledgeMatch[]>;
+
+  // === EVOLUTION ===
+  /** Reinforce a note with additional evidence */
+  async reinforce(noteId: string, trajectoryId: string): Promise<void>;
+  /** Record a contradiction */
+  async recordContradiction(contradiction: Contradiction): Promise<void>;
+  /** Apply confidence decay to stale knowledge */
+  async applyDecay(): Promise<DecayResult>;
+
+  // === EXTRACTION ===
+  /** Apply extraction results from KnowledgeExtractor */
+  async applyExtraction(extraction: ExtractedKnowledge): Promise<void>;
+
+  // === DEFRAGMENTATION ===
+  /** Run full defragmentation cycle */
+  async defragment(): Promise<DefragResult>;
+
+  // === SURFACING (independent from SkillLibrary) ===
+  /** Format knowledge notes for agent context injection */
+  formatKnowledgeForPrompt(notes: KnowledgeMatch[], options?: {
+    maxTokens?: number;
+    includeEvidence?: boolean;
+    includeLinks?: boolean;
+  }): string;
+
+  // === STATS ===
+  async getStats(): Promise<KnowledgeStats>;
+}
+
+interface KnowledgeStats {
+  observationCount: number;
+  entityCount: number;
+  domainCount: number;
+  inboxCount: number;
+  graph: {
+    nodeCount: number;
+    edgeCountByLayer: Record<GraphLayerName, number>;
+    enabledLayers: GraphLayerName[];
+  };
+  avgConfidence: number;
+  staleCount: number;
+  domainBreakdown: Record<string, number>;
+}
+```
+
+## 11. Configuration
+
+Addition to `AtlasConfig`:
+
+```typescript
+// In AtlasConfigSchema:
+knowledgeBank: KnowledgeBankConfigSchema.default({})
+
+// KnowledgeBankConfigSchema:
+interface KnowledgeBankConfig {
+  /** Enable knowledge bank */
+  enabled: boolean;                    // default: false
+
+  /** Root directory for knowledge files */
+  memoryDir: string;                   // default: '{baseDir}/memory'
+
+  /** Extraction config */
+  extraction: {
+    /** Enable automatic knowledge extraction from trajectories */
+    enabled: boolean;                  // default: true
+    /** Use LLM-assisted extraction (vs heuristic only) */
+    useLlmExtraction: boolean;        // default: false
+    /** Minimum trajectory attribution score for extraction */
+    minAttributionScore: number;      // default: 0.3
+  };
+
+  /** Defragmentation config */
+  defrag: DefragConfig;
+
+  /** Confidence model config */
+  confidence: ConfidenceConfig;
+
+  /** Graph overlay config */
+  graph: GraphConfig;
+
+  /** Surfacing config (independent from SkillLibrary) */
+  surfacing: {
+    /** Include domain summaries in task context */
+    includeDomainSummaries: boolean;  // default: true
+    /** Include entity notes in task context */
+    includeEntityNotes: boolean;      // default: true
+    /** Maximum knowledge notes to surface per task */
+    maxNotesPerTask: number;          // default: 5
+    /** Maximum tokens for knowledge context */
+    maxTokensForKnowledge: number;    // default: 1500
+    /** Include evidence citations in surfaced notes */
+    includeEvidence: boolean;         // default: false
+    /** Include graph links in surfaced notes */
+    includeLinks: boolean;            // default: false
+  };
+
+  /** Whether to manage minimem-specific features (sync, versioning) */
+  minimemAware: boolean;              // default: false
+}
+```
+
+## 12. Implementation Phases
+
+### Cross-Cutting Concerns
+
+Before diving into phases, these concerns apply throughout all implementation:
+
+**Frontmatter compatibility.** minimem's built-in parser (`parseFrontmatter` in `minimem/src/session.ts`) only supports 2-level nesting and inline `[a, b]` arrays — it cannot parse our `links` array-of-objects or deeply nested `source` structures. We will implement our own full-fidelity parser in cognitive-core (`src/utils/frontmatter.ts`) that handles the complete `KnowledgeNoteFrontmatter` schema, while keeping the simple top-level fields (`created`, `updated`, `tags`) compatible so minimem can still partially read our files.
+
+**Export pattern.** Every new module follows the existing convention: a barrel `index.ts` in its directory, re-exported up through `src/memory/index.ts` → `src/index.ts`. New types go in `src/types/`, re-exported from `src/types/index.ts`.
+
+**Config pattern.** New config schemas use Zod with `.default({})` at each level, nested under `AtlasConfig`. The `createDefaultConfig()` helper in `src/types/config.ts` merges partial user config over defaults.
+
+**Test pattern.** Tests live in `tests/` mirroring `src/` structure. Each phase has its own test file(s). Tests use the filesystem directly (tmp dirs) — no mocking of the file layer, since filesystem-as-primary-index is a core invariant.
+
+**Feature flag.** The entire knowledge bank is behind `knowledgeBank.enabled: false` by default. All Atlas/MemorySystem integration is guarded by this flag so existing behavior is unchanged unless opted in.
+
+---
+
+### Phase 1: Foundation (Core Types + Filesystem + Multi-Graph)
+
+**Goal**: Standalone KnowledgeBank that can create, read, update, and delete knowledge notes on the filesystem, with a multi-layer graph overlay. No integration with the learning pipeline or Atlas yet — this phase is a self-contained module with its own tests.
+
+#### Step 1.1 — Types (`src/types/knowledge.ts`)
+
+New file. Defines the core data model using Zod schemas (matching the existing pattern in `src/types/`).
+
+**What to define:**
+- `KnowledgeNoteFrontmatter` — the full frontmatter schema from Section 3.3 (id, type, domain, entities, tags, confidence, source, links, created, updated, supersedes)
+- `KnowledgeNote` — frontmatter + body (markdown content) + filePath (resolved at load time)
+- `NoteType` — `'observation' | 'entity' | 'domain-summary'`
+- `LinkRelation` — the union type from Section 3.3
+- `KnowledgeMatch` — a note + relevance score (for search results)
+- `EntityUpdate`, `Contradiction`, `PlaybookLink` — from Section 6.4
+- `ExtractedKnowledge` — from Section 6.4
+- Factory functions: `createKnowledgeNote()`, `createObservation()`, `createEntityNote()`
+- `InboxResult`, `DefragResult`, `DecayResult` — result types for lifecycle operations
+
+**Key decisions:**
+- IDs are kebab-case, prefixed `k-` for observations, entity name for entities, domain name for domain summaries
+- Zod schemas validate frontmatter on read; malformed files get logged and skipped (not crash)
+- `KnowledgeNote` carries its `filePath` so the graph can reference it, but the path is not in frontmatter (it's derived from type + name)
+
+#### Step 1.2 — Graph types (`src/types/knowledge-graph.ts`)
+
+New file. Types for the multi-graph overlay from Section 5.
+
+**What to define:**
+- `GraphNode`, `GraphEdge`, `GraphLayer`, `GraphLayerName`
+- `KnowledgeMultiGraph` — the top-level JSON structure
+- `GraphLayerOperations` — the per-layer interface (getEdges, neighbors, pathBetween, addEdge, removeEdge, rebuild)
+- `KnowledgeGraphManager` — the aggregate interface (neighbors across layers, filterNodes, crossSystemLinks, subgraph, rebuildAll)
+- `GraphConfig` — from Section 5.6
+
+#### Step 1.3 — Config integration (`src/types/config.ts`)
+
+Modify existing file. Add `KnowledgeBankConfig` (Section 11) as a new Zod schema nested under `AtlasConfigSchema`.
+
+**What to add:**
+- `KnowledgeBankConfigSchema` with all sub-schemas (extraction, defrag, confidence, graph, surfacing)
+- Default: `enabled: false`, so no behavior change for existing users
+- Add `knowledgeBank: KnowledgeBankConfigSchema.default({})` to `AtlasConfigSchema`
+
+**What to re-export:**
+- Add `KnowledgeBankConfig` type export to `src/types/index.ts`
+
+#### Step 1.4 — Frontmatter parser (`src/utils/frontmatter.ts`)
+
+New file. Full-fidelity YAML frontmatter parser/serializer for knowledge notes.
+
+**Why not reuse minimem's parser:** minimem's `parseSimpleYaml` only handles 2-level nesting and inline arrays. Our frontmatter has `links: [{ target: ..., relation: ..., layer: ... }]` and `source: { origin: ..., trajectories: [...] }`. We need to parse these correctly.
+
+**What to implement:**
+- `parseKnowledgeFrontmatter(content: string): { frontmatter: KnowledgeNoteFrontmatter | null; body: string }` — parse `---` delimited YAML block into typed frontmatter. Uses a lightweight approach: regex for `---` delimiters, then either a small YAML parser (consider `yaml` npm package which is already a common dependency) or a hand-rolled parser that handles 3 levels + `- item` list syntax.
+- `serializeKnowledgeFrontmatter(frontmatter: KnowledgeNoteFrontmatter): string` — produce `---\n...\n---\n` block. Keep simple fields (`created`, `updated`, `tags`) in the same format minimem uses so its parser can read those fields.
+- `serializeKnowledgeNote(note: KnowledgeNote): string` — frontmatter + body combined.
+
+**Decision: YAML library or hand-rolled?**
+- If `yaml` (npm) is already in the dependency tree or acceptable to add: use it. It's 60KB, zero dependencies, well-maintained.
+- If zero-dependency is a hard constraint: hand-roll a parser that handles the specific shapes we need (nested objects, arrays of objects, arrays of strings). Not a general YAML parser — just enough for our schema.
+- **Recommendation:** Use the `yaml` package. The frontmatter schema will evolve and a hand-rolled parser will be a maintenance burden.
+
+#### Step 1.5 — KnowledgeBank class (`src/memory/knowledge-bank.ts`)
+
+New file. The main class from Section 10.
+
+**Phase 1 scope** (subset of the full interface):
+- Constructor: takes `memoryDir` path and `KnowledgeBankConfig`
+- `init()` — create directory structure (`knowledge/observations/`, `knowledge/entities/`, `knowledge/domains/`, `inbox/`, `.knowledge/layers/`) if not exists. Load graph from disk if present.
+- `close()` — flush graph to disk.
+- **Write ops:** `addObservation(note)`, `updateEntity(entityId, update)` — write markdown files to correct directory, update graph overlay in memory.
+- **Read ops:** `getNote(id)`, `getEntity(entityName)`, `getDomainSummary(domain)`, `listEntities()`, `listDomains()` — scan filesystem, parse frontmatter, return typed `KnowledgeNote`.
+- **Graph delegation:** `getRelated(noteId, options)` — delegates to `KnowledgeGraphManager`.
+- **Stats:** `getStats()` — count files in each directory, graph stats.
+
+**Internal helpers:**
+- `private noteIdToPath(id: string, type: NoteType): string` — resolve note ID to filesystem path based on type
+- `private scanDirectory(dir: string): Promise<KnowledgeNote[]>` — read all `.md` files, parse frontmatter
+- `private writeNote(note: KnowledgeNote): Promise<void>` — serialize and write to disk
+- `private buildManifest(): Promise<void>` — scan all notes, write `.knowledge/manifest.json`
+
+**Not in Phase 1:** `search()`, `getRelevantKnowledge()`, `processInbox()`, `defragment()`, `applyExtraction()`, `reinforce()`, `recordContradiction()`, `applyDecay()`, `formatKnowledgeForPrompt()`. These are stubs that throw "not implemented" or return empty results.
+
+#### Step 1.6 — KnowledgeGraphManager (`src/memory/knowledge-graph.ts`)
+
+New file. Implements `KnowledgeGraphManager` interface.
+
+**What to implement:**
+- Constructor: takes `GraphConfig`, initializes enabled layers
+- `getLayer(name)` — return a layer by name (or null if disabled)
+- `neighbors(nodeId, options)` — BFS across all enabled layers (or subset specified in options), union results, deduplicate by node ID, sort by edge weight
+- `filterNodes(filter)` — linear scan of node registry with domain/entity/tag/type/confidence predicates
+- `crossSystemLinks(nodeId)` — filter edges where `crossSystem` is set
+- `rebuildAll(notes)` — rebuild shared node set from notes, then delegate `rebuild()` to each enabled layer
+- **Persistence:** `loadFromDisk(dir)`, `saveToDisk(dir)` — read/write `nodes.json` + `layers/*.json`
+
+**Not in Phase 1:** `pathBetween()` (BFS shortest path — implement but can be basic), `subgraph()` (stub).
+
+#### Step 1.7 — Semantic graph layer (`src/memory/graph-layers/semantic.ts`)
+
+New file. Implements `GraphLayerOperations` for the semantic layer.
+
+**What to implement:**
+- In-memory adjacency list (`Map<string, GraphEdge[]>`) for fast lookups
+- `getEdges(nodeId, direction)` — O(1) lookup
+- `neighbors(nodeId, depth)` — BFS with depth limit
+- `pathBetween(from, to)` — BFS shortest path
+- `addEdge(edge)` / `removeEdge(from, to, relation)` — mutate adjacency list
+- `rebuild(notes)` — iterate all notes' `links` where relation is a semantic type, build adjacency list
+
+#### Step 1.8 — Layer stubs (`src/memory/graph-layers/temporal.ts`, `causal.ts`, `entity.ts`)
+
+New files. Minimal implementations that share the same adjacency-list structure as semantic. Each only differs in which `LinkRelation` values they accept in `rebuild()`. Disabled by default in `GraphConfig.enabledLayers`.
+
+The implementation is identical to semantic — extract a shared `BaseGraphLayer` class that the four layers extend, each overriding only the set of valid relation types for their layer.
+
+#### Step 1.9 — Wire into MemorySystem (`src/memory/system.ts`)
+
+Modify existing file.
+
+**What to add:**
+- `public readonly knowledgeBank: KnowledgeBank | null` — initialized when `config.knowledgeBank.enabled` is true
+- In `init()`: `if (this.knowledgeBank) await this.knowledgeBank.init()`
+- In `close()`: `if (this.knowledgeBank) await this.knowledgeBank.close()`
+- In `getStats()`: add `knowledgeBank` stats if enabled
+
+**What NOT to change:** Everything else in MemorySystem stays the same. KnowledgeBank is an additive, optional subsystem.
+
+#### Step 1.10 — Wire into Atlas (`src/atlas.ts`)
+
+Modify existing file.
+
+**What to add:**
+- In constructor: no change (MemorySystem handles initialization)
+- In `init()`: after memory init, if `this.memory.knowledgeBank`, store reference for later use
+- `getKnowledgeBank(): KnowledgeBank | null` accessor
+- In `getStats()`: add `knowledgeBank` section to `AtlasStats` if enabled
+- In `close()`: no change (MemorySystem handles cleanup)
+
+**What NOT to change:** `solve()`, `processTrajectory()`, learning pipeline integration — all Phase 2+.
+
+#### Step 1.11 — Exports
+
+- New barrel: `src/memory/graph-layers/index.ts` — exports layer classes
+- Update `src/memory/index.ts` — add KnowledgeBank exports
+- Update `src/types/index.ts` — add knowledge types + graph types
+- Update `src/index.ts` — add KnowledgeBank + types to top-level exports
+
+#### Step 1.12 — Tests
+
+New test files:
+- `tests/memory/knowledge-bank.test.ts` — CRUD operations, directory structure creation, note serialization round-trip, ID-to-path resolution, stats
+- `tests/memory/knowledge-graph.test.ts` — graph manager lifecycle (build from notes, query neighbors, filter nodes, cross-layer queries, persistence round-trip)
+- `tests/memory/graph-layers/semantic.test.ts` — semantic layer edge operations, BFS, rebuild from notes
+- `tests/utils/frontmatter.test.ts` — parse/serialize round-trip for all frontmatter shapes, compatibility with minimem's simple fields, malformed input handling
+
+**Phase 1 deliverable:** A standalone `KnowledgeBank` that can be instantiated, writes structured markdown files to disk, maintains a graph overlay, and passes all CRUD + graph tests. Can be used independently of the learning pipeline.
+
+---
+
+### Phase 2: Extraction Pipeline
+
+**Goal**: Automatically extract knowledge from trajectories, running parallel to the existing PlaybookExtractor within the LearningPipeline.
+
+**Depends on:** Phase 1 complete (KnowledgeBank with working CRUD + graph).
+
+#### Step 2.1 — KnowledgeExtractor (`src/learning/knowledge-extractor.ts`)
+
+New file. The heuristic extraction engine.
+
+**What to implement:**
+
+```typescript
+class KnowledgeExtractor {
+  constructor(config?: KnowledgeExtractionConfig);
+
+  /**
+   * Extract knowledge from a single trajectory + its analysis.
+   * Returns observations, entity updates, contradictions, and links.
+   */
+  async extract(
+    trajectory: Trajectory,
+    analysis: AnalysisResult,
+    knowledgeBank: KnowledgeBank
+  ): Promise<ExtractedKnowledge>;
+}
+```
+
+**Heuristic extraction strategies** (no LLM required):
+
+1. **Error pattern extraction** — Scan `trajectory.steps` for steps with `type: 'error'` or failed outcomes. Extract tool/library name from error message + what fixed it → observation note. Pattern: `"{tool} fails when {condition}; fix: {resolution}"`.
+
+2. **Configuration facts** — Detect steps that read/write config files (package.json, tsconfig.json, etc.). Extract version constraints and settings → observation notes. Pattern: `"{tool} {version} requires {setting}"`.
+
+3. **Causal chain extraction** — Find failure→recovery sequences in steps (consecutive failure then success involving the same tool). Extract the causal relationship → observation + causal graph edge.
+
+4. **Entity identification** — Extract entity names from trajectory step descriptions and tool calls. Group extracted observations by entity. If an entity note exists, produce an `EntityUpdate`; if not, record the entity name for future consolidation.
+
+5. **Contradiction detection** — For each new observation, search existing KnowledgeBank for notes with overlapping entities + domain. Use `textSimilarity()` (from `src/utils/similarity.ts`) to find similar existing notes. If similarity is high but content conflicts (detected by presence of negation words, different version numbers, etc.), produce a `Contradiction`.
+
+6. **Cross-reference detection** — If the trajectory was guided by a playbook (available in trajectory metadata from `SolveResult.injectedPlaybooks`), produce `PlaybookLink` entries connecting new observations to those playbooks.
+
+**Key decision — extraction per-trajectory vs batch:**
+Knowledge extraction runs on **every trajectory** (unlike playbook extraction which batches). Individual facts are valuable immediately. The `extract()` method is called in `processTrajectory()`, not `runBatchLearning()`.
+
+#### Step 2.2 — Integrate into LearningPipeline (`src/learning/pipeline.ts`)
+
+Modify existing file.
+
+**What to change in constructor:**
+- Accept optional `KnowledgeBank` (from `MemorySystem.knowledgeBank`)
+- If provided, create a `KnowledgeExtractor` instance
+
+**What to change in `processTrajectory()`:**
+- After analysis, if `knowledgeExtractor` exists:
+  ```
+  const knowledge = await this.knowledgeExtractor.extract(trajectory, analysis, knowledgeBank);
+  await knowledgeBank.applyExtraction(knowledge);
+  ```
+- Add `knowledgeExtracted: boolean` to `ProcessResult`
+
+**What NOT to change:** Batch learning flow, playbook extraction — those continue as-is.
+
+#### Step 2.3 — `applyExtraction()` on KnowledgeBank (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed method.
+
+**What it does:**
+1. For each `observation` in `ExtractedKnowledge`: call `addObservation()` to write the file
+2. For each `entityUpdate`: read the entity note, append the new section, update `updated` timestamp, write back
+3. For each `contradiction`: call `recordContradiction()` (stub in Phase 1, full implementation in Phase 3)
+4. For each `link`: add edge to the appropriate graph layer
+5. For each `playbookLink`: add cross-system edge to semantic layer with `crossSystem: 'playbook'`
+6. Persist graph to disk
+
+#### Step 2.4 — Workspace template for LLM-assisted extraction (`src/workspace/templates/knowledge-extraction.ts`)
+
+New file. Follows the `AgenticTaskTemplate<Input, Output>` pattern from `trajectory-analysis.ts`.
+
+**Template structure:**
+- `taskType: 'knowledge-extraction'`
+- `assessComplexity(input)`: `'heuristic'` for short trajectories (< 5 steps), `'lightweight'` for medium (5-15 steps), `'standard'` for long/complex
+- `heuristicFallback(input)`: delegates to `KnowledgeExtractor.extract()` (the heuristic engine from Step 2.1)
+- Agent prompt: "Analyze this trajectory and extract factual knowledge. For each fact, produce a structured observation with domain, entities, tags, confidence, and evidence."
+- Output spec: validates against `ExtractedKnowledge` schema
+
+**Integration:** In `LearningPipeline.processTrajectory()`, if `taskRunner` is available and extraction config has `useLlmExtraction: true`, use the template instead of direct heuristic extraction (same pattern as `analyzeWithTemplate`).
+
+#### Step 2.5 — Tests
+
+New test files:
+- `tests/learning/knowledge-extractor.test.ts` — Feed sample trajectories (with errors, config changes, version issues) and verify correct observations, entity updates, and contradictions are extracted. Test each heuristic strategy independently.
+- `tests/learning/pipeline-knowledge.test.ts` — Integration test: process a trajectory through LearningPipeline with KnowledgeBank enabled, verify notes appear on filesystem and graph is updated.
+
+**Phase 2 deliverable:** Processing a trajectory through the LearningPipeline now automatically extracts knowledge observations, writes them to disk, and updates the graph. Heuristic extraction works without an LLM; LLM-assisted extraction is available via workspace template.
+
+---
+
+### Phase 3: Evolution & Defragmentation
+
+**Goal**: Knowledge evolves with reinforcement, contradiction resolution, staleness decay, and periodic defragmentation that consolidates and organizes the knowledge base.
+
+**Depends on:** Phase 2 complete (extraction pipeline producing observations).
+
+#### Step 3.1 — Reinforcement (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed `reinforce()` method.
+
+**What it does:**
+- Look up note by ID
+- Apply EMA confidence update: `newConf = (1 - alpha) * oldConf + alpha * 1.0` (alpha from `ConfidenceConfig.reinforcementAlpha`, default 0.1)
+- Add trajectory ID to `source.trajectories` array
+- Update `updated` timestamp
+- Write note back to disk
+- Update graph node's `confidence` and `updated`
+
+**Called from:** `KnowledgeExtractor.extract()` when a new observation matches an existing one (similarity > threshold), instead of creating a duplicate.
+
+#### Step 3.2 — Contradiction resolution (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed `recordContradiction()` method.
+
+**What it does:**
+- Based on `Contradiction.resolution`:
+  - `'supersede'`: Create new observation with `supersedes` pointing to old note's ID. Lower old note's confidence by `contradictionPenalty`. Add `supersedes` edge in temporal layer + `contradicts` edge in entity layer.
+  - `'coexist'`: Both notes kept. Add `contradicts` edge. Both get a slight confidence reduction (half of penalty) since truth is ambiguous.
+  - `'review'`: Add `contradicts` edge. Tag both notes with `needs-review`. No confidence change — leave for the defrag process or human review.
+
+#### Step 3.3 — Staleness decay (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed `applyDecay()` method.
+
+**What it does:**
+- Scan all observation and entity notes
+- For each note: calculate days since `updated`
+- If days > `decayGracePeriodDays`: apply decay `newConf = oldConf * (1 - dailyDecayRate) ^ (days - gracePeriod)`
+- If confidence drops below `staleThreshold`: add `stale` tag to note
+- Return `DecayResult` with counts (decayed, newly stale, already stale)
+
+**When called:** By defragmentation process (Step 3.5) or explicitly via `KnowledgeBank.applyDecay()`.
+
+#### Step 3.4 — Inbox processing (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed `processInbox()` method.
+
+**What it does:**
+1. Scan `inbox/` directory for `.md` files
+2. For each file:
+   a. Try to parse frontmatter. If valid `KnowledgeNoteFrontmatter`: classify by `type`, move to correct directory (`observations/`, `entities/`, `domains/`), add to graph.
+   b. If no frontmatter or invalid: attempt heuristic classification — extract entities from title/content, assign default frontmatter (type: `observation`, confidence: `agentAuthoredInitial`), generate ID from filename, move to `observations/`.
+3. Return `InboxResult` with counts (processed, failed, moved to each directory)
+
+#### Step 3.5 — Defragmentation orchestrator (`src/memory/knowledge-defrag.ts`)
+
+New file. Implements the 7-step defrag process from Section 8.1.
+
+```typescript
+class KnowledgeDefragmenter {
+  constructor(
+    private knowledgeBank: KnowledgeBank,
+    private config: DefragConfig
+  );
+
+  async defragment(): Promise<DefragResult>;
+}
+```
+
+**Defrag steps (all heuristic in Phase 3):**
+
+1. **Inbox processing** — delegate to `knowledgeBank.processInbox()`
+2. **Consolidation** — find entities with `>= consolidationThreshold` observations. For each: read observations, merge content into entity note (append sections with evidence citations), add `generalizes` links from entity → observations.
+3. **Contradiction detection** — pairwise similarity scan across observations in the same domain. Flag high-similarity + conflicting content pairs. (Reuses the same logic from `KnowledgeExtractor` contradiction detection.)
+4. **Graph rebuild** — `knowledgeBank.graph.rebuildAll(allNotes)` — full rebuild from frontmatter.
+5. **Domain summary regeneration** — for each domain with changes since last regen: collect entity notes + observations, generate a concatenated summary (heuristic: list entities + top observations by confidence). Write to `domains/{domain}.md`.
+6. **Staleness sweep** — `knowledgeBank.applyDecay()`
+7. **Manifest update** — rebuild `.knowledge/manifest.json` (note ID → path mapping) and `.knowledge/domain-index.json` (domain → note IDs)
+
+**`KnowledgeBank.defragment()`** delegates to `KnowledgeDefragmenter.defragment()`.
+
+#### Step 3.6 — Workspace template for agentic defrag (`src/workspace/templates/knowledge-defrag.ts`)
+
+New file. Template for LLM-assisted defragmentation.
+
+**When used:** When `DefragConfig.llmSummaryGeneration` is true, or for consolidation that requires semantic understanding (merging observations into coherent entity notes rather than just concatenating).
+
+**Template scope:**
+- Generate natural-language domain summaries (vs heuristic concatenation)
+- Semantic consolidation — merge related observations into entity notes with proper narrative flow
+- Nuanced contradiction detection — understand context-dependent truths
+
+#### Step 3.7 — Defrag scheduling
+
+**Where:** In `KnowledgeBank.init()`, optionally start a defrag timer:
+- If `defrag.interval > 0`: schedule `setInterval(defragment, interval)`
+- Also expose `defragment()` for manual/on-demand runs
+- In `close()`: clear the timer
+
+Alternatively (simpler): don't auto-schedule. Instead, the `LearningPipeline` triggers defrag after batch learning completes, or Atlas triggers it periodically. This avoids background timers and keeps the control flow explicit.
+
+**Recommendation:** No auto-scheduling in Phase 3. Add a `shouldDefragment(): boolean` check (inbox count > minInboxItems) and let the caller decide when to run it.
+
+#### Step 3.8 — Tests
+
+New test files:
+- `tests/memory/knowledge-evolution.test.ts` — reinforcement (confidence increases correctly), contradiction resolution (supersede/coexist/review paths), staleness decay (grace period, threshold, tagging)
+- `tests/memory/knowledge-defrag.test.ts` — full defrag cycle: seed inbox files → process → verify organization. Consolidation: seed 4 observations about same entity → verify entity note created with merged content. Domain summary: verify regeneration after entity changes. Manifest: verify JSON index accuracy.
+
+**Phase 3 deliverable:** Knowledge base is self-organizing. Inbox notes get classified and filed. Observations consolidate into entity notes. Contradictions are detected and handled. Stale knowledge decays. The filesystem stays clean and well-structured without manual intervention.
+
+---
+
+### Phase 4: Retrieval & Surfacing
+
+**Goal**: Knowledge is surfaced to agents during task execution as an independent context section alongside (but decoupled from) playbook/skill surfacing.
+
+**Depends on:** Phase 1 complete for core read/graph operations. Can be developed in parallel with Phase 2-3 for the surfacing-specific code, but full integration requires Phase 2 (extraction populates the knowledge base).
+
+#### Step 4.1 — Knowledge retrieval (`src/memory/knowledge-bank.ts`)
+
+Implement the previously-stubbed search and retrieval methods.
+
+**`search(query, options)`:**
+- If `EmbeddingManager` is available (from the existing embedding infrastructure in `src/embeddings/`): use vector search over knowledge notes. This requires indexing knowledge notes into the existing `SqliteVectorStore` — add knowledge notes as a new `MemoryItemType` alongside experiences and playbooks.
+- Fallback: `BM25Index` text search (already available in `src/embeddings/bm25.ts`).
+- Filter results by domain, entity, confidence, type if options specify.
+
+**`getRelevantKnowledge(task, options)`:**
+- Independent from `SkillLibrary.getSkillsForAgent()` — does not reference playbooks.
+- Three-tier retrieval (parallel to but independent from skill tiers):
+  1. **Domain match** — if `task.domain` matches a knowledge domain, include the domain summary
+  2. **Entity match** — scan task description for known entity names (from `listEntities()`), include matching entity notes
+  3. **Semantic match** — run `search(task.description)` for top-N contextually relevant observations
+- Deduplicate across tiers (domain summary may reference same entities as tier 2)
+- Respect `maxNotes` and `maxTokens` limits (estimate tokens from content length)
+- Return `KnowledgeMatch[]` sorted by relevance
+
+#### Step 4.2 — Prompt formatting (`src/memory/knowledge-bank.ts`)
+
+Implement `formatKnowledgeForPrompt()`.
+
+**Output format:**
+```markdown
+## Relevant Knowledge
+
+### About {entity} ({confidence}% confidence)
+- {observation summary} ({source info})
+- {observation summary}
+
+### {domain} Overview
+{domain summary content}
+
+### Additional Context
+- {contextual observation}
+```
+
+**Options:**
+- `maxTokens` — truncate to fit budget (drop lowest-confidence notes first)
+- `includeEvidence` — append evidence citations (trajectory IDs, dates)
+- `includeLinks` — append "Related: ..." links
+
+#### Step 4.3 — Wire into Atlas.solve() (`src/atlas.ts`)
+
+Modify `solve()` to surface knowledge alongside skills.
+
+**What to add:**
+```typescript
+// In solve(), after skill surfacing:
+let knowledgeContext = '';
+if (this.memory.knowledgeBank) {
+  const knowledge = await this.memory.knowledgeBank.getRelevantKnowledge(task, {
+    maxNotes: this.config.knowledgeBank.surfacing.maxNotesPerTask,
+    maxTokens: this.config.knowledgeBank.surfacing.maxTokensForKnowledge,
+  });
+  knowledgeContext = this.memory.knowledgeBank.formatKnowledgeForPrompt(knowledge, {
+    includeEvidence: this.config.knowledgeBank.surfacing.includeEvidence,
+    includeLinks: this.config.knowledgeBank.surfacing.includeLinks,
+  });
+}
+
+// Combine skill context + knowledge context for agent
+const systemPromptAdditions = [skillContext, knowledgeContext].filter(Boolean).join('\n\n');
+```
+
+**What to add to SolveResult:**
+- `injectedKnowledge?: KnowledgeMatch[]` — which knowledge notes were surfaced (for traceability)
+
+#### Step 4.4 — Knowledge tracing in trajectories
+
+**What to add to trajectory metadata** (in the `SolveResult` or trajectory's metadata field):
+- List of surfaced knowledge note IDs + their `updated` timestamps at time of surfacing
+- This enables the learning pipeline to assess: "was this knowledge helpful?" by comparing surfaced knowledge to trajectory outcome
+
+This is the knowledge equivalent of `injectedPlaybooks` / `playbookUsage` in the existing flow.
+
+#### Step 4.5 — Multi-layer graph query methods (`src/memory/knowledge-bank.ts`)
+
+Implement the remaining graph delegation methods:
+
+**`getCausalChain(noteId, direction)`:**
+- Requires causal layer enabled
+- Follow `caused-by` edges backward (direction: 'causes') or `led-to`/`broke`/`enabled` forward (direction: 'effects')
+- Return chain as ordered `KnowledgeMatch[]`
+
+**`getTemporalNeighbors(noteId, window)`:**
+- Requires temporal layer enabled
+- Follow `co-occurred`, `observed-before`, `observed-after` edges
+- Optionally filter by time window
+
+**`getKnowledgeForPlaybook(playbookId)`:**
+- Query cross-system edges where `crossSystem === 'playbook'` and target matches playbookId
+- Return all knowledge notes that reference this playbook
+
+#### Step 4.6 — MCP server integration
+
+**Option A (recommended):** Add knowledge tools to the existing `PlaybookMCPServer` (`src/mcp/playbook-server.ts`).
+
+New tools:
+- `knowledge_search` — wraps `knowledgeBank.search()`
+- `knowledge_entity` — wraps `knowledgeBank.getEntity()`
+- `knowledge_domain` — wraps `knowledgeBank.getDomainSummary()`
+- `knowledge_related` — wraps `knowledgeBank.getRelated()`
+
+**Option B:** Separate `KnowledgeMCPServer`. More modular but adds operational complexity (two servers to configure).
+
+**Recommendation:** Option A — extend the existing server. Rename it to `CognitiveCoreMCPServer` if the scope warrants it.
+
+#### Step 4.7 — Tests
+
+New test files:
+- `tests/memory/knowledge-retrieval.test.ts` — search with various query types, relevance ranking, token budget enforcement, tier matching
+- `tests/memory/knowledge-surfacing.test.ts` — formatKnowledgeForPrompt output format, truncation, option variations
+- `tests/atlas-knowledge.test.ts` — integration: Atlas.solve() with knowledge bank enabled, verify knowledge context appears in agent spawn config, verify traceability in SolveResult
+
+**Phase 4 deliverable:** Agents receive relevant knowledge context during task execution. Knowledge surfacing is fully independent from skill surfacing. Multi-layer graph queries enable causal and temporal reasoning. Knowledge notes are traceable through trajectory metadata.
+
+---
+
+### Phase 5: Bidirectional minimem Integration (Optional)
+
+**Goal**: Make cognitive-core and minimem mutually aware — cognitive-core delegates search to minimem when available, and minimem gains the ability to parse, index, and query knowledge-structured notes.
+
+**Depends on:** Phase 4 complete. This phase is entirely optional and does not gate any core functionality.
+
+**Coupling approach:** File conventions only — minimem parses the YAML frontmatter format by convention. No cross-package imports. Both packages remain independently deployable.
+
+#### Part A: cognitive-core → minimem
+
+**Step A1 — SearchProvider interface** (`src/memory/search-provider.ts`)
+
+Strategy pattern for swappable search backends:
+
+```typescript
+interface SearchProvider {
+  readonly name: string;
+  search(query, candidates, options?): SearchProviderResult[] | Promise<SearchProviderResult[]>;
+}
+```
+
+**Step A2 — TextSimilaritySearchProvider** (`src/memory/search-providers/text-similarity.ts`)
+
+Extracted existing `findTopK` logic from `KnowledgeBank.search()` into a class implementing `SearchProvider`.
+
+**Step A3 — MinimemSearchProvider** (`src/memory/search-providers/minimem.ts`)
+
+Defines `MinimemSearchClient` interface (subset of minimem's API) to avoid hard dependency. Delegates search to minimem, maps result paths back to candidate note IDs.
+
+**Step A4 — Directory layout** (`src/memory/knowledge-bank.ts`)
+
+When `minimemAware: true`, knowledge files are placed under `memory/knowledge/` instead of `knowledge/`, aligning with minimem's indexed path (`memory/**/*.md`).
+
+**Step A5 — Detection** (`src/memory/knowledge-bank.ts`)
+
+On `init()`, if `minimemAware`, checks for `.minimem/` directory or `MEMORY.md`. If found, dynamically `import('minimem')` — optional dependency, no `package.json` change. Falls back to `TextSimilaritySearchProvider` if unavailable.
+
+#### Part B: minimem → cognitive-core
+
+All changes in `references/minimem/`.
+
+**Step B1 — Enhanced frontmatter parsing** (`src/session.ts`)
+
+Extended `MemoryFrontmatter` with knowledge fields (`id`, `type`, `domain[]`, `entities[]`, `confidence`, `source`, `links[]`, `supersedes`). Types defined locally — zero imports from cognitive-core. Enhanced YAML parser for nested objects and arrays of objects.
+
+**Step B2 — Database schema v4** (`src/db/schema.ts`)
+
+Added nullable columns to `chunks` table (`knowledge_type`, `knowledge_id`, `domains`, `entities`, `confidence`). Created `knowledge_links` table for graph edges with composite PK `(from_id, to_id, relation)`.
+
+**Step B3 — Knowledge-aware indexing** (`src/minimem.ts`)
+
+`indexFile()` extracts knowledge frontmatter and populates chunk metadata columns. Upserts `knowledge_links` from frontmatter `links` array. Deletes old links on re-index.
+
+**Step B4 — Knowledge-filtered search** (`src/search/search.ts`)
+
+`buildKnowledgeFilterSql()` generates WHERE clauses using `json_each()` for domain/entity array filtering. Supports `minConfidence` and `knowledgeType` filters.
+
+**Step B5 — Graph traversal** (`src/search/graph.ts`)
+
+`getLinksFrom()`, `getLinksTo()`, `getNeighbors()` (BFS), `getPathBetween()` (BFS shortest path).
+
+**Step B6 — Minimem class methods** (`src/minimem.ts`)
+
+Public methods: `knowledgeSearch()`, `getLinks()`, `getGraphNeighbors()`, `getGraphPath()`.
+
+**Step B7 — MCP tools** (`src/server/tools.ts`)
+
+Three new tools alongside existing `memory_search`:
+- `knowledge_search` — search with domain/entity/confidence/type filters
+- `knowledge_graph` — traverse graph relationships from a note
+- `knowledge_path` — find shortest path between two knowledge notes
+
+#### Part C: Tests
+
+- `tests/memory/knowledge-minimem.test.ts` — 11 tests: file layout (4), search delegation (5), SearchProvider abstraction (2)
+- `references/minimem/src/__tests__/knowledge.test.ts` — 13 tests: frontmatter parsing (5), graph traversal (8)
+
+**Phase 5 deliverable:** cognitive-core's knowledge bank works seamlessly in minimem-backed environments, reusing minimem's search. minimem gains full knowledge awareness — indexing metadata, storing graph edges, exposing knowledge-specific MCP tools — all via file conventions with zero cross-package coupling.
+
+---
+
+### Implementation Order & Parallelism
+
+```
+Phase 1 (Foundation)
+  ├── Steps 1.1-1.4 (types, config, frontmatter) — can be done in parallel
+  ├── Steps 1.5-1.8 (KnowledgeBank, graph, layers) — depend on types
+  ├── Steps 1.9-1.11 (wiring, exports) — depend on KnowledgeBank
+  └── Step 1.12 (tests) — depend on implementation
+
+Phase 2 (Extraction)        Phase 4 (Surfacing)
+  ├── depends on Phase 1      ├── Steps 4.1-4.2 can start after Phase 1
+  └── Steps 2.1-2.5           ├── Steps 4.3-4.4 need Phase 2 for full integration
+                               └── Steps 4.5-4.7
+
+Phase 3 (Evolution)
+  ├── depends on Phase 2
+  └── Steps 3.1-3.8
+
+Phase 5 (minimem)
+  └── depends on Phase 4 (optional)
+```
+
+Phases 2 and 4 can be developed partially in parallel since Phase 4's retrieval/formatting code doesn't depend on extraction — it just needs notes to exist on disk (can be seeded manually for testing).
+
+## 13. Open Questions
+
+### Resolved
+1. **Where does the processing pipeline live?** → In cognitive-core. minimem provides filesystem + optional search.
+2. **Extraction granularity (atomic vs aggregate)?** → Both. Observations are atomic; entity notes aggregate. The natural domain drives this.
+3. **Who writes knowledge?** → Both agents (directly to files/inbox) and cognitive-core (via extraction pipeline). Different confidence levels.
+4. **Graph complexity** → Multi-graph (MAGMA-style) from the start, with a pluggable layer interface. Four orthogonal layers: semantic (default/always-on), temporal, causal, entity. Each layer can be independently enabled/disabled. Shared node set, separate edge sets per layer. See Section 5 for full design.
+5. **Knowledge surfacing alongside playbooks** → Independent. Knowledge and playbook surfacing are decoupled systems. Both produce separate context sections. The learning pipeline sees them colocated when analyzing trajectories (agents carry traced versions of skills + knowledge). No coupling between playbook selection and knowledge retrieval. See Section 9.2.
+6. **minimem's role?** → Bidirectional: (a) cognitive-core delegates search to minimem when available (SearchProvider strategy pattern), (b) minimem parses knowledge frontmatter, indexes metadata, stores graph edges, and exposes knowledge-specific MCP tools. Coupling is via file conventions only — no cross-package imports.
+7. **Knowledge extraction wiring?** → Knowledge extraction is decoupled from `LearningPipeline.processTrajectory()`. Callers invoke `KnowledgeBank.extractFromTrajectory()` directly. This differs from Section 6.5's design (which showed automatic wiring) but is intentional — it gives callers control over when extraction runs and avoids coupling the learning pipeline to the knowledge bank.
+
+### Implementation Notes
+
+All 5 phases are implemented. Key divergences from the original design:
+
+- **Phase 2 (Section 6.5)**: Knowledge extraction is NOT auto-wired into `LearningPipeline.processTrajectory()`. Instead, extraction is invoked directly via `KnowledgeBank.extractFromTrajectory()` or `KnowledgeBank.extractFrom()`. This keeps the learning pipeline's contract unchanged and allows callers to control extraction timing.
+- **Phase 4 (Section 4.5)**: The specialized graph traversal convenience methods `getCausalChain()`, `getTemporalNeighbors()`, and `getKnowledgeForPlaybook()` are not implemented as named methods. The underlying graph traversal works via `getRelated()` with layer filtering. These can be added as thin wrappers if needed.
+- **Phase 4 (Section 4.6)**: MCP knowledge tools are not in cognitive-core's `playbook-server.ts`. Instead, they are implemented on the minimem side (`knowledge_search`, `knowledge_graph`, `knowledge_path`), which is the natural home since minimem is the MCP server.
+- **Phase 5**: Expanded from unidirectional (cognitive-core → minimem) to bidirectional. minimem now has full knowledge awareness: schema v4 with knowledge columns + graph table, knowledge-aware indexing, filtered search, graph traversal, and 3 new MCP tools.
+
+### Test Coverage
+
+973 tests passing across the full codebase. Knowledge-specific test files:
+
+| File | Tests | Covers |
+|------|-------|--------|
+| `tests/memory/knowledge-bank.test.ts` | 36 | CRUD, directory structure, stats |
+| `tests/memory/knowledge-graph.test.ts` | 33 | Graph manager, multi-layer traversal, persistence |
+| `tests/memory/graph-layers/semantic.test.ts` | 17 | Semantic layer operations, BFS, rebuild |
+| `tests/utils/frontmatter.test.ts` | 11 | YAML parsing, serialization, round-trip |
+| `tests/learning/knowledge-extractor.test.ts` | 20 | All 4 extraction strategies |
+| `tests/memory/knowledge-bank-extraction.test.ts` | 14 | applyExtraction, extractFromTrajectory |
+| `tests/memory/knowledge-evolution.test.ts` | 19 | Reinforcement, contradiction, decay |
+| `tests/memory/knowledge-defrag.test.ts` | 12 | 7-step defragmentation cycle |
+| `tests/memory/knowledge-inbox.test.ts` | 11 | Inbox processing, classification |
+| `tests/atlas-knowledge.test.ts` | 4 | Atlas.solve() knowledge surfacing |
+| `tests/memory/knowledge-minimem.test.ts` | 11 | minimem integration, SearchProvider |
+
+## 14. References
+
+1. [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) — Comprehensive survey, taxonomy of factual/experiential/procedural memory
+2. [A-MEM: Agentic Memory for LLM Agents](https://arxiv.org/abs/2502.12110) — Zettelkasten-inspired structured notes with dynamic linking
+3. [MAGMA: Multi-Graph Agentic Memory](https://arxiv.org/abs/2601.03236) — Multi-graph decomposition (semantic, temporal, causal, entity)
+4. [Zep: Temporal Knowledge Graph](https://arxiv.org/pdf/2501.13956) — Entity extraction, community detection, temporal tracking
+5. [AriGraph](https://www.ijcai.org/proceedings/2025/0002.pdf) — Incremental KG learning from agent interaction (episodic → semantic)
+6. [CompassMem](https://arxiv.org/abs/2601.04726) — Event-centric memory as logic maps for reasoning
+7. [Agent Memory Paper List](https://github.com/Shichun-Liu/Agent-Memory-Paper-List) — Curated list of 100+ papers on agent memory