codymaster 4.4.5 → 4.5.1

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
+## [4.5.0] - 2026-03-31
+
+### 🚀 Improvements — Context Backbone v5 (Smart Spine)
+
+- **SQLite + FTS5 Storage Layer** — Learnings and decisions migrated from flat JSON to a WAL-mode SQLite database (`.cm/context.db`) with full-text search via FTS5 virtual tables. BM25-ranked `cm_query` replaces linear JSON scans. FTS5 indexes are kept in sync automatically via `AFTER INSERT`/`AFTER DELETE` triggers.
+- **L0 / L1 / L2 Progressive Loading** — Every memory resource is now available at three granularities. L0 compact indexes (`learnings-index.md`, `skeleton-index.md`) reduce context cost by up to 96% for the common "just give me a summary" case. L0 is pre-generated on every `addLearning()` write and refreshable on demand.
+- **cm:// URI Scheme** — Unified content addressing for all CodyMaster resources. Skills reference context by URI (`cm://memory/learnings`, `cm://skills/cm-tdd/L0`, `cm://pipeline/current`) and the resolver handles depth selection, caching, and fallbacks transparently.
+- **MCP Context Server** — Standalone stdio MCP server (`src/mcp-context-server.ts`) exposing 7 tools to Claude Desktop and any MCP-compatible client:
+  - `cm_query` — FTS5 search across learnings + decisions with scope filter
+  - `cm_resolve` — resolve any `cm://` URI at L0/L1/L2
+  - `cm_bus_read` / `cm_bus_write` — read/publish to the context bus
+  - `cm_budget_check` — pre-flight token budget check by category
+  - `cm_memory_decay` — TTL-based archival with `dry_run` option
+  - `cm_index_refresh` — regenerate L0 indexes on demand
+- **Token Budget Enforcement** — 200k-token window pre-allocated by category in `.cm/token-budget.json`. Budget checked at load time; overages return a remediation suggestion. Configurable per-project.
+- **Context Bus** — `.cm/context-bus.json` tracks skill chain state across steps. Each skill publishes its output; downstream skills read what upstream steps produced via `cm://pipeline/current`. Integrated into `createChainExecution()` and `advanceChain()`.
+- **File Watcher** — `src/file-watcher.ts` (chokidar) watches `.cm/memory/*.json` and auto-regenerates the L0 learnings index on change with 300ms debounce.
+- **JSON → SQLite Migration** — One-time migration utility (`src/migrate-json-to-sqlite.ts`) reads existing `learnings.json` / `decisions.json`, inserts into SQLite, and creates `.backup` files. Handles both camelCase and snake_case legacy field names.
+- **New CLI commands** — `cm continuity index` (regenerate L0 indexes), `cm continuity budget` (show token allocation table), `cm continuity bus` (pretty-print context bus), `cm continuity mcp` (print Claude Desktop config snippet).
+- **Test suite expanded** — 4 new test files covering SQLite CRUD + FTS5 relevance, context bus roundtrip, token budget enforcement, and L0 index generation. Test count: 78 → 92 (all passing).
+
+## [4.4.5] - 2026-03-30
+
+### 🔒 Security
+
+- **Security Checkpoints Upgraded** — Deployed unified security updates across `cm-security-gate`, `cm-quality-gate`, `cm-safe-deploy`, and `cm-test-gate`.
+
+## [4.4.4] - 2026-03-29
+
+### 🐛 Bug Fixes
+
+- **Version Bump** — Minor bug fixes and dependency updates.
+
 ## [4.4.3] - 2026-03-29
 
 ### 🚀 Improvements — The Self-Healing Update

package/README.md

@@ -6,10 +6,10 @@
 
 ### Your AI Agent is smart. CodyMaster makes it *wise*.
 
-**68+ Skills · 11 Commands · 1 Plugin · 7+ Platforms · 6 Languages**
+**68+ Skills · 18 Commands · 1 Plugin · 7+ Platforms · 6 Languages**
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-4.4.3-blue.svg?cacheSeconds=2592000" />
+  <img alt="Version" src="https://img.shields.io/badge/version-4.5.0-blue.svg?cacheSeconds=2592000" />
   <img alt="Skills" src="https://img.shields.io/badge/skills-68+-success.svg" />
   <img alt="Platforms" src="https://img.shields.io/badge/platforms-7+-orange.svg" />
   <img alt="Open Source" src="https://img.shields.io/badge/license-MIT-purple.svg" />
@@ -105,9 +105,9 @@ graph LR
     class A,B,C,D,E,F,G,H,I,J,K,L phase;
 ```
 
-### 🧠 The Unified Brain: 5-Tier Memory Architecture
+### 🧠 The Unified Brain: 5-Tier Memory + Smart Spine
 
-Your AI doesn't just execute — it **understands and remembers** using a multi-scale, 5-Tier Unified Brain system that persists across sessions and machines:
+Your AI doesn't just execute — it **understands and remembers** using a multi-scale, 5-Tier + Smart Spine architecture that persists across sessions and machines:
 
 1. **Sensory Memory (Session)** — Immediate context of active files and terminals.
 2. **Working Memory (`cm-continuity`)** — Cross-session scratchpad. AI never repeats the same mistake.
@@ -115,10 +115,18 @@ Your AI doesn't just execute — it **understands and remembers** using a multi-
 4. **Semantic Memory (`cm-deep-search`)** — Local vector search across docs using `qmd`.
 5. **Structural Memory (`cm-codeintell`)** — AST-based CodeGraph. Up to 95% token compression for full codebase context.
 
+🦴 **Smart Spine (v4.5+)** — The nervous system connecting all 5 tiers:
+- **SQLite + FTS5** — BM25-ranked keyword search replaces flat JSON scans.
+- **Progressive Loading (L0/L1/L2)** — Context loaded at cheapest sufficient depth. 78% token savings.
+- **cm:// URI Scheme** — Skills request context by URI, not file paths.
+- **Token Budget** — 200k window pre-allocated by category. No more silent overflow.
+- **Context Bus** — Skills share outputs in real-time within a chain.
+- **MCP Server** — 7 tools exposed to Claude Desktop and any MCP client.
+
 ☁️ **The Cloud Brain (`cm-notebooklm`)**
 High-value knowledge and design patterns are synced to NotebookLM, providing a universal, cross-machine "Soul" for your project. Auto-generate podcasts and flashcards to onboard human developers alongside the AI.
 
-📖 [Read the full Knowledge Architecture →](docs/knowledge-architecture.md)
+📖 [Read the full Knowledge Architecture →](docs/architecture/knowledge-architecture.md)
 
 ### 🛡️ Multi-Layer Protection (Your Codebase Won't Get Destroyed)
 
@@ -166,7 +174,7 @@ Don't know what the old code does? **`cm-dockit`** reads your entire codebase an
 
 Before diving into code for complex requests, **`cm-brainstorm-idea`** evaluates your product using multi-dimensional analysis (Tech, Product, Design, Business). It generates 2-3 qualified options using the 9 Windows (TRIZ) framework and provides a visual UI Preview via **Pencil.dev** or **Google Stitch** to validate the direction before detailed planning. 
 
-📖 [Read more about the UI Preview Phase →](docs/Brainstorm-UI-Preview.md)
+📖 [Read more about the UI Preview Phase →](docs/workflows/brainstorm-ui-preview.md)
 
 
 ### 🏭 AI Content Factory v2.0 & Visual Dashboard
@@ -294,14 +302,21 @@ The CLI will greet you and keep you organized on your long coding sessions!
 ## 🎮 Commands
 
 ```
-cm                → Quick menu with Cody 🐹
-cm task add "..." → Add a task
-cm task list      → View tasks
-cm status         → Project health
-cm dashboard      → Open Mission Control
-cm list           → Browse 68+ skills
-cm profile        → Your stats & achievements
-cm deploy <env>   → Record deployment
+cm                          → Quick menu with Cody 🐹
+cm task add "..."           → Add a task
+cm task list                → View tasks
+cm status                   → Project health
+cm dashboard                → Open Mission Control
+cm list                     → Browse 68+ skills
+cm profile                  → Your stats & achievements
+cm deploy <env>             → Record deployment
+cm continuity index         → Regenerate L0 memory indexes
+cm continuity budget        → Show token budget allocation
+cm continuity bus           → View context bus state
+cm continuity mcp           → Print MCP server config
+cm continuity migrate       → Migrate JSON → SQLite
+cm continuity export        → Export SQLite → JSON
+cm resolve <uri>            → Resolve any cm:// URI
 ```
 
 **Slash Commands (inside AI agents):**

package/commands/demo.md

@@ -24,7 +24,7 @@ Remember the chosen language and respond in it for all following steps.
 
 Show a warm, concise welcome. Include:
 - What CodyMaster is (1 sentence)
-- That it gives AI agents 34+ specialized skills
+- That it gives AI agents 60+ specialized skills
 - That this demo will take ~2 minutes
 
 ## Step 3 — Show the Workflow

package/dist/context-bus.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initBus = initBus;
+exports.readBus = readBus;
+exports.writeBus = writeBus;
+exports.updateBusStep = updateBusStep;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// ─── Constants ──────────────────────────────────────────────────────────────
+const CM_DIR = '.cm';
+const BUS_FILE = 'context-bus.json';
+function getBusPath(projectPath) {
+    return path_1.default.join(projectPath, CM_DIR, BUS_FILE);
+}
+// ─── Init ───────────────────────────────────────────────────────────────────
+function initBus(projectPath, pipeline, sessionId) {
+    const now = new Date().toISOString();
+    const bus = {
+        version: '1.0',
+        session_id: sessionId,
+        pipeline,
+        current_step: '',
+        started_at: now,
+        updated_at: now,
+        shared_context: {},
+        resource_state: {
+            skeleton_generated: null,
+            learnings_indexed: null,
+            codegraph_indexed: null,
+            qmd_synced: null,
+        },
+    };
+    writeBus(projectPath, bus);
+    return bus;
+}
+// ─── Read ───────────────────────────────────────────────────────────────────
+function readBus(projectPath) {
+    const busPath = getBusPath(projectPath);
+    if (!fs_1.default.existsSync(busPath))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(busPath, 'utf-8'));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+// ─── Write ──────────────────────────────────────────────────────────────────
+function writeBus(projectPath, bus) {
+    const busPath = getBusPath(projectPath);
+    const dir = path_1.default.dirname(busPath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    fs_1.default.writeFileSync(busPath, JSON.stringify(bus, null, 2), 'utf-8');
+}
+// ─── Update Step ────────────────────────────────────────────────────────────
+function updateBusStep(projectPath, skill, output) {
+    const bus = readBus(projectPath);
+    if (!bus) {
+        throw new Error(`Context bus not initialized at ${projectPath}. Call initBus() first.`);
+    }
+    bus.current_step = skill;
+    bus.updated_at = new Date().toISOString();
+    bus.shared_context[skill] = output;
+    writeBus(projectPath, bus);
+}

package/dist/context-db.js

@@ -0,0 +1,265 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openDb = openDb;
+exports.closeDb = closeDb;
+exports.insertLearning = insertLearning;
+exports.getLearningById = getLearningById;
+exports.queryLearnings = queryLearnings;
+exports.insertDecision = insertDecision;
+exports.queryDecisions = queryDecisions;
+exports.upsertIndex = upsertIndex;
+exports.getIndex = getIndex;
+exports.writeSkillOutput = writeSkillOutput;
+exports.getSkillOutputs = getSkillOutputs;
+exports.getDbPath = getDbPath;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path_1 = __importDefault(require("path"));
+// ─── DB Cache (one connection per path) ─────────────────────────────────────
+const dbCache = new Map();
+function getDb(dbPath) {
+    if (dbCache.has(dbPath))
+        return dbCache.get(dbPath);
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    dbCache.set(dbPath, db);
+    return db;
+}
+// ─── Schema ─────────────────────────────────────────────────────────────────
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS learnings (
+  id TEXT PRIMARY KEY,
+  what_failed TEXT NOT NULL,
+  why_failed TEXT NOT NULL DEFAULT '',
+  how_to_prevent TEXT NOT NULL DEFAULT '',
+  scope TEXT DEFAULT 'global',
+  ttl INTEGER DEFAULT 60,
+  reinforce_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  agent TEXT,
+  task_id TEXT,
+  module TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS learnings_fts USING fts5(
+  what_failed, why_failed, how_to_prevent,
+  content=learnings, content_rowid=rowid
+);
+
+CREATE TRIGGER IF NOT EXISTS learnings_ai AFTER INSERT ON learnings BEGIN
+  INSERT INTO learnings_fts(rowid, what_failed, why_failed, how_to_prevent)
+  VALUES (new.rowid, new.what_failed, new.why_failed, new.how_to_prevent);
+END;
+
+CREATE TRIGGER IF NOT EXISTS learnings_ad AFTER DELETE ON learnings BEGIN
+  INSERT INTO learnings_fts(learnings_fts, rowid, what_failed, why_failed, how_to_prevent)
+  VALUES('delete', old.rowid, old.what_failed, old.why_failed, old.how_to_prevent);
+END;
+
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY,
+  decision TEXT NOT NULL,
+  rationale TEXT NOT NULL DEFAULT '',
+  scope TEXT DEFAULT 'global',
+  status TEXT DEFAULT 'active',
+  superseded_by TEXT,
+  created_at TEXT NOT NULL,
+  agent TEXT
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+  decision, rationale,
+  content=decisions, content_rowid=rowid
+);
+
+CREATE TRIGGER IF NOT EXISTS decisions_ai AFTER INSERT ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, decision, rationale)
+  VALUES (new.rowid, new.decision, new.rationale);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_ad AFTER DELETE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, decision, rationale)
+  VALUES ('delete', old.rowid, old.decision, old.rationale);
+END;
+
+CREATE TABLE IF NOT EXISTS skill_outputs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  chain_id TEXT,
+  skill TEXT NOT NULL,
+  output_path TEXT,
+  summary TEXT,
+  affected_files TEXT,
+  metadata TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS indexes (
+  resource TEXT NOT NULL,
+  level TEXT NOT NULL,
+  content TEXT NOT NULL,
+  token_count INTEGER,
+  generated_at TEXT NOT NULL,
+  source_hash TEXT,
+  PRIMARY KEY (resource, level)
+);
+
+CREATE TABLE IF NOT EXISTS token_usage (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  category TEXT NOT NULL,
+  tokens_used INTEGER NOT NULL,
+  timestamp TEXT NOT NULL
+);
+`;
+// ─── Open / Close ────────────────────────────────────────────────────────────
+function openDb(dbPath) {
+    const db = getDb(dbPath);
+    db.exec(SCHEMA);
+    return db;
+}
+function closeDb(dbPath) {
+    const db = dbCache.get(dbPath);
+    if (db) {
+        try {
+            db.close();
+        }
+        catch ( /* already closed */_a) { /* already closed */ }
+        dbCache.delete(dbPath);
+    }
+}
+// ─── Learnings ───────────────────────────────────────────────────────────────
+function insertLearning(dbPath, learning) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const db = openDb(dbPath);
+    db.prepare(`
+    INSERT OR REPLACE INTO learnings
+      (id, what_failed, why_failed, how_to_prevent, scope, ttl, reinforce_count,
+       status, created_at, updated_at, agent, task_id, module)
+    VALUES
+      (@id, @what_failed, @why_failed, @how_to_prevent, @scope, @ttl, @reinforce_count,
+       @status, @created_at, @updated_at, @agent, @task_id, @module)
+  `).run({
+        id: learning.id,
+        what_failed: learning.what_failed,
+        why_failed: (_a = learning.why_failed) !== null && _a !== void 0 ? _a : '',
+        how_to_prevent: (_b = learning.how_to_prevent) !== null && _b !== void 0 ? _b : '',
+        scope: (_c = learning.scope) !== null && _c !== void 0 ? _c : 'global',
+        ttl: (_d = learning.ttl) !== null && _d !== void 0 ? _d : 60,
+        reinforce_count: (_e = learning.reinforce_count) !== null && _e !== void 0 ? _e : 0,
+        status: (_f = learning.status) !== null && _f !== void 0 ? _f : 'active',
+        created_at: learning.created_at,
+        updated_at: learning.updated_at,
+        agent: (_g = learning.agent) !== null && _g !== void 0 ? _g : null,
+        task_id: (_h = learning.task_id) !== null && _h !== void 0 ? _h : null,
+        module: (_j = learning.module) !== null && _j !== void 0 ? _j : null,
+    });
+}
+function getLearningById(dbPath, id) {
+    var _a;
+    const db = openDb(dbPath);
+    return (_a = db.prepare('SELECT * FROM learnings WHERE id = ?').get(id)) !== null && _a !== void 0 ? _a : null;
+}
+function queryLearnings(dbPath, query, scope, limit = 10) {
+    const db = openDb(dbPath);
+    if (!query.trim()) {
+        const sql = scope
+            ? "SELECT * FROM learnings WHERE scope = ? AND status != 'archived' ORDER BY created_at DESC LIMIT ?"
+            : "SELECT * FROM learnings WHERE status != 'archived' ORDER BY created_at DESC LIMIT ?";
+        return scope
+            ? db.prepare(sql).all(scope, limit)
+            : db.prepare(sql).all(limit);
+    }
+    // Sanitize scope for SQL (not user-facing, but defensive)
+    const scopeClause = scope ? `AND learnings.scope = '${scope.replace(/'/g, "''")}'` : '';
+    return db.prepare(`
+    SELECT learnings.* FROM learnings
+    JOIN learnings_fts ON learnings.rowid = learnings_fts.rowid
+    WHERE learnings_fts MATCH ?
+      AND learnings.status != 'archived'
+      ${scopeClause}
+    ORDER BY bm25(learnings_fts)
+    LIMIT ?
+  `).all(query, limit);
+}
+// ─── Decisions ───────────────────────────────────────────────────────────────
+function insertDecision(dbPath, decision) {
+    var _a, _b, _c, _d, _e;
+    const db = openDb(dbPath);
+    db.prepare(`
+    INSERT OR REPLACE INTO decisions
+      (id, decision, rationale, scope, status, superseded_by, created_at, agent)
+    VALUES
+      (@id, @decision, @rationale, @scope, @status, @superseded_by, @created_at, @agent)
+  `).run({
+        id: decision.id,
+        decision: decision.decision,
+        rationale: (_a = decision.rationale) !== null && _a !== void 0 ? _a : '',
+        scope: (_b = decision.scope) !== null && _b !== void 0 ? _b : 'global',
+        status: (_c = decision.status) !== null && _c !== void 0 ? _c : 'active',
+        superseded_by: (_d = decision.superseded_by) !== null && _d !== void 0 ? _d : null,
+        created_at: decision.created_at,
+        agent: (_e = decision.agent) !== null && _e !== void 0 ? _e : null,
+    });
+}
+function queryDecisions(dbPath, query, limit = 10) {
+    const db = openDb(dbPath);
+    if (!query.trim()) {
+        return db.prepare("SELECT * FROM decisions WHERE status != 'archived' ORDER BY created_at DESC LIMIT ?").all(limit);
+    }
+    return db.prepare(`
+    SELECT decisions.* FROM decisions
+    JOIN decisions_fts ON decisions.rowid = decisions_fts.rowid
+    WHERE decisions_fts MATCH ?
+      AND decisions.status != 'archived'
+    ORDER BY bm25(decisions_fts)
+    LIMIT ?
+  `).all(query, limit);
+}
+// ─── Index Cache ─────────────────────────────────────────────────────────────
+function upsertIndex(dbPath, resource, level, content, sourceHash) {
+    const db = openDb(dbPath);
+    const tokenCount = Math.ceil(content.length / 4);
+    db.prepare(`
+    INSERT OR REPLACE INTO indexes (resource, level, content, token_count, generated_at, source_hash)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(resource, level, content, tokenCount, new Date().toISOString(), sourceHash !== null && sourceHash !== void 0 ? sourceHash : null);
+}
+function getIndex(dbPath, resource, level) {
+    var _a;
+    const db = openDb(dbPath);
+    return (_a = db.prepare('SELECT * FROM indexes WHERE resource = ? AND level = ?').get(resource, level)) !== null && _a !== void 0 ? _a : null;
+}
+// ─── Skill Outputs ────────────────────────────────────────────────────────────
+function writeSkillOutput(dbPath, output) {
+    var _a, _b, _c, _d, _e;
+    const db = openDb(dbPath);
+    db.prepare(`
+    INSERT INTO skill_outputs
+      (session_id, chain_id, skill, output_path, summary, affected_files, metadata, created_at)
+    VALUES
+      (@session_id, @chain_id, @skill, @output_path, @summary, @affected_files, @metadata, @created_at)
+  `).run({
+        session_id: output.session_id,
+        chain_id: (_a = output.chain_id) !== null && _a !== void 0 ? _a : null,
+        skill: output.skill,
+        output_path: (_b = output.output_path) !== null && _b !== void 0 ? _b : null,
+        summary: (_c = output.summary) !== null && _c !== void 0 ? _c : null,
+        affected_files: (_d = output.affected_files) !== null && _d !== void 0 ? _d : null,
+        metadata: (_e = output.metadata) !== null && _e !== void 0 ? _e : null,
+        created_at: output.created_at,
+    });
+}
+function getSkillOutputs(dbPath, sessionId) {
+    const db = openDb(dbPath);
+    return db.prepare('SELECT * FROM skill_outputs WHERE session_id = ? ORDER BY id ASC').all(sessionId);
+}
+// ─── DB Path Helper ──────────────────────────────────────────────────────────
+function getDbPath(projectPath) {
+    return path_1.default.join(projectPath, '.cm', 'context.db');
+}

package/dist/continuity.js

@@ -19,6 +19,8 @@ exports.hasCmDir = hasCmDir;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const crypto_1 = __importDefault(require("crypto"));
+const l0_indexer_1 = require("./l0-indexer");
+const token_budget_1 = require("./token-budget");
 // ─── Constants ──────────────────────────────────────────────────────────────
 const CM_DIR = '.cm';
 const CONTINUITY_FILE = 'CONTINUITY.md';
@@ -55,6 +57,11 @@ function ensureCmDir(projectPath) {
     if (!fs_1.default.existsSync(configPath)) {
         fs_1.default.writeFileSync(configPath, generateDefaultConfig());
     }
+    // Initialize token budget if not present
+    const budgetPath = path_1.default.join(cmDir, 'token-budget.json');
+    if (!fs_1.default.existsSync(budgetPath)) {
+        fs_1.default.writeFileSync(budgetPath, JSON.stringify((0, token_budget_1.getDefaultBudget)(), null, 2));
+    }
     // Add .cm to .gitignore if not already there
     const gitignorePath = path_1.default.join(projectPath, '.gitignore');
     if (fs_1.default.existsSync(gitignorePath)) {
@@ -252,6 +259,11 @@ function addLearning(projectPath, learning) {
     catch ( /* empty */_a) { /* empty */ }
     learnings.push(fullLearning);
     fs_1.default.writeFileSync(learningsPath, JSON.stringify(learnings, null, 2));
+    // Refresh L0 index after adding a learning
+    try {
+        (0, l0_indexer_1.generateLearningsIndex)(projectPath);
+    }
+    catch ( /* non-fatal */_b) { /* non-fatal */ }
     return fullLearning;
 }
 function archiveLearnings(projectPath, learnings) {

package/dist/file-watcher.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWatcher = startWatcher;
+exports.stopWatcher = stopWatcher;
+exports.isWatching = isWatching;
+const chokidar_1 = __importDefault(require("chokidar"));
+const path_1 = __importDefault(require("path"));
+const l0_indexer_1 = require("./l0-indexer");
+// ─── Watcher ─────────────────────────────────────────────────────────────────
+let watcher = null;
+const debounceTimers = new Map();
+function debounce(key, ms, fn) {
+    const existing = debounceTimers.get(key);
+    if (existing)
+        clearTimeout(existing);
+    debounceTimers.set(key, setTimeout(() => {
+        debounceTimers.delete(key);
+        fn();
+    }, ms));
+}
+/**
+ * Start watching `.cm/memory/learnings.json` and `.cm/memory/decisions.json`.
+ * On change, regenerates the L0 learnings index automatically.
+ */
+function startWatcher(projectPath, options = {}) {
+    if (watcher)
+        return watcher;
+    const { debounceMs = 300, onRefresh, onError } = options;
+    const memoryDir = path_1.default.join(projectPath, '.cm', 'memory');
+    const watched = [
+        path_1.default.join(memoryDir, 'learnings.json'),
+        path_1.default.join(memoryDir, 'decisions.json'),
+    ];
+    watcher = chokidar_1.default.watch(watched, {
+        ignoreInitial: true,
+        persistent: false,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+    });
+    watcher.on('change', (filePath) => {
+        const basename = path_1.default.basename(filePath);
+        debounce(`refresh:${basename}`, debounceMs, () => {
+            try {
+                if (basename === 'learnings.json') {
+                    (0, l0_indexer_1.generateLearningsIndex)(projectPath);
+                    onRefresh === null || onRefresh === void 0 ? void 0 : onRefresh('learnings');
+                }
+                // decisions don't have an L0 index yet — placeholder for future
+            }
+            catch (err) {
+                onError === null || onError === void 0 ? void 0 : onError(err);
+            }
+        });
+    });
+    watcher.on('error', (err) => {
+        onError === null || onError === void 0 ? void 0 : onError(err);
+    });
+    return watcher;
+}
+/**
+ * Stop the active watcher and clear pending debounce timers.
+ */
+function stopWatcher() {
+    for (const timer of debounceTimers.values())
+        clearTimeout(timer);
+    debounceTimers.clear();
+    if (watcher) {
+        watcher.close();
+        watcher = null;
+    }
+}
+/**
+ * Returns true if a watcher is currently active.
+ */
+function isWatching() {
+    return watcher !== null;
+}