claude-memory-layer 1.0.10 → 1.0.12

package/dist/cli/index.js

@@ -5,18 +5,25 @@ import { dirname } from 'path';
 const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/cli/index.ts
 import { Command } from "commander";
 import { exec } from "child_process";
-import * as fs4 from "fs";
-import * as path4 from "path";
-import * as os3 from "os";
+import * as fs9 from "fs";
+import * as path9 from "path";
+import * as os6 from "os";
 
 // src/services/memory-service.ts
-import * as path from "path";
+import * as path3 from "path";
 import * as os from "os";
-import * as fs from "fs";
+import * as fs4 from "fs";
 import * as crypto2 from "crypto";
 
 // src/core/event-store.ts
@@ -74,57 +81,57 @@ function toDate(value) {
     return new Date(value);
   return new Date(String(value));
 }
-function createDatabase(path5, options) {
+function createDatabase(path10, options) {
   if (options?.readOnly) {
-    return new duckdb.Database(path5, { access_mode: "READ_ONLY" });
+    return new duckdb.Database(path10, { access_mode: "READ_ONLY" });
   }
-  return new duckdb.Database(path5);
+  return new duckdb.Database(path10);
 }
 function dbRun(db, sql, params = []) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     if (params.length === 0) {
       db.run(sql, (err) => {
         if (err)
           reject(err);
         else
-          resolve2();
+          resolve4();
       });
     } else {
       db.run(sql, ...params, (err) => {
         if (err)
           reject(err);
         else
-          resolve2();
+          resolve4();
       });
     }
   });
 }
 function dbAll(db, sql, params = []) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     if (params.length === 0) {
       db.all(sql, (err, rows) => {
         if (err)
           reject(err);
         else
-          resolve2(convertBigInts(rows || []));
+          resolve4(convertBigInts(rows || []));
       });
     } else {
       db.all(sql, ...params, (err, rows) => {
         if (err)
           reject(err);
         else
-          resolve2(convertBigInts(rows || []));
+          resolve4(convertBigInts(rows || []));
       });
     }
   });
 }
 function dbClose(db) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve4, reject) => {
     db.close((err) => {
       if (err)
         reject(err);
       else
-        resolve2();
+        resolve4();
     });
   });
 }
@@ -342,6 +349,17 @@ var EventStore = class {
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
       )
     `);
+    await dbRun(this.db, `
+      CREATE TABLE IF NOT EXISTS consolidated_rules (
+        rule_id VARCHAR PRIMARY KEY,
+        rule TEXT NOT NULL,
+        topics JSON,
+        source_memory_ids JSON,
+        source_events JSON,
+        confidence FLOAT DEFAULT 0.5,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
     await dbRun(this.db, `
       CREATE TABLE IF NOT EXISTS endless_config (
         key VARCHAR PRIMARY KEY,
@@ -361,6 +379,7 @@ var EventStore = class {
     await dbRun(this.db, `CREATE INDEX IF NOT EXISTS idx_working_set_expires ON working_set(expires_at)`);
     await dbRun(this.db, `CREATE INDEX IF NOT EXISTS idx_working_set_relevance ON working_set(relevance_score DESC)`);
     await dbRun(this.db, `CREATE INDEX IF NOT EXISTS idx_consolidated_confidence ON consolidated_memories(confidence DESC)`);
+    await dbRun(this.db, `CREATE INDEX IF NOT EXISTS idx_consolidated_rules_confidence ON consolidated_rules(confidence DESC)`);
     await dbRun(this.db, `CREATE INDEX IF NOT EXISTS idx_continuity_created ON continuity_log(created_at)`);
     this.initialized = true;
   }
@@ -748,8 +767,14 @@ import { randomUUID as randomUUID2 } from "crypto";
 
 // src/core/sqlite-wrapper.ts
 import Database from "better-sqlite3";
-function createSQLiteDatabase(path5, options) {
-  const db = new Database(path5, {
+import * as fs from "fs";
+import * as nodePath from "path";
+function createSQLiteDatabase(path10, options) {
+  const dir = nodePath.dirname(path10);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const db = new Database(path10, {
     readonly: options?.readonly ?? false
   });
   if (!options?.readonly && (options?.walMode ?? true)) {
@@ -790,6 +815,64 @@ function toSQLiteTimestamp(date) {
   return date.toISOString();
 }
 
+// src/core/markdown-mirror.ts
+import * as fs2 from "fs/promises";
+import * as path from "path";
+var DEFAULT_NAMESPACE = "default";
+var DEFAULT_CATEGORY = "uncategorized";
+function sanitizeSegment(input, fallback) {
+  const raw = String(input ?? "").trim().toLowerCase();
+  const safe = raw.normalize("NFKD").replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!safe || safe === "." || safe === "..")
+    return fallback;
+  return safe;
+}
+function getCategorySegments(metadata, eventType) {
+  const raw = metadata?.categoryPath;
+  if (Array.isArray(raw) && raw.length > 0) {
+    return raw.map((s) => sanitizeSegment(s, DEFAULT_CATEGORY));
+  }
+  const single = metadata?.category;
+  if (typeof single === "string" && single.trim()) {
+    return [sanitizeSegment(single, DEFAULT_CATEGORY)];
+  }
+  return [sanitizeSegment(eventType, DEFAULT_CATEGORY)];
+}
+function buildMirrorPath(rootDir, event) {
+  const metadata = event.metadata;
+  const namespace = sanitizeSegment(metadata?.namespace, DEFAULT_NAMESPACE);
+  const categories = getCategorySegments(metadata, event.eventType);
+  const d = event.timestamp;
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return path.join(rootDir, "memory", namespace, ...categories, `${yyyy}-${mm}-${dd}.md`);
+}
+function formatMirrorEntry(event) {
+  const category = Array.isArray(event.metadata?.categoryPath) ? event.metadata.categoryPath.join("/") : String(event.metadata?.category ?? event.eventType);
+  return [
+    "",
+    `- ts: ${event.timestamp.toISOString()}`,
+    `  id: ${event.id}`,
+    `  type: ${event.eventType}`,
+    `  session: ${event.sessionId}`,
+    `  category: ${category}`,
+    "  content: |",
+    ...event.content.split("\n").map((line) => `    ${line}`)
+  ].join("\n") + "\n";
+}
+var MarkdownMirror = class {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  async append(event) {
+    const outPath = buildMirrorPath(this.rootDir, event);
+    await fs2.mkdir(path.dirname(outPath), { recursive: true });
+    await fs2.appendFile(outPath, formatMirrorEntry(event), "utf8");
+    return outPath;
+  }
+};
+
 // src/core/sqlite-event-store.ts
 var SQLiteEventStore = class {
   constructor(dbPath, options) {
@@ -799,10 +882,12 @@ var SQLiteEventStore = class {
       readonly: this.readOnly,
       walMode: !this.readOnly
     });
+    this.markdownMirror = this.readOnly || !options?.markdownMirrorRoot ? null : new MarkdownMirror(options.markdownMirrorRoot);
   }
   db;
   initialized = false;
   readOnly;
+  markdownMirror;
   /**
    * Initialize database schema
    */
@@ -1009,6 +1094,17 @@ var SQLiteEventStore = class {
         created_at TEXT DEFAULT (datetime('now'))
       );
 
+      -- Consolidated Rules table (long-term stable memory)
+      CREATE TABLE IF NOT EXISTS consolidated_rules (
+        rule_id TEXT PRIMARY KEY,
+        rule TEXT NOT NULL,
+        topics TEXT,
+        source_memory_ids TEXT,
+        source_events TEXT,
+        confidence REAL DEFAULT 0.5,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
       -- Endless Mode Config table
       CREATE TABLE IF NOT EXISTS endless_config (
         key TEXT PRIMARY KEY,
@@ -1016,6 +1112,41 @@ var SQLiteEventStore = class {
         updated_at TEXT DEFAULT (datetime('now'))
       );
 
+      -- Memory Helpfulness tracking
+      CREATE TABLE IF NOT EXISTS memory_helpfulness (
+        id TEXT PRIMARY KEY,
+        event_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        retrieval_score REAL DEFAULT 0,
+        query_preview TEXT,
+        session_continued INTEGER DEFAULT 0,
+        prompt_count_after INTEGER DEFAULT 0,
+        tool_success_count INTEGER DEFAULT 0,
+        tool_total_count INTEGER DEFAULT 0,
+        was_reasked INTEGER DEFAULT 0,
+        helpfulness_score REAL DEFAULT 0.5,
+        created_at TEXT DEFAULT (datetime('now')),
+        measured_at TEXT
+      );
+
+      -- Retrieval trace log (query -> candidates -> selected for context)
+      CREATE TABLE IF NOT EXISTS retrieval_traces (
+        trace_id TEXT PRIMARY KEY,
+        session_id TEXT,
+        project_hash TEXT,
+        query_text TEXT NOT NULL,
+        strategy TEXT,
+        candidate_event_ids TEXT,
+        selected_event_ids TEXT,
+        candidate_details_json TEXT,
+        selected_details_json TEXT,
+        candidate_count INTEGER DEFAULT 0,
+        selected_count INTEGER DEFAULT 0,
+        confidence TEXT,
+        fallback_trace TEXT,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
       -- Sync position tracking (for SQLite -> DuckDB sync)
       CREATE TABLE IF NOT EXISTS sync_positions (
         target_name TEXT PRIMARY KEY,
@@ -1040,7 +1171,14 @@ var SQLiteEventStore = class {
       CREATE INDEX IF NOT EXISTS idx_working_set_relevance ON working_set(relevance_score);
       CREATE INDEX IF NOT EXISTS idx_consolidated_confidence ON consolidated_memories(confidence);
       CREATE INDEX IF NOT EXISTS idx_continuity_created ON continuity_log(created_at);
+      CREATE INDEX IF NOT EXISTS idx_consolidated_rules_confidence ON consolidated_rules(confidence);
       CREATE INDEX IF NOT EXISTS idx_embedding_outbox_status ON embedding_outbox(status);
+      CREATE INDEX IF NOT EXISTS idx_helpfulness_event ON memory_helpfulness(event_id);
+      CREATE INDEX IF NOT EXISTS idx_helpfulness_session ON memory_helpfulness(session_id);
+      CREATE INDEX IF NOT EXISTS idx_helpfulness_score ON memory_helpfulness(helpfulness_score DESC);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_traces_created_at ON retrieval_traces(created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_traces_project_hash ON retrieval_traces(project_hash);
+      CREATE INDEX IF NOT EXISTS idx_retrieval_traces_session_id ON retrieval_traces(session_id);
 
       -- FTS5 Full-Text Search for fast keyword search
       CREATE VIRTUAL TABLE IF NOT EXISTS events_fts USING fts5(
@@ -1064,6 +1202,14 @@ var SQLiteEventStore = class {
         INSERT INTO events_fts(rowid, content, event_id) VALUES (NEW.rowid, NEW.content, NEW.id);
       END;
     `);
+    try {
+      sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN selected_details_json TEXT;`);
+    } catch {
+    }
+    try {
+      sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN candidate_details_json TEXT;`);
+    } catch {
+    }
     const tableInfo = sqliteAll(this.db, "PRAGMA table_info(events)", []);
     const columnNames = tableInfo.map((col) => col.name);
     if (!columnNames.includes("access_count")) {
@@ -1084,6 +1230,15 @@ var SQLiteEventStore = class {
         console.error("Error adding last_accessed_at column:", err);
       }
     }
+    if (!columnNames.includes("turn_id")) {
+      try {
+        sqliteExec(this.db, `
+          ALTER TABLE events ADD COLUMN turn_id TEXT;
+        `);
+      } catch (err) {
+        console.error("Error adding turn_id column:", err);
+      }
+    }
     try {
       sqliteExec(this.db, `
         CREATE INDEX IF NOT EXISTS idx_events_access_count ON events(access_count DESC);
@@ -1096,6 +1251,12 @@ var SQLiteEventStore = class {
       `);
     } catch (err) {
     }
+    try {
+      sqliteExec(this.db, `
+        CREATE INDEX IF NOT EXISTS idx_events_turn_id ON events(turn_id);
+      `);
+    } catch (err) {
+    }
     this.initialized = true;
   }
   /**
@@ -1120,9 +1281,11 @@ var SQLiteEventStore = class {
     const id = randomUUID2();
     const timestamp = toSQLiteTimestamp(input.timestamp);
     try {
+      const metadata = input.metadata || {};
+      const turnId = metadata.turnId || null;
       const insertEvent = this.db.prepare(`
-        INSERT INTO events (id, event_type, session_id, timestamp, content, canonical_key, dedupe_key, metadata)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO events (id, event_type, session_id, timestamp, content, canonical_key, dedupe_key, metadata, turn_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
       const insertDedup = this.db.prepare(`
         INSERT INTO event_dedup (dedupe_key, event_id) VALUES (?, ?)
@@ -1139,12 +1302,28 @@ var SQLiteEventStore = class {
           input.content,
           canonicalKey,
           dedupeKey,
-          JSON.stringify(input.metadata || {})
+          JSON.stringify(metadata),
+          turnId
         );
         insertDedup.run(dedupeKey, id);
         insertLevel.run(id);
       });
       transaction();
+      if (this.markdownMirror) {
+        const event = {
+          id,
+          eventType: input.eventType,
+          sessionId: input.sessionId,
+          timestamp: input.timestamp,
+          content: input.content,
+          canonicalKey,
+          dedupeKey,
+          metadata
+        };
+        this.markdownMirror.append(event).catch((err) => {
+          console.warn("[SQLiteEventStore] markdown mirror append failed:", err);
+        });
+      }
       return { success: true, eventId: id, isDuplicate: false };
     } catch (error) {
       return {
@@ -1203,6 +1382,92 @@ var SQLiteEventStore = class {
     );
     return rows.map(this.rowToEvent);
   }
+  /**
+   * Get events since a SQLite rowid (for robust incremental replication).
+   * Rowid is monotonic for append-only tables, independent of client timestamps.
+   */
+  async getEventsSinceRowid(lastRowid, limit = 1e3) {
+    await this.initialize();
+    const rows = sqliteAll(
+      this.db,
+      `SELECT rowid as _rowid, * FROM events WHERE rowid > ? ORDER BY rowid ASC LIMIT ?`,
+      [lastRowid, limit]
+    );
+    return rows.map((row) => ({
+      rowid: row._rowid,
+      event: this.rowToEvent(row)
+    }));
+  }
+  /**
+   * Import events with fixed IDs (used for cross-machine replication).
+   * Idempotent: skips if event id or dedupeKey already exists.
+   *
+   * NOTE: This bypasses the append() id generation to preserve stable IDs.
+   */
+  async importEvents(events) {
+    if (events.length === 0)
+      return { inserted: 0, skipped: 0 };
+    if (this.readOnly)
+      return { inserted: 0, skipped: events.length };
+    await this.initialize();
+    const getById = this.db.prepare(`SELECT id FROM events WHERE id = ?`);
+    const getByDedupe = this.db.prepare(`SELECT event_id FROM event_dedup WHERE dedupe_key = ?`);
+    const insertEvent = this.db.prepare(`
+      INSERT INTO events (id, event_type, session_id, timestamp, content, canonical_key, dedupe_key, metadata, turn_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    const insertDedup = this.db.prepare(`
+      INSERT INTO event_dedup (dedupe_key, event_id) VALUES (?, ?)
+    `);
+    const insertLevel = this.db.prepare(`
+      INSERT INTO memory_levels (event_id, level) VALUES (?, 'L0')
+    `);
+    let inserted = 0;
+    let skipped = 0;
+    const insertedEvents = [];
+    const tx = this.db.transaction((batch) => {
+      for (const ev of batch) {
+        const existingById = getById.get(ev.id);
+        if (existingById) {
+          skipped++;
+          continue;
+        }
+        const canonicalKey = ev.canonicalKey || makeCanonicalKey(ev.content);
+        const dedupeKey = ev.dedupeKey || makeDedupeKey(ev.content, ev.sessionId);
+        const existingByDedupe = getByDedupe.get(dedupeKey);
+        if (existingByDedupe) {
+          skipped++;
+          continue;
+        }
+        const metadata = ev.metadata || {};
+        const turnId = metadata.turnId;
+        insertEvent.run(
+          ev.id,
+          ev.eventType,
+          ev.sessionId,
+          toSQLiteTimestamp(ev.timestamp),
+          ev.content,
+          canonicalKey,
+          dedupeKey,
+          JSON.stringify(metadata),
+          turnId ?? null
+        );
+        insertDedup.run(dedupeKey, ev.id);
+        insertLevel.run(ev.id);
+        inserted++;
+        insertedEvents.push(ev);
+      }
+    });
+    tx(events);
+    if (this.markdownMirror && insertedEvents.length > 0) {
+      for (const ev of insertedEvents) {
+        this.markdownMirror.append(ev).catch((err) => {
+          console.warn("[SQLiteEventStore] markdown mirror append failed:", err);
+        });
+      }
+    }
+    return { inserted, skipped };
+  }
   /**
    * Create or update session
    */
@@ -1365,6 +1630,35 @@ var SQLiteEventStore = class {
       [error, ...ids]
     );
   }
+  /**
+   * Get embedding/vector outbox health statistics
+   */
+  async getOutboxStats() {
+    await this.initialize();
+    const embeddingRows = sqliteAll(
+      this.db,
+      `SELECT status, COUNT(*) as count FROM embedding_outbox GROUP BY status`
+    );
+    const vectorRows = sqliteAll(
+      this.db,
+      `SELECT status, COUNT(*) as count FROM vector_outbox GROUP BY status`
+    );
+    const fromRows = (rows) => {
+      const out = { pending: 0, processing: 0, failed: 0, total: 0 };
+      for (const row of rows) {
+        const key = row.status;
+        if (key === "pending" || key === "processing" || key === "failed") {
+          out[key] += row.count;
+        }
+        out.total += row.count;
+      }
+      return out;
+    };
+    return {
+      embedding: fromRows(embeddingRows),
+      vector: fromRows(vectorRows)
+    };
+  }
   /**
    * Update memory level
    */
@@ -1489,11 +1783,11 @@ var SQLiteEventStore = class {
     );
   }
   /**
-   * Get most accessed memories
+   * Get most accessed memories (falls back to recent events if none accessed)
    */
   async getMostAccessed(limit = 10) {
     await this.initialize();
-    const rows = sqliteAll(
+    let rows = sqliteAll(
       this.db,
       `SELECT * FROM events
        WHERE access_count > 0
@@ -1501,8 +1795,166 @@ var SQLiteEventStore = class {
        LIMIT ?`,
       [limit]
     );
+    if (rows.length === 0) {
+      rows = sqliteAll(
+        this.db,
+        `SELECT * FROM events
+         ORDER BY timestamp DESC
+         LIMIT ?`,
+        [limit]
+      );
+    }
     return rows.map((row) => this.rowToEvent(row));
   }
+  /**
+   * Record a memory retrieval for helpfulness tracking
+   */
+  async recordRetrieval(eventId, sessionId, score, query) {
+    if (this.readOnly)
+      return;
+    await this.initialize();
+    const id = randomUUID2();
+    sqliteRun(
+      this.db,
+      `INSERT INTO memory_helpfulness (id, event_id, session_id, retrieval_score, query_preview, created_at)
+       VALUES (?, ?, ?, ?, ?, datetime('now'))`,
+      [id, eventId, sessionId, score, query.slice(0, 100)]
+    );
+  }
+  /**
+   * Evaluate helpfulness for all retrievals in a session
+   * Called at session end - uses behavioral signals to compute score
+   */
+  async evaluateSessionHelpfulness(sessionId) {
+    if (this.readOnly)
+      return;
+    await this.initialize();
+    const retrievals = sqliteAll(
+      this.db,
+      `SELECT * FROM memory_helpfulness WHERE session_id = ? AND measured_at IS NULL`,
+      [sessionId]
+    );
+    if (retrievals.length === 0)
+      return;
+    const sessionEvents = sqliteAll(
+      this.db,
+      `SELECT * FROM events WHERE session_id = ? ORDER BY timestamp ASC`,
+      [sessionId]
+    );
+    const promptEvents = sessionEvents.filter((e) => e.event_type === "user_prompt");
+    const toolEvents = sessionEvents.filter((e) => e.event_type === "tool_observation");
+    let toolSuccessCount = 0;
+    let toolTotalCount = toolEvents.length;
+    for (const t of toolEvents) {
+      try {
+        const content = JSON.parse(t.content);
+        if (content.success !== false)
+          toolSuccessCount++;
+      } catch {
+        toolSuccessCount++;
+      }
+    }
+    const toolSuccessRatio = toolTotalCount > 0 ? toolSuccessCount / toolTotalCount : 0.5;
+    for (const retrieval of retrievals) {
+      const retrievalTime = retrieval.created_at;
+      const eventsAfter = sessionEvents.filter((e) => e.timestamp > retrievalTime);
+      const sessionContinued = eventsAfter.length > 0 ? 1 : 0;
+      const promptsAfter = promptEvents.filter((e) => e.timestamp > retrievalTime);
+      const promptCountAfter = promptsAfter.length;
+      const queryWords = new Set((retrieval.query_preview || "").toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+      let wasReasked = 0;
+      for (const p of promptsAfter) {
+        const pWords = new Set(p.content.toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+        let overlap = 0;
+        for (const w of queryWords) {
+          if (pWords.has(w))
+            overlap++;
+        }
+        if (queryWords.size > 0 && overlap / queryWords.size > 0.5) {
+          wasReasked = 1;
+          break;
+        }
+      }
+      const retrievalScore = retrieval.retrieval_score || 0;
+      const helpfulnessScore = 0.3 * Math.min(retrievalScore, 1) + 0.25 * (sessionContinued ? 1 : 0) + 0.25 * toolSuccessRatio + 0.2 * (wasReasked ? 0 : 1);
+      sqliteRun(
+        this.db,
+        `UPDATE memory_helpfulness
+         SET session_continued = ?, prompt_count_after = ?,
+             tool_success_count = ?, tool_total_count = ?,
+             was_reasked = ?, helpfulness_score = ?,
+             measured_at = datetime('now')
+         WHERE id = ?`,
+        [
+          sessionContinued,
+          promptCountAfter,
+          toolSuccessCount,
+          toolTotalCount,
+          wasReasked,
+          helpfulnessScore,
+          retrieval.id
+        ]
+      );
+    }
+  }
+  /**
+   * Get most helpful memories ranked by helpfulness score
+   */
+  async getHelpfulMemories(limit = 10) {
+    await this.initialize();
+    const rows = sqliteAll(
+      this.db,
+      `SELECT
+         mh.event_id,
+         AVG(mh.helpfulness_score) as avg_score,
+         COUNT(*) as eval_count,
+         e.content,
+         e.access_count
+       FROM memory_helpfulness mh
+       JOIN events e ON e.id = mh.event_id
+       WHERE mh.measured_at IS NOT NULL
+       GROUP BY mh.event_id
+       ORDER BY avg_score DESC
+       LIMIT ?`,
+      [limit]
+    );
+    return rows.map((r) => ({
+      eventId: r.event_id,
+      summary: r.content.substring(0, 200) + (r.content.length > 200 ? "..." : ""),
+      helpfulnessScore: Math.round(r.avg_score * 100) / 100,
+      accessCount: r.access_count || 0,
+      evaluationCount: r.eval_count
+    }));
+  }
+  /**
+   * Get helpfulness statistics for dashboard
+   */
+  async getHelpfulnessStats() {
+    await this.initialize();
+    const stats = sqliteGet(
+      this.db,
+      `SELECT
+         AVG(helpfulness_score) as avg_score,
+         COUNT(*) as total_evaluated,
+         SUM(CASE WHEN helpfulness_score >= 0.7 THEN 1 ELSE 0 END) as helpful,
+         SUM(CASE WHEN helpfulness_score >= 0.4 AND helpfulness_score < 0.7 THEN 1 ELSE 0 END) as neutral,
+         SUM(CASE WHEN helpfulness_score < 0.4 THEN 1 ELSE 0 END) as unhelpful
+       FROM memory_helpfulness
+       WHERE measured_at IS NOT NULL`
+    );
+    const totalRow = sqliteGet(
+      this.db,
+      `SELECT COUNT(*) as total FROM memory_helpfulness`
+    );
+    return {
+      avgScore: Math.round((stats?.avg_score || 0) * 100) / 100,
+      totalEvaluated: stats?.total_evaluated || 0,
+      totalRetrievals: totalRow?.total || 0,
+      helpful: stats?.helpful || 0,
+      neutral: stats?.neutral || 0,
+      unhelpful: stats?.unhelpful || 0
+    };
+  }
   /**
    * Fast keyword search using FTS5
    * Returns events matching the search query, ranked by relevance
@@ -1565,12 +2017,222 @@ var SQLiteEventStore = class {
   getDatabase() {
     return this.db;
   }
+  async recordRetrievalTrace(input) {
+    await this.initialize();
+    const traceId = randomUUID2();
+    sqliteRun(
+      this.db,
+      `INSERT INTO retrieval_traces (
+        trace_id, session_id, project_hash, query_text, strategy,
+        candidate_event_ids, selected_event_ids, candidate_details_json, selected_details_json,
+        candidate_count, selected_count, confidence, fallback_trace
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        traceId,
+        input.sessionId || null,
+        input.projectHash || null,
+        input.queryText,
+        input.strategy || null,
+        JSON.stringify(input.candidateEventIds || []),
+        JSON.stringify(input.selectedEventIds || []),
+        JSON.stringify(input.candidateDetails || []),
+        JSON.stringify(input.selectedDetails || []),
+        (input.candidateEventIds || []).length,
+        (input.selectedEventIds || []).length,
+        input.confidence || null,
+        JSON.stringify(input.fallbackTrace || [])
+      ]
+    );
+  }
+  async getRecentRetrievalTraces(limit = 50) {
+    await this.initialize();
+    const rows = sqliteAll(
+      this.db,
+      `SELECT * FROM retrieval_traces ORDER BY created_at DESC LIMIT ?`,
+      [limit]
+    );
+    return rows.map((row) => ({
+      traceId: row.trace_id,
+      sessionId: row.session_id || void 0,
+      projectHash: row.project_hash || void 0,
+      queryText: row.query_text,
+      strategy: row.strategy || void 0,
+      candidateEventIds: row.candidate_event_ids ? JSON.parse(row.candidate_event_ids) : [],
+      selectedEventIds: row.selected_event_ids ? JSON.parse(row.selected_event_ids) : [],
+      candidateDetails: row.candidate_details_json ? JSON.parse(row.candidate_details_json) : [],
+      selectedDetails: row.selected_details_json ? JSON.parse(row.selected_details_json) : [],
+      candidateCount: Number(row.candidate_count || 0),
+      selectedCount: Number(row.selected_count || 0),
+      confidence: row.confidence || void 0,
+      fallbackTrace: row.fallback_trace ? JSON.parse(row.fallback_trace) : [],
+      createdAt: toDateFromSQLite(row.created_at)
+    }));
+  }
+  async getRetrievalTraceStats() {
+    await this.initialize();
+    const row = sqliteGet(
+      this.db,
+      `SELECT
+        COUNT(*) as total_queries,
+        AVG(candidate_count) as avg_candidate_count,
+        AVG(selected_count) as avg_selected_count,
+        CASE
+          WHEN SUM(candidate_count) > 0 THEN (SUM(selected_count) * 1.0 / SUM(candidate_count))
+          ELSE 0
+        END as selection_rate
+       FROM retrieval_traces`,
+      []
+    );
+    return {
+      totalQueries: Number(row?.total_queries || 0),
+      avgCandidateCount: Number(row?.avg_candidate_count || 0),
+      avgSelectedCount: Number(row?.avg_selected_count || 0),
+      selectionRate: Number(row?.selection_rate || 0)
+    };
+  }
   /**
    * Close database connection
    */
   async close() {
     sqliteClose(this.db);
   }
+  /**
+   * Get events grouped by turn_id for a session
+   * Returns turns ordered by first event timestamp (newest first)
+   */
+  async getSessionTurns(sessionId, options) {
+    await this.initialize();
+    const limit = options?.limit || 20;
+    const offset = options?.offset || 0;
+    const turnRows = sqliteAll(
+      this.db,
+      `SELECT turn_id, MIN(timestamp) as min_ts
+       FROM events
+       WHERE session_id = ? AND turn_id IS NOT NULL
+       GROUP BY turn_id
+       ORDER BY min_ts DESC
+       LIMIT ? OFFSET ?`,
+      [sessionId, limit, offset]
+    );
+    const turns = [];
+    for (const turnRow of turnRows) {
+      const events = await this.getEventsByTurn(turnRow.turn_id);
+      const promptEvent = events.find((e) => e.eventType === "user_prompt");
+      const toolEvents = events.filter((e) => e.eventType === "tool_observation");
+      const hasResponse = events.some((e) => e.eventType === "agent_response");
+      turns.push({
+        turnId: turnRow.turn_id,
+        events,
+        startedAt: toDateFromSQLite(turnRow.min_ts),
+        promptPreview: promptEvent ? promptEvent.content.slice(0, 200) + (promptEvent.content.length > 200 ? "..." : "") : "(no prompt)",
+        eventCount: events.length,
+        toolCount: toolEvents.length,
+        hasResponse
+      });
+    }
+    return turns;
+  }
+  /**
+   * Get all events for a specific turn_id
+   */
+  async getEventsByTurn(turnId) {
+    await this.initialize();
+    const rows = sqliteAll(
+      this.db,
+      `SELECT * FROM events WHERE turn_id = ? ORDER BY timestamp ASC`,
+      [turnId]
+    );
+    return rows.map(this.rowToEvent);
+  }
+  /**
+   * Count total turns for a session
+   */
+  async countSessionTurns(sessionId) {
+    await this.initialize();
+    const row = sqliteGet(
+      this.db,
+      `SELECT COUNT(DISTINCT turn_id) as count
+       FROM events
+       WHERE session_id = ? AND turn_id IS NOT NULL`,
+      [sessionId]
+    );
+    return row?.count || 0;
+  }
+  /**
+   * Migrate existing events: backfill turn_id for events that have turnId in metadata
+   * but no turn_id column value (for events stored before this migration)
+   */
+  async backfillTurnIds() {
+    await this.initialize();
+    const rows = sqliteAll(
+      this.db,
+      `SELECT id, metadata FROM events
+       WHERE turn_id IS NULL AND metadata IS NOT NULL AND metadata LIKE '%turnId%'`
+    );
+    let updated = 0;
+    for (const row of rows) {
+      try {
+        const metadata = JSON.parse(row.metadata);
+        if (metadata.turnId) {
+          sqliteRun(
+            this.db,
+            `UPDATE events SET turn_id = ? WHERE id = ?`,
+            [metadata.turnId, row.id]
+          );
+          updated++;
+        }
+      } catch {
+      }
+    }
+    return updated;
+  }
+  /**
+   * Delete all events for a session (for force reimport)
+   */
+  async deleteSessionEvents(sessionId) {
+    await this.initialize();
+    const events = sqliteAll(
+      this.db,
+      `SELECT id FROM events WHERE session_id = ?`,
+      [sessionId]
+    );
+    if (events.length === 0)
+      return 0;
+    const eventIds = events.map((e) => e.id);
+    const placeholders = eventIds.map(() => "?").join(",");
+    const ftsTriggersDropped = [];
+    for (const triggerName of ["events_fts_delete", "events_fts_update", "events_fts_insert"]) {
+      try {
+        sqliteRun(this.db, `DROP TRIGGER IF EXISTS ${triggerName}`);
+        ftsTriggersDropped.push(triggerName);
+      } catch {
+      }
+    }
+    for (const table of ["event_dedup", "memory_levels", "embedding_queue", "embedding_outbox", "vector_outbox"]) {
+      try {
+        sqliteRun(this.db, `DELETE FROM ${table} WHERE event_id IN (${placeholders})`, eventIds);
+      } catch {
+      }
+    }
+    const result = sqliteRun(this.db, `DELETE FROM events WHERE session_id = ?`, [sessionId]);
+    if (ftsTriggersDropped.length > 0) {
+      try {
+        sqliteRun(this.db, `INSERT INTO events_fts(events_fts) VALUES('rebuild')`);
+        sqliteRun(this.db, `CREATE TRIGGER IF NOT EXISTS events_fts_insert AFTER INSERT ON events BEGIN
+          INSERT INTO events_fts(rowid, content) VALUES (NEW.rowid, NEW.content);
+        END`);
+        sqliteRun(this.db, `CREATE TRIGGER IF NOT EXISTS events_fts_delete AFTER DELETE ON events BEGIN
+          INSERT INTO events_fts(events_fts, rowid, content) VALUES('delete', OLD.rowid, OLD.content);
+        END`);
+        sqliteRun(this.db, `CREATE TRIGGER IF NOT EXISTS events_fts_update AFTER UPDATE ON events BEGIN
+          INSERT INTO events_fts(events_fts, rowid, content) VALUES('delete', OLD.rowid, OLD.content);
+          INSERT INTO events_fts(rowid, content) VALUES (NEW.rowid, NEW.content);
+        END`);
+      } catch {
+      }
+    }
+    return result.changes || 0;
+  }
   /**
    * Convert database row to MemoryEvent
    */
@@ -1591,6 +2253,9 @@ var SQLiteEventStore = class {
     if (row.last_accessed_at !== void 0) {
       event.last_accessed_at = row.last_accessed_at;
     }
+    if (row.turn_id !== void 0 && row.turn_id !== null) {
+      event.turn_id = row.turn_id;
+    }
     return event;
   }
 };
@@ -1742,7 +2407,7 @@ var SyncWorker = class {
    * Sleep utility
    */
   sleep(ms) {
-    return new Promise((resolve2) => setTimeout(resolve2, ms));
+    return new Promise((resolve4) => setTimeout(resolve4, ms));
   }
   /**
    * Get sync statistics
@@ -1802,8 +2467,17 @@ var VectorStore = class {
       metadata: JSON.stringify(record.metadata || {})
     };
     if (!this.table) {
-      this.table = await this.db.createTable(this.tableName, [data]);
-    } else {
+      try {
+        this.table = await this.db.createTable(this.tableName, [data]);
+      } catch (e) {
+        if (e?.message?.includes("already exists")) {
+          this.table = await this.db.openTable(this.tableName);
+          await this.table.add([data]);
+        } else {
+          throw e;
+        }
+      }
+    } else {
       await this.table.add([data]);
     }
   }
@@ -1828,7 +2502,16 @@ var VectorStore = class {
       metadata: JSON.stringify(record.metadata || {})
     }));
     if (!this.table) {
-      this.table = await this.db.createTable(this.tableName, data);
+      try {
+        this.table = await this.db.createTable(this.tableName, data);
+      } catch (e) {
+        if (e?.message?.includes("already exists")) {
+          this.table = await this.db.openTable(this.tableName);
+          await this.table.add(data);
+        } else {
+          throw e;
+        }
+      }
     } else {
       await this.table.add(data);
     }
@@ -2268,7 +2951,20 @@ var DEFAULT_OPTIONS = {
   topK: 5,
   minScore: 0.7,
   maxTokens: 2e3,
-  includeSessionContext: true
+  includeSessionContext: true,
+  strategy: "auto",
+  rerankWithKeyword: true,
+  decayPolicy: {
+    enabled: true,
+    windowDays: 30,
+    maxPenalty: 0.15
+  },
+  graphHop: {
+    enabled: true,
+    maxHops: 1,
+    hopPenalty: 0.08
+  },
+  projectScopeMode: "global"
 };
 var Retriever = class {
   eventStore;
@@ -2278,6 +2974,7 @@ var Retriever = class {
   sharedStore;
   sharedVectorStore;
   graduation;
+  queryRewriter;
   constructor(eventStore, vectorStore, embedder, matcher, sharedOptions) {
     this.eventStore = eventStore;
     this.vectorStore = vectorStore;
@@ -2286,47 +2983,105 @@ var Retriever = class {
     this.sharedStore = sharedOptions?.sharedStore;
     this.sharedVectorStore = sharedOptions?.sharedVectorStore;
   }
-  /**
-   * Set graduation pipeline for access tracking
-   */
   setGraduationPipeline(graduation) {
     this.graduation = graduation;
   }
-  /**
-   * Set shared stores after construction
-   */
   setSharedStores(sharedStore, sharedVectorStore) {
     this.sharedStore = sharedStore;
     this.sharedVectorStore = sharedVectorStore;
   }
-  /**
-   * Retrieve relevant memories for a query
-   */
+  setQueryRewriter(rewriter) {
+    this.queryRewriter = rewriter;
+  }
   async retrieve(query, options = {}) {
     const opts = { ...DEFAULT_OPTIONS, ...options };
-    const queryEmbedding = await this.embedder.embed(query);
-    const searchResults = await this.vectorStore.search(queryEmbedding.vector, {
-      limit: opts.topK * 2,
-      // Get extra for filtering
+    const sessionFilter = opts.scope?.sessionId ?? opts.sessionId;
+    const fallbackTrace = [];
+    const fallbackEnabled = (opts.strategy ?? "auto") === "auto";
+    const primaryStrategy = opts.strategy === "auto" ? "fast" : opts.strategy || "fast";
+    let current = await this.runStage(query, {
+      strategy: primaryStrategy,
+      topK: opts.topK,
       minScore: opts.minScore,
-      sessionId: opts.sessionId
+      sessionId: sessionFilter,
+      scope: opts.scope,
+      rerankWithKeyword: opts.rerankWithKeyword !== false,
+      rerankWeights: opts.rerankWeights,
+      decayPolicy: opts.decayPolicy,
+      intentRewrite: opts.intentRewrite === true,
+      graphHop: opts.graphHop,
+      projectScopeMode: opts.projectScopeMode,
+      projectHash: opts.projectHash,
+      allowedProjectHashes: opts.allowedProjectHashes
     });
-    const matchResult = this.matcher.matchSearchResults(
-      searchResults,
-      (eventId) => this.getEventAgeDays(eventId)
-    );
-    const memories = await this.enrichResults(searchResults.slice(0, opts.topK), opts);
+    fallbackTrace.push(`stage:primary:${primaryStrategy}`);
+    if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results) && primaryStrategy !== "deep") {
+      current = await this.runStage(query, {
+        strategy: "deep",
+        topK: opts.topK,
+        minScore: opts.minScore,
+        sessionId: sessionFilter,
+        scope: opts.scope,
+        rerankWithKeyword: opts.rerankWithKeyword !== false,
+        rerankWeights: opts.rerankWeights,
+        decayPolicy: opts.decayPolicy,
+        graphHop: opts.graphHop,
+        projectScopeMode: opts.projectScopeMode,
+        projectHash: opts.projectHash,
+        allowedProjectHashes: opts.allowedProjectHashes
+      });
+      fallbackTrace.push("fallback:deep");
+    }
+    if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results)) {
+      current = await this.runStage(query, {
+        strategy: "deep",
+        topK: opts.topK,
+        minScore: Math.max(0.5, opts.minScore - 0.15),
+        sessionId: void 0,
+        scope: void 0,
+        rerankWithKeyword: true,
+        rerankWeights: opts.rerankWeights,
+        decayPolicy: opts.decayPolicy,
+        graphHop: opts.graphHop,
+        projectScopeMode: opts.projectScopeMode,
+        projectHash: opts.projectHash,
+        allowedProjectHashes: opts.allowedProjectHashes
+      });
+      fallbackTrace.push("fallback:scope-expanded");
+    }
+    if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results)) {
+      const summary = await this.buildSummaryFallback(query, opts.topK);
+      current = {
+        results: summary,
+        candidateResults: summary,
+        matchResult: this.matcher.matchSearchResults(summary, () => 0)
+      };
+      fallbackTrace.push("fallback:summary");
+    }
+    const memories = await this.enrichResults(current.results.slice(0, opts.topK), opts);
     const context = this.buildContext(memories, opts.maxTokens);
     return {
       memories,
-      matchResult,
+      matchResult: current.matchResult,
       totalTokens: this.estimateTokens(context),
-      context
+      context,
+      fallbackTrace,
+      selectedDebug: current.results.slice(0, opts.topK).map((r) => ({
+        eventId: r.eventId,
+        score: r.score,
+        semanticScore: r.semanticScore,
+        lexicalScore: r.lexicalScore,
+        recencyScore: r.recencyScore
+      })),
+      candidateDebug: (current.candidateResults || []).slice(0, Math.max(opts.topK * 3, 20)).map((r) => ({
+        eventId: r.eventId,
+        score: r.score,
+        semanticScore: r.semanticScore,
+        lexicalScore: r.lexicalScore,
+        recencyScore: r.recencyScore
+      }))
     };
   }
-  /**
-   * Retrieve with unified search (project + shared)
-   */
   async retrieveUnified(query, options = {}) {
     const projectResult = await this.retrieve(query, options);
     if (!options.includeShared || !this.sharedStore || !this.sharedVectorStore) {
@@ -2334,22 +3089,19 @@ var Retriever = class {
     }
     try {
       const queryEmbedding = await this.embedder.embed(query);
-      const sharedVectorResults = await this.sharedVectorStore.search(
-        queryEmbedding.vector,
-        {
-          limit: options.topK || 5,
-          minScore: options.minScore || 0.7,
-          excludeProjectHash: options.projectHash
-        }
-      );
+      const sharedVectorResults = await this.sharedVectorStore.search(queryEmbedding.vector, {
+        limit: options.topK || 5,
+        minScore: options.minScore || 0.7,
+        excludeProjectHash: options.projectHash
+      });
       const sharedMemories = [];
       for (const result of sharedVectorResults) {
         const entry = await this.sharedStore.get(result.entryId);
-        if (entry) {
-          if (!options.projectHash || entry.sourceProjectHash !== options.projectHash) {
-            sharedMemories.push(entry);
-            await this.sharedStore.recordUsage(entry.entryId);
-          }
+        if (!entry)
+          continue;
+        if (!options.projectHash || entry.sourceProjectHash !== options.projectHash) {
+          sharedMemories.push(entry);
+          await this.sharedStore.recordUsage(entry.entryId);
         }
       }
       const unifiedContext = this.buildUnifiedContext(projectResult, sharedMemories);
@@ -2364,50 +3116,243 @@ var Retriever = class {
       return projectResult;
     }
   }
-  /**
-   * Build unified context combining project and shared memories
-   */
-  buildUnifiedContext(projectResult, sharedMemories) {
-    let context = projectResult.context;
-    if (sharedMemories.length > 0) {
-      context += "\n\n## Cross-Project Knowledge\n\n";
-      for (const memory of sharedMemories.slice(0, 3)) {
-        context += `### ${memory.title}
-`;
-        if (memory.symptoms.length > 0) {
-          context += `**Symptoms:** ${memory.symptoms.join(", ")}
-`;
-        }
-        context += `**Root Cause:** ${memory.rootCause}
-`;
-        context += `**Solution:** ${memory.solution}
-`;
-        if (memory.technologies && memory.technologies.length > 0) {
-          context += `**Technologies:** ${memory.technologies.join(", ")}
-`;
+  async runStage(query, input) {
+    let initialResults = await this.searchByStrategy(query, {
+      strategy: input.strategy,
+      topK: input.topK,
+      minScore: input.minScore,
+      sessionId: input.sessionId
+    });
+    if (input.intentRewrite && input.strategy === "deep" && this.queryRewriter) {
+      const rewritten = (await this.queryRewriter(query))?.trim();
+      if (rewritten && rewritten !== query) {
+        const rewrittenResults = await this.searchByStrategy(rewritten, {
+          strategy: "deep",
+          topK: input.topK,
+          minScore: Math.max(0.5, input.minScore - 0.1),
+          sessionId: input.sessionId
+        });
+        initialResults = this.mergeResults(initialResults, rewrittenResults, input.topK * 3);
+      }
+    }
+    const expandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
+      maxHops: Math.max(1, input.graphHop?.maxHops ?? 1),
+      hopPenalty: Math.max(0, input.graphHop?.hopPenalty ?? 0.08),
+      limit: input.topK * 4
+    });
+    const rerankedResults = input.rerankWithKeyword ? this.rerankByKeywordOverlap(expandedResults, query, input.rerankWeights, input.decayPolicy) : expandedResults;
+    const filtered = await this.applyScopeFilters(rerankedResults, {
+      scope: input.scope,
+      projectScopeMode: input.projectScopeMode,
+      projectHash: input.projectHash,
+      allowedProjectHashes: input.allowedProjectHashes
+    });
+    const top = filtered.slice(0, input.topK);
+    const matchResult = this.matcher.matchSearchResults(top, () => 0);
+    return { results: top, candidateResults: filtered, matchResult };
+  }
+  mergeResults(primary, secondary, limit) {
+    const byId = /* @__PURE__ */ new Map();
+    for (const row of primary)
+      byId.set(row.eventId, row);
+    for (const row of secondary) {
+      const prev = byId.get(row.eventId);
+      if (!prev || row.score > prev.score) {
+        byId.set(row.eventId, row);
+      }
+    }
+    return [...byId.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+  async expandGraphHops(seeds, opts) {
+    const byId = /* @__PURE__ */ new Map();
+    for (const s of seeds)
+      byId.set(s.eventId, s);
+    let frontier = seeds.map((s) => ({ row: s, hop: 0 }));
+    for (let hop = 1; hop <= opts.maxHops; hop += 1) {
+      const next = [];
+      for (const f of frontier) {
+        const ev = await this.eventStore.getEvent(f.row.eventId);
+        if (!ev)
+          continue;
+        const rel = ev.metadata?.relatedEventIds ?? [];
+        const relatedIds = Array.isArray(rel) ? rel.filter((x) => typeof x === "string") : [];
+        for (const rid of relatedIds) {
+          if (byId.has(rid))
+            continue;
+          const target = await this.eventStore.getEvent(rid);
+          if (!target)
+            continue;
+          const score = Math.max(0, f.row.score - opts.hopPenalty * hop);
+          const row = {
+            id: `hop-${hop}-${rid}`,
+            eventId: target.id,
+            content: target.content,
+            score,
+            sessionId: target.sessionId,
+            eventType: target.eventType,
+            timestamp: target.timestamp.toISOString()
+          };
+          byId.set(row.eventId, row);
+          next.push({ row, hop });
+          if (byId.size >= opts.limit)
+            break;
         }
-        context += `_Confidence: ${(memory.confidence * 100).toFixed(0)}%_
-
-`;
+        if (byId.size >= opts.limit)
+          break;
       }
+      frontier = next;
+      if (frontier.length === 0 || byId.size >= opts.limit)
+        break;
     }
-    return context;
+    return [...byId.values()].sort((a, b) => b.score - a.score).slice(0, opts.limit);
+  }
+  shouldFallback(matchResult, results) {
+    if (results.length === 0)
+      return true;
+    if (matchResult.confidence === "none")
+      return true;
+    return false;
+  }
+  async buildSummaryFallback(query, topK) {
+    const recent = await this.eventStore.getRecentEvents(Math.max(topK * 6, 20));
+    const q = this.tokenize(query);
+    const ranked = recent.map((e) => ({ e, overlap: this.keywordOverlap(q, this.tokenize(e.content)) })).filter((r) => r.overlap > 0).sort((a, b) => b.overlap - a.overlap).slice(0, topK).map((row, idx) => ({
+      id: `summary-${row.e.id}`,
+      eventId: row.e.id,
+      content: row.e.content,
+      score: Math.max(0.25, 0.6 - idx * 0.05),
+      sessionId: row.e.sessionId,
+      eventType: row.e.eventType,
+      timestamp: row.e.timestamp.toISOString()
+    }));
+    return ranked;
+  }
+  async searchByStrategy(query, input) {
+    const strategy = input.strategy === "auto" ? "deep" : input.strategy;
+    if (strategy === "fast") {
+      const keyword = await this.searchByKeyword(query, {
+        limit: Math.max(5, input.topK * 3),
+        sessionId: input.sessionId
+      });
+      return keyword;
+    }
+    const queryEmbedding = await this.embedder.embed(query);
+    return this.vectorStore.search(queryEmbedding.vector, {
+      limit: Math.max(5, input.topK * 3),
+      minScore: input.minScore,
+      sessionId: input.sessionId
+    });
+  }
+  async searchByKeyword(query, input) {
+    if (this.eventStore.keywordSearch) {
+      const rows = await this.eventStore.keywordSearch(query, input.limit);
+      const filtered2 = input.sessionId ? rows.filter((r) => r.event.sessionId === input.sessionId) : rows;
+      return filtered2.map((row, idx) => ({
+        id: `kw-${row.event.id}`,
+        eventId: row.event.id,
+        content: row.event.content,
+        score: Math.max(0.4, 1 - idx * 0.04),
+        sessionId: row.event.sessionId,
+        eventType: row.event.eventType,
+        timestamp: row.event.timestamp.toISOString()
+      }));
+    }
+    const recent = await this.eventStore.getRecentEvents(input.limit * 4);
+    const tokens = this.tokenize(query);
+    const filtered = recent.filter((e) => input.sessionId ? e.sessionId === input.sessionId : true).map((e) => ({ e, overlap: this.keywordOverlap(tokens, this.tokenize(e.content)) })).filter((r) => r.overlap > 0).sort((a, b) => b.overlap - a.overlap).slice(0, input.limit);
+    return filtered.map((row, idx) => ({
+      id: `kw-fallback-${row.e.id}`,
+      eventId: row.e.id,
+      content: row.e.content,
+      score: Math.max(0.3, 0.9 - idx * 0.05),
+      sessionId: row.e.sessionId,
+      eventType: row.e.eventType,
+      timestamp: row.e.timestamp.toISOString()
+    }));
+  }
+  rerankByKeywordOverlap(results, query, weights, decayPolicy) {
+    const q = this.tokenize(query);
+    const now = Date.now();
+    const sw = Math.max(0, weights?.semantic ?? 0.7);
+    const lw = Math.max(0, weights?.lexical ?? 0.2);
+    const rw = Math.max(0, weights?.recency ?? 0.1);
+    const total = sw + lw + rw || 1;
+    const decayEnabled = decayPolicy?.enabled !== false;
+    const decayWindow = Math.max(1, decayPolicy?.windowDays ?? 30);
+    const decayMaxPenalty = Math.max(0, decayPolicy?.maxPenalty ?? 0.15);
+    return [...results].map((r) => {
+      const overlap = this.keywordOverlap(q, this.tokenize(r.content));
+      const recencyDays = Math.max(0, (now - new Date(r.timestamp).getTime()) / (1e3 * 60 * 60 * 24));
+      const recency = Math.max(0, 1 - recencyDays / decayWindow);
+      let blended = (r.score * sw + overlap * lw + recency * rw) / total;
+      if (decayEnabled && recencyDays > decayWindow && overlap < 0.5) {
+        const ageFactor = Math.min(1, (recencyDays - decayWindow) / decayWindow);
+        blended -= decayMaxPenalty * ageFactor;
+      }
+      return { ...r, score: Math.max(0, blended), semanticScore: r.score, lexicalScore: overlap, recencyScore: recency };
+    }).sort((a, b) => b.score - a.score);
+  }
+  async applyScopeFilters(results, options) {
+    const scope = options?.scope;
+    const projectScopeMode = options?.projectScopeMode ?? "global";
+    const allowedProjectHashes = new Set(
+      [options?.projectHash, ...options?.allowedProjectHashes || []].filter(
+        (value) => typeof value === "string" && value.length > 0
+      )
+    );
+    if (!scope && projectScopeMode === "global")
+      return results;
+    const normalizedIncludes = (scope?.contentIncludes || []).map((s) => s.toLowerCase());
+    const filtered = [];
+    for (const result of results) {
+      if (scope?.sessionId && result.sessionId !== scope.sessionId)
+        continue;
+      if (scope?.sessionIdPrefix && !result.sessionId.startsWith(scope.sessionIdPrefix))
+        continue;
+      if (scope?.eventTypes && scope.eventTypes.length > 0 && !scope.eventTypes.includes(result.eventType))
+        continue;
+      const event = await this.eventStore.getEvent(result.eventId);
+      if (!event)
+        continue;
+      if (scope?.canonicalKeyPrefix && !event.canonicalKey.startsWith(scope.canonicalKeyPrefix))
+        continue;
+      if (normalizedIncludes.length > 0) {
+        const lc = event.content.toLowerCase();
+        if (!normalizedIncludes.some((needle) => lc.includes(needle)))
+          continue;
+      }
+      if (scope?.metadata && !this.matchesMetadataScope(event.metadata, scope.metadata))
+        continue;
+      const projectHash = this.extractProjectHash(event.metadata);
+      filtered.push({ result, projectHash });
+    }
+    if (projectScopeMode === "global" || allowedProjectHashes.size === 0) {
+      return filtered.map((x) => x.result);
+    }
+    const projectMatched = filtered.filter((x) => x.projectHash && allowedProjectHashes.has(x.projectHash));
+    if (projectScopeMode === "strict") {
+      return projectMatched.map((x) => x.result);
+    }
+    return (projectMatched.length > 0 ? projectMatched : filtered).map((x) => x.result);
+  }
+  extractProjectHash(metadata) {
+    if (!metadata || typeof metadata !== "object")
+      return void 0;
+    const scope = metadata.scope;
+    if (!scope || typeof scope !== "object")
+      return void 0;
+    const project = scope.project;
+    if (!project || typeof project !== "object")
+      return void 0;
+    const hash = project.hash;
+    return typeof hash === "string" && hash.length > 0 ? hash : void 0;
   }
-  /**
-   * Retrieve memories from a specific session
-   */
   async retrieveFromSession(sessionId) {
     return this.eventStore.getSessionEvents(sessionId);
   }
-  /**
-   * Get recent memories across all sessions
-   */
   async retrieveRecent(limit = 100) {
     return this.eventStore.getRecentEvents(limit);
   }
-  /**
-   * Enrich search results with full event data
-   */
   async enrichResults(results, options) {
     const memories = [];
     for (const result of results) {
@@ -2415,27 +3360,16 @@ var Retriever = class {
       if (!event)
         continue;
       if (this.graduation) {
-        this.graduation.recordAccess(
-          event.id,
-          options.sessionId || "unknown",
-          result.score
-        );
+        this.graduation.recordAccess(event.id, options.sessionId || "unknown", result.score);
       }
       let sessionContext;
       if (options.includeSessionContext) {
         sessionContext = await this.getSessionContext(event.sessionId, event.id);
       }
-      memories.push({
-        event,
-        score: result.score,
-        sessionContext
-      });
+      memories.push({ event, score: result.score, sessionContext });
     }
     return memories;
   }
-  /**
-   * Get surrounding context from the same session
-   */
   async getSessionContext(sessionId, eventId) {
     const sessionEvents = await this.eventStore.getSessionEvents(sessionId);
     const eventIndex = sessionEvents.findIndex((e) => e.id === eventId);
@@ -2448,55 +3382,86 @@ var Retriever = class {
       return void 0;
     return contextEvents.filter((e) => e.id !== eventId).map((e) => `[${e.eventType}]: ${e.content.slice(0, 200)}...`).join("\n");
   }
-  /**
-   * Build context string from memories (respecting token limit)
-   */
+  buildUnifiedContext(projectResult, sharedMemories) {
+    let context = projectResult.context;
+    if (sharedMemories.length === 0)
+      return context;
+    context += "\n\n## Cross-Project Knowledge\n\n";
+    for (const memory of sharedMemories.slice(0, 3)) {
+      context += `### ${memory.title}
+`;
+      if (memory.symptoms.length > 0)
+        context += `**Symptoms:** ${memory.symptoms.join(", ")}
+`;
+      context += `**Root Cause:** ${memory.rootCause}
+`;
+      context += `**Solution:** ${memory.solution}
+`;
+      if (memory.technologies && memory.technologies.length > 0)
+        context += `**Technologies:** ${memory.technologies.join(", ")}
+`;
+      context += `_Confidence: ${(memory.confidence * 100).toFixed(0)}%_
+
+`;
+    }
+    return context;
+  }
   buildContext(memories, maxTokens) {
     const parts = [];
     let currentTokens = 0;
     for (const memory of memories) {
       const memoryText = this.formatMemory(memory);
       const memoryTokens = this.estimateTokens(memoryText);
-      if (currentTokens + memoryTokens > maxTokens) {
+      if (currentTokens + memoryTokens > maxTokens)
         break;
-      }
       parts.push(memoryText);
       currentTokens += memoryTokens;
     }
-    if (parts.length === 0) {
+    if (parts.length === 0)
       return "";
-    }
     return `## Relevant Memories
 
 ${parts.join("\n\n---\n\n")}`;
   }
-  /**
-   * Format a single memory for context
-   */
   formatMemory(memory) {
     const { event, score, sessionContext } = memory;
     const date = event.timestamp.toISOString().split("T")[0];
     let text = `**${event.eventType}** (${date}, score: ${score.toFixed(2)})
 ${event.content}`;
-    if (sessionContext) {
+    if (sessionContext)
       text += `
 
 _Context:_ ${sessionContext}`;
-    }
     return text;
   }
-  /**
-   * Estimate token count (rough approximation)
-   */
+  matchesMetadataScope(metadata, expected) {
+    if (!metadata)
+      return false;
+    return Object.entries(expected).every(([path10, value]) => {
+      const actual = path10.split(".").reduce((acc, key) => {
+        if (typeof acc !== "object" || acc === null)
+          return void 0;
+        return acc[key];
+      }, metadata);
+      return actual === value;
+    });
+  }
+  tokenize(text) {
+    return text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((t) => t.length >= 2).slice(0, 64);
+  }
+  keywordOverlap(a, b) {
+    if (a.length === 0 || b.length === 0)
+      return 0;
+    const bs = new Set(b);
+    let hit = 0;
+    for (const t of a)
+      if (bs.has(t))
+        hit += 1;
+    return hit / a.length;
+  }
   estimateTokens(text) {
     return Math.ceil(text.length / 4);
   }
-  /**
-   * Get event age in days (for recency scoring)
-   */
-  getEventAgeDays(eventId) {
-    return 0;
-  }
 };
 function createRetriever(eventStore, vectorStore, embedder, matcher) {
   return new Retriever(eventStore, vectorStore, embedder, matcher);
@@ -3786,6 +4751,59 @@ var ConsolidatedStore = class {
       [memoryId]
     );
   }
+  /**
+   * Create a long-term rule promoted from stable summaries
+   */
+  async createRule(input) {
+    const ruleId = randomUUID6();
+    await dbRun(
+      this.db,
+      `INSERT INTO consolidated_rules
+        (rule_id, rule, topics, source_memory_ids, source_events, confidence, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)`,
+      [
+        ruleId,
+        input.rule,
+        JSON.stringify(input.topics),
+        JSON.stringify(input.sourceMemoryIds),
+        JSON.stringify(input.sourceEvents),
+        input.confidence
+      ]
+    );
+    return ruleId;
+  }
+  async getRules(options) {
+    const limit = options?.limit || 100;
+    const rows = await dbAll(
+      this.db,
+      `SELECT * FROM consolidated_rules ORDER BY confidence DESC, created_at DESC LIMIT ?`,
+      [limit]
+    );
+    return rows.map((row) => ({
+      ruleId: row.rule_id,
+      rule: row.rule,
+      topics: JSON.parse(row.topics || "[]"),
+      sourceMemoryIds: JSON.parse(row.source_memory_ids || "[]"),
+      sourceEvents: JSON.parse(row.source_events || "[]"),
+      confidence: Number(row.confidence ?? 0.5),
+      createdAt: toDate(row.created_at) || /* @__PURE__ */ new Date()
+    }));
+  }
+  async countRules() {
+    const result = await dbAll(
+      this.db,
+      `SELECT COUNT(*) as count FROM consolidated_rules`
+    );
+    return result[0]?.count || 0;
+  }
+  async hasRuleForSourceMemory(memoryId) {
+    const rows = await dbAll(
+      this.db,
+      `SELECT COUNT(*) as count FROM consolidated_rules WHERE source_memory_ids LIKE ?`,
+      [`%"${memoryId}"%`]
+    );
+    return (rows[0]?.count || 0) > 0;
+  }
   /**
    * Get count of consolidated memories
    */
@@ -3935,7 +4953,14 @@ var ConsolidationWorker = class {
    * Force a consolidation run (manual trigger)
    */
   async forceRun() {
-    return await this.consolidate();
+    const out = await this.consolidateWithReport();
+    return out.consolidatedCount;
+  }
+  /**
+   * Force a consolidation run and return metrics report
+   */
+  async forceRunWithReport() {
+    return this.consolidateWithReport();
   }
   /**
    * Schedule the next consolidation check
@@ -3975,12 +5000,21 @@ var ConsolidationWorker = class {
    * Perform consolidation
    */
   async consolidate() {
+    const out = await this.consolidateWithReport();
+    return out.consolidatedCount;
+  }
+  async consolidateWithReport() {
     const workingSet = await this.workingSetStore.get();
     if (workingSet.recentEvents.length < 3) {
-      return 0;
+      return {
+        consolidatedCount: 0,
+        promotedRuleCount: 0,
+        report: this.buildCostQualityReport(workingSet.recentEvents, [], 0)
+      };
     }
     const groups = this.groupByTopic(workingSet.recentEvents);
     let consolidatedCount = 0;
+    const createdMemoryIds = [];
     for (const group of groups) {
       if (group.events.length < 3)
         continue;
@@ -3989,14 +5023,16 @@ var ConsolidationWorker = class {
       if (alreadyConsolidated)
         continue;
       const summary = await this.summarize(group);
-      await this.consolidatedStore.create({
+      const memoryId = await this.consolidatedStore.create({
         summary,
         topics: group.topics,
         sourceEvents: eventIds,
         confidence: this.calculateConfidence(group)
       });
+      createdMemoryIds.push(memoryId);
       consolidatedCount++;
     }
+    const promotedRuleCount = await this.promoteStableSummariesToRules(createdMemoryIds);
     if (consolidatedCount > 0) {
       const consolidatedEventIds = groups.filter((g) => g.events.length >= 3).flatMap((g) => g.events.map((e) => e.id));
       const oldEventIds = consolidatedEventIds.filter((id) => {
@@ -4010,7 +5046,61 @@ var ConsolidationWorker = class {
         await this.workingSetStore.prune(oldEventIds);
       }
     }
-    return consolidatedCount;
+    const report = this.buildCostQualityReport(workingSet.recentEvents, groups, consolidatedCount);
+    return { consolidatedCount, promotedRuleCount, report };
+  }
+  async promoteStableSummariesToRules(memoryIds) {
+    let promoted = 0;
+    for (const memoryId of memoryIds) {
+      const memory = await this.consolidatedStore.get(memoryId);
+      if (!memory)
+        continue;
+      if (memory.confidence < 0.55)
+        continue;
+      if (memory.sourceEvents.length < 4)
+        continue;
+      const exists = await this.consolidatedStore.hasRuleForSourceMemory(memoryId);
+      if (exists)
+        continue;
+      const rule = this.buildRuleFromSummary(memory.summary, memory.topics);
+      if (!rule)
+        continue;
+      await this.consolidatedStore.createRule({
+        rule,
+        topics: memory.topics,
+        sourceMemoryIds: [memory.memoryId],
+        sourceEvents: memory.sourceEvents,
+        confidence: Math.min(1, memory.confidence + 0.08)
+      });
+      promoted++;
+    }
+    return promoted;
+  }
+  buildRuleFromSummary(summary, topics) {
+    const lines = summary.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).filter((l) => !l.toLowerCase().startsWith("topics:"));
+    const bullet = lines.find((l) => l.startsWith("- "))?.replace(/^-\s*/, "");
+    const seed = bullet || lines[0];
+    if (!seed || seed.length < 8)
+      return null;
+    const topicPrefix = topics.length > 0 ? `[${topics.slice(0, 2).join(", ")}] ` : "";
+    return `${topicPrefix}${seed}`;
+  }
+  buildCostQualityReport(events, groups, consolidatedCount) {
+    const beforeTokenEstimate = events.reduce((acc, e) => acc + this.estimateTokens(e.content), 0);
+    const afterSummaries = groups.filter((g) => g.events.length >= 3).slice(0, Math.max(consolidatedCount, 1));
+    const afterTokenEstimate = afterSummaries.length > 0 ? afterSummaries.reduce((acc, g) => acc + this.estimateTokens(this.ruleBasedSummary(g)), 0) : beforeTokenEstimate;
+    const reductionRatio = beforeTokenEstimate > 0 ? Math.max(0, (beforeTokenEstimate - afterTokenEstimate) / beforeTokenEstimate) : 0;
+    const qualityGuardPassed = consolidatedCount === 0 ? true : groups.filter((g) => g.events.length >= 3).every((g) => this.calculateConfidence(g) >= 0.55);
+    return {
+      beforeTokenEstimate,
+      afterTokenEstimate,
+      reductionRatio,
+      qualityGuardPassed,
+      details: `groups=${groups.length}, consolidated=${consolidatedCount}`
+    };
+  }
+  estimateTokens(text) {
+    return Math.ceil((text || "").length / 4);
   }
   /**
    * Check if consolidation should run
@@ -4570,13 +5660,185 @@ function createGraduationWorker(eventStore, graduation, config) {
   );
 }
 
+// src/core/md-mirror.ts
+import * as fs3 from "node:fs";
+import * as path2 from "node:path";
+function sanitizeSegment2(input, fallback) {
+  const v = (input || "").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return v || fallback;
+}
+function getAtPath(obj, dotted) {
+  if (!obj)
+    return void 0;
+  return dotted.split(".").reduce((acc, key) => {
+    if (!acc || typeof acc !== "object")
+      return void 0;
+    return acc[key];
+  }, obj);
+}
+function buildMirrorPath2(rootDir, event) {
+  const meta = event.metadata;
+  const namespaceRaw = getAtPath(meta, "namespace") ?? getAtPath(meta, "scope.namespace") ?? event.eventType;
+  const namespace = sanitizeSegment2(typeof namespaceRaw === "string" ? namespaceRaw : void 0, "general");
+  const categoryRaw = getAtPath(meta, "categoryPath") ?? getAtPath(meta, "scope.categoryPath");
+  const categoryPath = Array.isArray(categoryRaw) && categoryRaw.length > 0 ? categoryRaw.map((x) => sanitizeSegment2(typeof x === "string" ? x : void 0, "uncategorized")) : ["uncategorized"];
+  const d = event.timestamp;
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return path2.join(rootDir, "memory", namespace, ...categoryPath, `${yyyy}-${mm}-${dd}.md`);
+}
+var MarkdownMirror2 = class {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+  }
+  async append(event, eventId) {
+    const out = buildMirrorPath2(this.rootDir, event);
+    fs3.mkdirSync(path2.dirname(out), { recursive: true });
+    const lines = [
+      "",
+      `## ${event.timestamp.toISOString()} | ${eventId ?? "pending-id"}`,
+      `- type: ${event.eventType}`,
+      `- session: ${event.sessionId}`,
+      event.content
+    ];
+    await fs3.promises.appendFile(out, lines.join("\n"), "utf8");
+    await this.refreshIndex();
+  }
+  async refreshIndex() {
+    const memoryRoot = path2.join(this.rootDir, "memory");
+    await fs3.promises.mkdir(memoryRoot, { recursive: true });
+    const files = [];
+    await this.walk(memoryRoot, files);
+    const mdFiles = files.filter((f) => f.endsWith(".md")).map((f) => path2.relative(this.rootDir, f)).filter((rel) => rel !== path2.join("memory", "_index.md")).sort();
+    const index = [
+      "# Memory Index",
+      "",
+      "Generated automatically by MarkdownMirror.",
+      "",
+      ...mdFiles.map((rel) => `- ${rel}`),
+      ""
+    ].join("\n");
+    await fs3.promises.writeFile(path2.join(memoryRoot, "_index.md"), index, "utf8");
+  }
+  async walk(dir, out) {
+    const entries = await fs3.promises.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = path2.join(dir, e.name);
+      if (e.isDirectory()) {
+        await this.walk(full, out);
+      } else {
+        out.push(full);
+      }
+    }
+  }
+};
+
+// src/core/ingest-interceptor.ts
+var IngestInterceptorRegistry = class {
+  before = [];
+  after = [];
+  onError = [];
+  registerBefore(interceptor) {
+    this.before.push(interceptor);
+    return () => {
+      this.before = this.before.filter((i) => i !== interceptor);
+    };
+  }
+  registerAfter(interceptor) {
+    this.after.push(interceptor);
+    return () => {
+      this.after = this.after.filter((i) => i !== interceptor);
+    };
+  }
+  registerOnError(interceptor) {
+    this.onError.push(interceptor);
+    return () => {
+      this.onError = this.onError.filter((i) => i !== interceptor);
+    };
+  }
+  async run(stage, context) {
+    const interceptors = stage === "before" ? this.before : stage === "after" ? this.after : this.onError;
+    for (const interceptor of interceptors) {
+      await interceptor({ ...context, stage });
+    }
+  }
+};
+function mergeHierarchicalMetadata(base, patch) {
+  if (!base && !patch)
+    return void 0;
+  if (!base)
+    return patch;
+  if (!patch)
+    return base;
+  const result = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    const current = result[key];
+    if (typeof current === "object" && current !== null && !Array.isArray(current) && typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[key] = mergeHierarchicalMetadata(
+        current,
+        value
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/core/tag-taxonomy.ts
+var TAG_NAMESPACES = {
+  SYSTEM: "sys:",
+  QUALITY: "q:",
+  PROJECT: "proj:",
+  TOPIC: "topic:",
+  TEMPORAL: "t:",
+  USER: "user:",
+  AGENT: "agent:"
+};
+var VALID_TAG_NAMESPACES = new Set(Object.values(TAG_NAMESPACES));
+function parseTag(tag) {
+  const value = (tag || "").trim();
+  const idx = value.indexOf(":");
+  if (idx <= 0)
+    return { value };
+  const namespace = `${value.slice(0, idx)}:`;
+  const tagValue = value.slice(idx + 1);
+  if (!tagValue)
+    return { value };
+  return { namespace, value: tagValue };
+}
+function validateTag(tag) {
+  const normalized = (tag || "").trim();
+  if (!normalized)
+    return false;
+  const { namespace } = parseTag(normalized);
+  if (!namespace)
+    return true;
+  return VALID_TAG_NAMESPACES.has(namespace);
+}
+function normalizeTags(tags) {
+  if (!Array.isArray(tags))
+    return [];
+  const dedup = /* @__PURE__ */ new Set();
+  for (const item of tags) {
+    if (typeof item !== "string")
+      continue;
+    const normalized = item.trim();
+    if (!validateTag(normalized))
+      continue;
+    dedup.add(normalized);
+  }
+  return [...dedup];
+}
+
 // src/services/memory-service.ts
 function normalizePath(projectPath) {
-  const expanded = projectPath.startsWith("~") ? path.join(os.homedir(), projectPath.slice(1)) : projectPath;
+  const expanded = projectPath.startsWith("~") ? path3.join(os.homedir(), projectPath.slice(1)) : projectPath;
   try {
-    return fs.realpathSync(expanded);
+    return fs4.realpathSync(expanded);
   } catch {
-    return path.resolve(expanded);
+    return path3.resolve(expanded);
   }
 }
 function hashProjectPath(projectPath) {
@@ -4585,10 +5847,46 @@ function hashProjectPath(projectPath) {
 }
 function getProjectStoragePath(projectPath) {
   const hash = hashProjectPath(projectPath);
-  return path.join(os.homedir(), ".claude-code", "memory", "projects", hash);
+  return path3.join(os.homedir(), ".claude-code", "memory", "projects", hash);
+}
+var REGISTRY_PATH = path3.join(os.homedir(), ".claude-code", "memory", "session-registry.json");
+var SHARED_STORAGE_PATH = path3.join(os.homedir(), ".claude-code", "memory", "shared");
+function loadSessionRegistry() {
+  try {
+    if (fs4.existsSync(REGISTRY_PATH)) {
+      const data = fs4.readFileSync(REGISTRY_PATH, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error) {
+    console.error("Failed to load session registry:", error);
+  }
+  return { version: 1, sessions: {} };
+}
+function saveSessionRegistry(registry) {
+  const dir = path3.dirname(REGISTRY_PATH);
+  if (!fs4.existsSync(dir)) {
+    fs4.mkdirSync(dir, { recursive: true });
+  }
+  const tempPath = REGISTRY_PATH + ".tmp";
+  fs4.writeFileSync(tempPath, JSON.stringify(registry, null, 2));
+  fs4.renameSync(tempPath, REGISTRY_PATH);
+}
+function registerSession(sessionId, projectPath) {
+  const registry = loadSessionRegistry();
+  registry.sessions[sessionId] = {
+    projectPath: normalizePath(projectPath),
+    projectHash: hashProjectPath(projectPath),
+    registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const entries = Object.entries(registry.sessions);
+  if (entries.length > 1e3) {
+    const sorted = entries.sort(
+      (a, b) => new Date(b[1].registeredAt).getTime() - new Date(a[1].registeredAt).getTime()
+    );
+    registry.sessions = Object.fromEntries(sorted.slice(0, 1e3));
+  }
+  saveSessionRegistry(registry);
 }
-var REGISTRY_PATH = path.join(os.homedir(), ".claude-code", "memory", "session-registry.json");
-var SHARED_STORAGE_PATH = path.join(os.homedir(), ".claude-code", "memory", "shared");
 var MemoryService = class {
   // Primary store: SQLite (WAL mode) - for hooks, always available
   sqliteStore;
@@ -4603,6 +5901,7 @@ var MemoryService = class {
   vectorWorker = null;
   graduationWorker = null;
   initialized = false;
+  ingestInterceptors = new IngestInterceptorRegistry();
   // Endless Mode components
   workingSetStore = null;
   consolidatedStore = null;
@@ -4616,20 +5915,27 @@ var MemoryService = class {
   sharedPromoter = null;
   sharedStoreConfig = null;
   projectHash = null;
+  projectPath = null;
   readOnly;
   lightweightMode;
+  mdMirror;
   constructor(config) {
     const storagePath = this.expandPath(config.storagePath);
     this.readOnly = config.readOnly ?? false;
     this.lightweightMode = config.lightweightMode ?? false;
-    if (!this.readOnly && !fs.existsSync(storagePath)) {
-      fs.mkdirSync(storagePath, { recursive: true });
+    this.mdMirror = new MarkdownMirror2(process.cwd());
+    if (!this.readOnly && !fs4.existsSync(storagePath)) {
+      fs4.mkdirSync(storagePath, { recursive: true });
     }
     this.projectHash = config.projectHash || null;
+    this.projectPath = config.projectPath || null;
     this.sharedStoreConfig = config.sharedStoreConfig ?? { enabled: true };
     this.sqliteStore = new SQLiteEventStore(
-      path.join(storagePath, "events.sqlite"),
-      { readonly: this.readOnly }
+      path3.join(storagePath, "events.sqlite"),
+      {
+        readonly: this.readOnly,
+        markdownMirrorRoot: storagePath
+      }
     );
     const analyticsEnabled = config.analyticsEnabled ?? this.readOnly;
     if (!analyticsEnabled) {
@@ -4637,7 +5943,7 @@ var MemoryService = class {
     } else if (this.readOnly) {
       try {
         this.analyticsStore = new EventStore(
-          path.join(storagePath, "analytics.duckdb"),
+          path3.join(storagePath, "analytics.duckdb"),
           { readOnly: true }
         );
       } catch {
@@ -4645,11 +5951,11 @@ var MemoryService = class {
       }
     } else {
       this.analyticsStore = new EventStore(
-        path.join(storagePath, "analytics.duckdb"),
+        path3.join(storagePath, "analytics.duckdb"),
         { readOnly: false }
       );
     }
-    this.vectorStore = new VectorStore(path.join(storagePath, "vectors"));
+    this.vectorStore = new VectorStore(path3.join(storagePath, "vectors"));
     this.embedder = config.embeddingModel ? new Embedder(config.embeddingModel) : getDefaultEmbedder();
     this.matcher = getDefaultMatcher();
     this.retriever = createRetriever(
@@ -4659,6 +5965,7 @@ var MemoryService = class {
       this.embedder,
       this.matcher
     );
+    this.retriever.setQueryRewriter((q) => this.rewriteQueryIntent(q));
     this.graduation = createGraduationPipeline(this.sqliteStore);
   }
   /**
@@ -4718,16 +6025,16 @@ var MemoryService = class {
    */
   async initializeSharedStore() {
     const sharedPath = this.sharedStoreConfig?.sharedStoragePath ? this.expandPath(this.sharedStoreConfig.sharedStoragePath) : SHARED_STORAGE_PATH;
-    if (!fs.existsSync(sharedPath)) {
-      fs.mkdirSync(sharedPath, { recursive: true });
+    if (!fs4.existsSync(sharedPath)) {
+      fs4.mkdirSync(sharedPath, { recursive: true });
     }
     this.sharedEventStore = createSharedEventStore(
-      path.join(sharedPath, "shared.duckdb")
+      path3.join(sharedPath, "shared.duckdb")
     );
     await this.sharedEventStore.initialize();
     this.sharedStore = createSharedStore(this.sharedEventStore);
     this.sharedVectorStore = createSharedVectorStore(
-      path.join(sharedPath, "vectors")
+      path3.join(sharedPath, "vectors")
     );
     await this.sharedVectorStore.initialize();
     this.sharedPromoter = createSharedPromoter(
@@ -4738,18 +6045,98 @@ var MemoryService = class {
     );
     this.retriever.setSharedStores(this.sharedStore, this.sharedVectorStore);
   }
-  /**
-   * Start a new session
-   */
-  async startSession(sessionId, projectPath) {
-    await this.initialize();
-    await this.sqliteStore.upsertSession({
-      id: sessionId,
-      startedAt: /* @__PURE__ */ new Date(),
-      projectPath
-    });
+  registerIngestBefore(interceptor) {
+    return this.ingestInterceptors.registerBefore(interceptor);
   }
-  /**
+  registerIngestAfter(interceptor) {
+    return this.ingestInterceptors.registerAfter(interceptor);
+  }
+  registerIngestOnError(interceptor) {
+    return this.ingestInterceptors.registerOnError(interceptor);
+  }
+  async ingestWithInterceptors(operation, input, onSuccess) {
+    const normalizedInput = {
+      ...input,
+      metadata: mergeHierarchicalMetadata(
+        {
+          ingest: {
+            operation,
+            pipeline: "default",
+            ts: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          ...this.projectHash ? {
+            scope: {
+              project: {
+                hash: this.projectHash,
+                ...this.projectPath ? { path: this.projectPath } : {}
+              }
+            },
+            tags: [`proj:${this.projectHash}`]
+          } : {}
+        },
+        input.metadata
+      )
+    };
+    if (this.projectHash && normalizedInput.metadata) {
+      const meta = normalizedInput.metadata;
+      const currentTags = Array.isArray(meta.tags) ? meta.tags.filter((x) => typeof x === "string") : [];
+      const projectTag = `proj:${this.projectHash}`;
+      if (!currentTags.includes(projectTag)) {
+        meta.tags = [...currentTags, projectTag];
+      }
+    }
+    if (normalizedInput.metadata) {
+      const meta = normalizedInput.metadata;
+      const normalizedTags = normalizeTags(meta.tags);
+      if (normalizedTags.length > 0) {
+        meta.tags = normalizedTags;
+      }
+    }
+    await this.ingestInterceptors.run("before", {
+      operation,
+      sessionId: normalizedInput.sessionId,
+      event: normalizedInput
+    });
+    try {
+      const result = await this.sqliteStore.append(normalizedInput);
+      if (result.success && !result.isDuplicate) {
+        if (onSuccess) {
+          await onSuccess(result.eventId);
+        }
+        try {
+          await this.mdMirror.append(normalizedInput, result.eventId);
+        } catch {
+        }
+      }
+      await this.ingestInterceptors.run("after", {
+        operation,
+        sessionId: normalizedInput.sessionId,
+        event: normalizedInput
+      });
+      return result;
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error));
+      await this.ingestInterceptors.run("error", {
+        operation,
+        sessionId: normalizedInput.sessionId,
+        event: normalizedInput,
+        error: normalizedError
+      });
+      throw error;
+    }
+  }
+  /**
+   * Start a new session
+   */
+  async startSession(sessionId, projectPath) {
+    await this.initialize();
+    await this.sqliteStore.upsertSession({
+      id: sessionId,
+      startedAt: /* @__PURE__ */ new Date(),
+      projectPath
+    });
+  }
+  /**
    * End a session
    */
   async endSession(sessionId, summary) {
@@ -4765,50 +6152,57 @@ var MemoryService = class {
    */
   async storeUserPrompt(sessionId, content, metadata) {
     await this.initialize();
-    const result = await this.sqliteStore.append({
-      eventType: "user_prompt",
-      sessionId,
-      timestamp: /* @__PURE__ */ new Date(),
-      content,
-      metadata
-    });
-    if (result.success && !result.isDuplicate) {
-      await this.sqliteStore.enqueueForEmbedding(result.eventId, content);
-    }
-    return result;
+    return this.ingestWithInterceptors(
+      "user_prompt",
+      {
+        eventType: "user_prompt",
+        sessionId,
+        timestamp: /* @__PURE__ */ new Date(),
+        content,
+        metadata
+      },
+      async (eventId) => {
+        await this.sqliteStore.enqueueForEmbedding(eventId, content);
+      }
+    );
   }
   /**
    * Store an agent response
    */
   async storeAgentResponse(sessionId, content, metadata) {
     await this.initialize();
-    const result = await this.sqliteStore.append({
-      eventType: "agent_response",
-      sessionId,
-      timestamp: /* @__PURE__ */ new Date(),
-      content,
-      metadata
-    });
-    if (result.success && !result.isDuplicate) {
-      await this.sqliteStore.enqueueForEmbedding(result.eventId, content);
-    }
-    return result;
+    return this.ingestWithInterceptors(
+      "agent_response",
+      {
+        eventType: "agent_response",
+        sessionId,
+        timestamp: /* @__PURE__ */ new Date(),
+        content,
+        metadata
+      },
+      async (eventId) => {
+        await this.sqliteStore.enqueueForEmbedding(eventId, content);
+      }
+    );
   }
   /**
    * Store a session summary
    */
-  async storeSessionSummary(sessionId, summary) {
+  async storeSessionSummary(sessionId, summary, metadata) {
     await this.initialize();
-    const result = await this.sqliteStore.append({
-      eventType: "session_summary",
-      sessionId,
-      timestamp: /* @__PURE__ */ new Date(),
-      content: summary
-    });
-    if (result.success && !result.isDuplicate) {
-      await this.sqliteStore.enqueueForEmbedding(result.eventId, summary);
-    }
-    return result;
+    return this.ingestWithInterceptors(
+      "session_summary",
+      {
+        eventType: "session_summary",
+        sessionId,
+        timestamp: /* @__PURE__ */ new Date(),
+        content: summary,
+        metadata
+      },
+      async (eventId) => {
+        await this.sqliteStore.enqueueForEmbedding(eventId, summary);
+      }
+    );
   }
   /**
    * Store a tool observation
@@ -4816,39 +6210,182 @@ var MemoryService = class {
   async storeToolObservation(sessionId, payload) {
     await this.initialize();
     const content = JSON.stringify(payload);
-    const result = await this.sqliteStore.append({
-      eventType: "tool_observation",
-      sessionId,
-      timestamp: /* @__PURE__ */ new Date(),
-      content,
-      metadata: {
-        toolName: payload.toolName,
-        success: payload.success
+    const turnId = payload.metadata?.turnId;
+    return this.ingestWithInterceptors(
+      "tool_observation",
+      {
+        eventType: "tool_observation",
+        sessionId,
+        timestamp: /* @__PURE__ */ new Date(),
+        content,
+        metadata: {
+          toolName: payload.toolName,
+          success: payload.success,
+          ...turnId ? { turnId } : {}
+        }
+      },
+      async (eventId) => {
+        const embeddingContent = createToolObservationEmbedding(
+          payload.toolName,
+          payload.metadata || {},
+          payload.success
+        );
+        await this.sqliteStore.enqueueForEmbedding(eventId, embeddingContent);
       }
-    });
-    if (result.success && !result.isDuplicate) {
-      const embeddingContent = createToolObservationEmbedding(
-        payload.toolName,
-        payload.metadata || {},
-        payload.success
-      );
-      await this.sqliteStore.enqueueForEmbedding(result.eventId, embeddingContent);
-    }
-    return result;
+    );
   }
   /**
    * Retrieve relevant memories for a query
    */
   async retrieveMemories(query, options) {
     await this.initialize();
+    const rerankWeights = await this.getRerankWeights(options?.adaptiveRerank === true);
+    let result;
     if (options?.includeShared && this.sharedStore) {
-      return this.retriever.retrieveUnified(query, {
+      result = await this.retriever.retrieveUnified(query, {
         ...options,
+        intentRewrite: options?.intentRewrite === true,
+        rerankWeights,
         includeShared: true,
-        projectHash: this.projectHash || void 0
+        projectHash: this.projectHash || void 0,
+        projectScopeMode: options?.projectScopeMode ?? (this.projectHash ? "strict" : "global"),
+        allowedProjectHashes: options?.allowedProjectHashes
+      });
+    } else {
+      result = await this.retriever.retrieve(query, {
+        ...options,
+        intentRewrite: options?.intentRewrite === true,
+        rerankWeights,
+        projectHash: this.projectHash || void 0,
+        projectScopeMode: options?.projectScopeMode ?? (this.projectHash ? "strict" : "global"),
+        allowedProjectHashes: options?.allowedProjectHashes
+      });
+    }
+    try {
+      const selectedEventIds = result.memories.map((m) => m.event.id);
+      const selectedDetails = (result.selectedDebug || []).map((d) => ({
+        eventId: d.eventId,
+        score: d.score,
+        semanticScore: d.semanticScore,
+        lexicalScore: d.lexicalScore,
+        recencyScore: d.recencyScore
+      }));
+      const candidateDetails = (result.candidateDebug || []).map((d) => ({
+        eventId: d.eventId,
+        score: d.score,
+        semanticScore: d.semanticScore,
+        lexicalScore: d.lexicalScore,
+        recencyScore: d.recencyScore
+      }));
+      const candidateEventIds = candidateDetails.length > 0 ? candidateDetails.map((d) => d.eventId) : selectedEventIds;
+      await this.sqliteStore.recordRetrievalTrace({
+        sessionId: options?.sessionId,
+        projectHash: this.projectHash || void 0,
+        queryText: query,
+        strategy: options?.strategy || "auto",
+        candidateEventIds,
+        selectedEventIds,
+        candidateDetails,
+        selectedDetails,
+        confidence: result.matchResult.confidence,
+        fallbackTrace: result.fallbackTrace || []
+      });
+    } catch {
+    }
+    return result;
+  }
+  getConfiguredRerankWeights() {
+    const semantic = Number(process.env.MEMORY_RERANK_WEIGHT_SEMANTIC ?? "");
+    const lexical = Number(process.env.MEMORY_RERANK_WEIGHT_LEXICAL ?? "");
+    const recency = Number(process.env.MEMORY_RERANK_WEIGHT_RECENCY ?? "");
+    const allFinite = [semantic, lexical, recency].every((v) => Number.isFinite(v));
+    if (!allFinite)
+      return void 0;
+    const nonNegative = [semantic, lexical, recency].every((v) => v >= 0);
+    const total = semantic + lexical + recency;
+    if (!nonNegative || total <= 0)
+      return void 0;
+    return {
+      semantic: semantic / total,
+      lexical: lexical / total,
+      recency: recency / total
+    };
+  }
+  async getRerankWeights(adaptive) {
+    const configured = this.getConfiguredRerankWeights();
+    if (configured)
+      return configured;
+    if (adaptive)
+      return this.getAdaptiveRerankWeights();
+    return void 0;
+  }
+  async rewriteQueryIntent(query) {
+    if (process.env.MEMORY_INTENT_REWRITE_ENABLED !== "1")
+      return null;
+    const apiUrl = process.env.COMPANY_STOCK_API_URL || process.env.COMPANY_INT_API_URL;
+    if (!apiUrl)
+      return null;
+    const controller = new AbortController();
+    const timeoutMs = Number(process.env.MEMORY_INTENT_REWRITE_TIMEOUT_MS || 5e3);
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const prompt = [
+        "Rewrite user query for memory retrieval intent expansion.",
+        "Return plain text only, one line, no markdown.",
+        `Query: ${query}`
+      ].join("\n");
+      const res = await fetch(apiUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "*/*",
+          Origin: process.env.COMPANY_INT_ORIGIN || "http://company-int.aplusai.ai",
+          Referer: process.env.COMPANY_INT_REFERER || "http://company-int.aplusai.ai/"
+        },
+        body: JSON.stringify({
+          question: prompt,
+          company_name: null,
+          conversation_id: null
+        }),
+        signal: controller.signal
       });
+      const text = (await res.text()).trim();
+      if (!text)
+        return null;
+      const oneLine = text.replace(/^data:\s*/gm, "").split(/\r?\n/).map((x) => x.trim()).filter(Boolean).join(" ").slice(0, 240);
+      if (!oneLine || oneLine.toLowerCase() === query.toLowerCase())
+        return null;
+      return oneLine;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  async getAdaptiveRerankWeights() {
+    try {
+      const s = await this.sqliteStore.getHelpfulnessStats();
+      if (s.totalEvaluated < 20)
+        return void 0;
+      let semantic = 0.7;
+      let lexical = 0.2;
+      let recency = 0.1;
+      if (s.avgScore < 0.45) {
+        semantic -= 0.1;
+        lexical += 0.1;
+      } else if (s.avgScore > 0.75) {
+        semantic += 0.05;
+        lexical -= 0.05;
+      }
+      if (s.unhelpful > s.helpful) {
+        recency += 0.05;
+        semantic -= 0.03;
+        lexical -= 0.02;
+      }
+      return { semantic, lexical, recency };
+    } catch {
+      return void 0;
     }
-    return this.retriever.retrieve(query, options);
   }
   /**
    * Fast keyword search using SQLite FTS5
@@ -4890,6 +6427,18 @@ var MemoryService = class {
   /**
    * Get memory statistics
    */
+  async getOutboxStats() {
+    await this.initialize();
+    return this.sqliteStore.getOutboxStats();
+  }
+  async getRetrievalTraceStats() {
+    await this.initialize();
+    return this.sqliteStore.getRetrievalTraceStats();
+  }
+  async getRecentRetrievalTraces(limit = 50) {
+    await this.initialize();
+    return this.sqliteStore.getRecentRetrievalTraces(limit);
+  }
   async getStats() {
     await this.initialize();
     const recentEvents = await this.sqliteStore.getRecentEvents(1e4);
@@ -5106,6 +6655,31 @@ var MemoryService = class {
       return [];
     return this.consolidatedStore.getAll({ limit });
   }
+  /**
+   * Extract topic keywords from event content (markdown headings and key terms)
+   */
+  extractTopicsFromContent(content) {
+    const topics = /* @__PURE__ */ new Set();
+    const headings = content.match(/^#{1,3}\s+(.+)$/gm);
+    if (headings) {
+      for (const h of headings.slice(0, 5)) {
+        const text = h.replace(/^#+\s+/, "").replace(/[*_`#]/g, "").trim();
+        if (text.length > 2 && text.length < 50) {
+          topics.add(text);
+        }
+      }
+    }
+    const boldTerms = content.match(/\*\*([^*]+)\*\*/g);
+    if (boldTerms) {
+      for (const b of boldTerms.slice(0, 5)) {
+        const text = b.replace(/\*\*/g, "").trim();
+        if (text.length > 2 && text.length < 30) {
+          topics.add(text);
+        }
+      }
+    }
+    return Array.from(topics).slice(0, 5);
+  }
   /**
    * Increment access count for memories that were used in prompts
    */
@@ -5129,8 +6703,7 @@ var MemoryService = class {
       return events.map((event) => ({
         memoryId: event.id,
         summary: event.content.substring(0, 200) + (event.content.length > 200 ? "..." : ""),
-        topics: [],
-        // Could extract topics from content if needed
+        topics: this.extractTopicsFromContent(event.content),
         accessCount: event.access_count || 0,
         lastAccessed: event.last_accessed_at || null,
         confidence: 1,
@@ -5151,6 +6724,34 @@ var MemoryService = class {
     }
     return [];
   }
+  /**
+   * Record a memory retrieval for helpfulness tracking
+   */
+  async recordRetrieval(eventId, sessionId, score, query) {
+    await this.initialize();
+    await this.sqliteStore.recordRetrieval(eventId, sessionId, score, query);
+  }
+  /**
+   * Evaluate helpfulness of retrievals in a session (called at session end)
+   */
+  async evaluateSessionHelpfulness(sessionId) {
+    await this.initialize();
+    await this.sqliteStore.evaluateSessionHelpfulness(sessionId);
+  }
+  /**
+   * Get most helpful memories ranked by helpfulness score
+   */
+  async getHelpfulMemories(limit = 10) {
+    await this.initialize();
+    return this.sqliteStore.getHelpfulMemories(limit);
+  }
+  /**
+   * Get helpfulness statistics for dashboard
+   */
+  async getHelpfulnessStats() {
+    await this.initialize();
+    return this.sqliteStore.getHelpfulnessStats();
+  }
   /**
    * Mark a consolidated memory as accessed
    */
@@ -5214,6 +6815,44 @@ var MemoryService = class {
       lastConsolidation
     };
   }
+  // ============================================================
+  // Turn Grouping Methods
+  // ============================================================
+  /**
+   * Get events grouped by turn for a session
+   */
+  async getSessionTurns(sessionId, options) {
+    await this.initialize();
+    return this.sqliteStore.getSessionTurns(sessionId, options);
+  }
+  /**
+   * Get all events for a specific turn
+   */
+  async getEventsByTurn(turnId) {
+    await this.initialize();
+    return this.sqliteStore.getEventsByTurn(turnId);
+  }
+  /**
+   * Count total turns for a session
+   */
+  async countSessionTurns(sessionId) {
+    await this.initialize();
+    return this.sqliteStore.countSessionTurns(sessionId);
+  }
+  /**
+   * Backfill turn_ids from metadata for events stored before the migration
+   */
+  async backfillTurnIds() {
+    await this.initialize();
+    return this.sqliteStore.backfillTurnIds();
+  }
+  /**
+   * Delete all events for a session (for force reimport)
+   */
+  async deleteSessionEvents(sessionId) {
+    await this.initialize();
+    return this.sqliteStore.deleteSessionEvents(sessionId);
+  }
   /**
    * Format Endless Mode context for Claude
    */
@@ -5290,7 +6929,7 @@ var MemoryService = class {
    */
   expandPath(p) {
     if (p.startsWith("~")) {
-      return path.join(os.homedir(), p.slice(1));
+      return path3.join(os.homedir(), p.slice(1));
     }
     return p;
   }
@@ -5326,6 +6965,7 @@ function getMemoryServiceForProject(projectPath, sharedStoreConfig) {
     serviceCache.set(hash, new MemoryService({
       storagePath,
       projectHash: hash,
+      projectPath,
       // Override shared store config - hooks don't need DuckDB
       sharedStoreConfig: sharedStoreConfig ?? { enabled: false },
       analyticsEnabled: false
@@ -5336,16 +6976,52 @@ function getMemoryServiceForProject(projectPath, sharedStoreConfig) {
 }
 
 // src/services/session-history-importer.ts
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs5 from "fs";
+import * as path4 from "path";
 import * as os2 from "os";
 import * as readline from "readline";
+import { randomUUID as randomUUID9 } from "crypto";
+function classifyEntry(entry) {
+  if (entry.type !== "user" && entry.type !== "assistant") {
+    return "skip";
+  }
+  const content = entry.message?.content;
+  if (!content)
+    return "skip";
+  if (entry.type === "user") {
+    if (typeof content === "string")
+      return "user_prompt";
+    if (Array.isArray(content)) {
+      const hasToolResult = content.some((b) => b.type === "tool_result");
+      if (hasToolResult)
+        return "tool_result";
+      const hasText = content.some((b) => b.type === "text" && b.text);
+      if (hasText)
+        return "user_prompt";
+    }
+    return "skip";
+  }
+  if (Array.isArray(content)) {
+    const hasToolUse = content.some((b) => b.type === "tool_use");
+    if (hasToolUse)
+      return "tool_use";
+    const hasText = content.some((b) => b.type === "text" && b.text);
+    if (hasText)
+      return "agent_text";
+    const hasThinking = content.some((b) => b.type === "thinking");
+    if (hasThinking)
+      return "thinking";
+  } else if (typeof content === "string" && content.length > 0) {
+    return "agent_text";
+  }
+  return "skip";
+}
 var SessionHistoryImporter = class {
   memoryService;
   claudeDir;
   constructor(memoryService) {
     this.memoryService = memoryService;
-    this.claudeDir = path2.join(os2.homedir(), ".claude");
+    this.claudeDir = path4.join(os2.homedir(), ".claude");
   }
   /**
    * Import all sessions from a project
@@ -5359,6 +7035,8 @@ var SessionHistoryImporter = class {
       skippedDuplicates: 0,
       errors: []
     };
+    const onProgress = options.onProgress;
+    onProgress?.({ phase: "scan", message: "Scanning for session files..." });
     const projectDir = await this.findProjectDir(projectPath);
     if (!projectDir) {
       result.errors.push(`Project directory not found for: ${projectPath}`);
@@ -5366,16 +7044,29 @@ var SessionHistoryImporter = class {
     }
     const sessionFiles = await this.findSessionFiles(projectDir);
     result.totalSessions = sessionFiles.length;
+    onProgress?.({ phase: "scan", message: `Found ${sessionFiles.length} sessions in ${path4.basename(projectDir)}` });
     if (options.verbose) {
       console.log(`Found ${sessionFiles.length} session files in ${projectDir}`);
     }
-    for (const sessionFile of sessionFiles) {
+    for (let i = 0; i < sessionFiles.length; i++) {
+      const sessionFile = sessionFiles[i];
       try {
-        const sessionResult = await this.importSessionFile(sessionFile, options);
+        onProgress?.({ phase: "session-start", sessionIndex: i, totalSessions: sessionFiles.length, filePath: sessionFile });
+        const sessionResult = await this.importSessionFile(sessionFile, {
+          ...options,
+          _sessionIndex: i
+        });
         result.totalMessages += sessionResult.totalMessages;
         result.importedPrompts += sessionResult.importedPrompts;
         result.importedResponses += sessionResult.importedResponses;
         result.skippedDuplicates += sessionResult.skippedDuplicates;
+        onProgress?.({
+          phase: "session-done",
+          sessionIndex: i,
+          importedPrompts: sessionResult.importedPrompts,
+          importedResponses: sessionResult.importedResponses,
+          skipped: sessionResult.skippedDuplicates
+        });
       } catch (error) {
         result.errors.push(`Failed to import ${sessionFile}: ${error}`);
       }
@@ -5394,60 +7085,105 @@ var SessionHistoryImporter = class {
       skippedDuplicates: 0,
       errors: []
     };
-    if (!fs2.existsSync(filePath)) {
+    if (!fs5.existsSync(filePath)) {
       result.errors.push(`File not found: ${filePath}`);
       return result;
     }
-    const sessionId = path2.basename(filePath, ".jsonl");
+    const sessionId = path4.basename(filePath, ".jsonl");
+    if (options.force) {
+      const deleted = await this.memoryService.deleteSessionEvents(sessionId);
+      if (options.verbose && deleted > 0) {
+        console.log(`  Deleted ${deleted} existing events for session ${sessionId}`);
+      }
+    }
     await this.memoryService.startSession(sessionId, options.projectPath);
-    const fileStream = fs2.createReadStream(filePath);
+    const fileStream = fs5.createReadStream(filePath);
     const rl = readline.createInterface({
       input: fileStream,
       crlfDelay: Infinity
     });
     let lineCount = 0;
     const limit = options.limit || Infinity;
+    const onProgress = options.onProgress;
+    const sessionIndex = options._sessionIndex ?? 0;
+    let lastProgressAt = 0;
+    let currentTurnId = null;
+    let textBuffer = [];
+    let lastTimestamp;
+    const flushTextBuffer = async () => {
+      if (textBuffer.length === 0 || !currentTurnId)
+        return;
+      const substantive = textBuffer.filter((t) => t.length >= 100);
+      const merged = substantive.length > 0 ? substantive.join("\n\n") : textBuffer.reduce((a, b) => a.length >= b.length ? a : b, "");
+      if (!merged) {
+        textBuffer = [];
+        return;
+      }
+      const truncated = merged.length > 1e4 ? merged.slice(0, 1e4) + "...[truncated]" : merged;
+      const appendResult = await this.memoryService.storeAgentResponse(
+        sessionId,
+        truncated,
+        { importedFrom: filePath, originalTimestamp: lastTimestamp, turnId: currentTurnId }
+      );
+      if (appendResult.isDuplicate) {
+        result.skippedDuplicates++;
+      } else {
+        result.importedResponses++;
+      }
+      lineCount++;
+      textBuffer = [];
+    };
     for await (const line of rl) {
       if (lineCount >= limit)
         break;
       try {
         const entry = JSON.parse(line);
         result.totalMessages++;
-        if (entry.type === "user" || entry.type === "assistant") {
+        const msgClass = classifyEntry(entry);
+        if (msgClass === "user_prompt") {
+          await flushTextBuffer();
           const content = this.extractContent(entry);
           if (!content)
             continue;
-          if (entry.type === "user") {
-            const appendResult = await this.memoryService.storeUserPrompt(
-              sessionId,
-              content,
-              { importedFrom: filePath, originalTimestamp: entry.timestamp }
-            );
-            if (appendResult.isDuplicate) {
-              result.skippedDuplicates++;
-            } else {
-              result.importedPrompts++;
-            }
-          } else if (entry.type === "assistant") {
-            const truncatedContent = content.length > 5e3 ? content.slice(0, 5e3) + "...[truncated]" : content;
-            const appendResult = await this.memoryService.storeAgentResponse(
-              sessionId,
-              truncatedContent,
-              { importedFrom: filePath, originalTimestamp: entry.timestamp }
-            );
-            if (appendResult.isDuplicate) {
-              result.skippedDuplicates++;
-            } else {
-              result.importedResponses++;
-            }
+          currentTurnId = randomUUID9();
+          const appendResult = await this.memoryService.storeUserPrompt(
+            sessionId,
+            content,
+            { importedFrom: filePath, originalTimestamp: entry.timestamp, turnId: currentTurnId }
+          );
+          if (appendResult.isDuplicate) {
+            result.skippedDuplicates++;
+          } else {
+            result.importedPrompts++;
           }
           lineCount++;
+        } else if (msgClass === "agent_text") {
+          const content = this.extractContent(entry);
+          if (content) {
+            textBuffer.push(content);
+            lastTimestamp = entry.timestamp;
+          }
+        }
+        const now = Date.now();
+        if (now - lastProgressAt > 200) {
+          lastProgressAt = now;
+          onProgress?.({
+            phase: "session-progress",
+            sessionIndex,
+            messagesProcessed: result.totalMessages,
+            imported: result.importedPrompts + result.importedResponses,
+            skipped: result.skippedDuplicates
+          });
         }
       } catch (parseError) {
         result.errors.push(`Parse error on line: ${parseError}`);
       }
     }
+    await flushTextBuffer();
     await this.memoryService.endSession(sessionId);
+    if (options.projectPath) {
+      registerSession(sessionId, options.projectPath);
+    }
     if (options.verbose) {
       console.log(`Imported ${result.importedPrompts} prompts, ${result.importedResponses} responses from ${filePath}`);
     }
@@ -5465,29 +7201,46 @@ var SessionHistoryImporter = class {
       skippedDuplicates: 0,
       errors: []
     };
-    const projectsDir = path2.join(this.claudeDir, "projects");
-    if (!fs2.existsSync(projectsDir)) {
+    const onProgress = options.onProgress;
+    const projectsDir = path4.join(this.claudeDir, "projects");
+    if (!fs5.existsSync(projectsDir)) {
       result.errors.push(`Projects directory not found: ${projectsDir}`);
       return result;
     }
-    const projectDirs = fs2.readdirSync(projectsDir).map((name) => path2.join(projectsDir, name)).filter((p) => fs2.statSync(p).isDirectory());
+    onProgress?.({ phase: "scan", message: "Scanning all projects..." });
+    const projectDirs = fs5.readdirSync(projectsDir).map((name) => path4.join(projectsDir, name)).filter((p) => fs5.statSync(p).isDirectory());
+    const allSessionFiles = [];
+    for (const projectDir of projectDirs) {
+      const sessionFiles = await this.findSessionFiles(projectDir);
+      allSessionFiles.push(...sessionFiles);
+    }
+    onProgress?.({ phase: "scan", message: `Found ${allSessionFiles.length} sessions across ${projectDirs.length} projects` });
     if (options.verbose) {
-      console.log(`Found ${projectDirs.length} project directories`);
+      console.log(`Found ${projectDirs.length} project directories, ${allSessionFiles.length} sessions`);
     }
-    for (const projectDir of projectDirs) {
+    for (let i = 0; i < allSessionFiles.length; i++) {
+      const sessionFile = allSessionFiles[i];
       try {
-        const sessionFiles = await this.findSessionFiles(projectDir);
-        for (const sessionFile of sessionFiles) {
-          const sessionResult = await this.importSessionFile(sessionFile, options);
-          result.totalSessions++;
-          result.totalMessages += sessionResult.totalMessages;
-          result.importedPrompts += sessionResult.importedPrompts;
-          result.importedResponses += sessionResult.importedResponses;
-          result.skippedDuplicates += sessionResult.skippedDuplicates;
-          result.errors.push(...sessionResult.errors);
-        }
+        onProgress?.({ phase: "session-start", sessionIndex: i, totalSessions: allSessionFiles.length, filePath: sessionFile });
+        const sessionResult = await this.importSessionFile(sessionFile, {
+          ...options,
+          _sessionIndex: i
+        });
+        result.totalSessions++;
+        result.totalMessages += sessionResult.totalMessages;
+        result.importedPrompts += sessionResult.importedPrompts;
+        result.importedResponses += sessionResult.importedResponses;
+        result.skippedDuplicates += sessionResult.skippedDuplicates;
+        result.errors.push(...sessionResult.errors);
+        onProgress?.({
+          phase: "session-done",
+          sessionIndex: i,
+          importedPrompts: sessionResult.importedPrompts,
+          importedResponses: sessionResult.importedResponses,
+          skipped: sessionResult.skippedDuplicates
+        });
       } catch (error) {
-        result.errors.push(`Failed to process ${projectDir}: ${error}`);
+        result.errors.push(`Failed to process ${sessionFile}: ${error}`);
       }
     }
     return result;
@@ -5496,14 +7249,14 @@ var SessionHistoryImporter = class {
    * Find project directory from project path
    */
   async findProjectDir(projectPath) {
-    const projectsDir = path2.join(this.claudeDir, "projects");
-    if (!fs2.existsSync(projectsDir)) {
+    const projectsDir = path4.join(this.claudeDir, "projects");
+    if (!fs5.existsSync(projectsDir)) {
       return null;
     }
-    const projectDirs = fs2.readdirSync(projectsDir).map((name) => path2.join(projectsDir, name)).filter((p) => fs2.statSync(p).isDirectory());
+    const projectDirs = fs5.readdirSync(projectsDir).map((name) => path4.join(projectsDir, name)).filter((p) => fs5.statSync(p).isDirectory());
     const normalizedPath = projectPath.replace(/\//g, "-").replace(/^-/, "");
     for (const dir of projectDirs) {
-      const dirName = path2.basename(dir);
+      const dirName = path4.basename(dir);
       if (dirName.includes(normalizedPath) || normalizedPath.includes(dirName)) {
         return dir;
       }
@@ -5514,10 +7267,10 @@ var SessionHistoryImporter = class {
    * Find all JSONL session files in a directory
    */
   async findSessionFiles(dir) {
-    if (!fs2.existsSync(dir)) {
+    if (!fs5.existsSync(dir)) {
       return [];
     }
-    return fs2.readdirSync(dir).filter((name) => name.endsWith(".jsonl")).map((name) => path2.join(dir, name)).filter((p) => fs2.statSync(p).isFile());
+    return fs5.readdirSync(dir).filter((name) => name.endsWith(".jsonl")).map((name) => path4.join(dir, name)).filter((p) => fs5.statSync(p).isFile());
   }
   /**
    * Extract text content from Claude message
@@ -5548,17 +7301,17 @@ var SessionHistoryImporter = class {
         projectDirs = [projectDir];
       }
     } else {
-      const projectsDir = path2.join(this.claudeDir, "projects");
-      if (fs2.existsSync(projectsDir)) {
-        projectDirs = fs2.readdirSync(projectsDir).map((name) => path2.join(projectsDir, name)).filter((p) => fs2.statSync(p).isDirectory());
+      const projectsDir = path4.join(this.claudeDir, "projects");
+      if (fs5.existsSync(projectsDir)) {
+        projectDirs = fs5.readdirSync(projectsDir).map((name) => path4.join(projectsDir, name)).filter((p) => fs5.statSync(p).isDirectory());
       }
     }
     for (const projectDir of projectDirs) {
       const sessionFiles = await this.findSessionFiles(projectDir);
       for (const filePath of sessionFiles) {
-        const stats = fs2.statSync(filePath);
+        const stats = fs5.statSync(filePath);
         sessions.push({
-          sessionId: path2.basename(filePath, ".jsonl"),
+          sessionId: path4.basename(filePath, ".jsonl"),
           filePath,
           size: stats.size,
           modifiedAt: stats.mtime
@@ -5573,25 +7326,448 @@ function createSessionHistoryImporter(memoryService) {
   return new SessionHistoryImporter(memoryService);
 }
 
+// src/services/bootstrap-organizer.ts
+import * as fs6 from "node:fs";
+import * as path5 from "node:path";
+import { execSync } from "node:child_process";
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "coverage", ".next", ".turbo", "memory"]);
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".kt",
+  ".swift",
+  ".rb",
+  ".php",
+  ".cs",
+  ".scala",
+  ".sh",
+  ".zsh",
+  ".yaml",
+  ".yml",
+  ".json",
+  ".sql",
+  ".md"
+]);
+function safeRel(base, target) {
+  return path5.relative(base, target).replaceAll("\\", "/");
+}
+function mkdirp(dir) {
+  fs6.mkdirSync(dir, { recursive: true });
+}
+function walkCodeFiles(root) {
+  const out = [];
+  function walk(dir) {
+    const entries = fs6.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const full = path5.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!EXCLUDED_DIRS.has(e.name))
+          walk(full);
+      } else if (e.isFile()) {
+        const ext = path5.extname(e.name).toLowerCase();
+        if (CODE_EXTENSIONS.has(ext))
+          out.push(full);
+      }
+    }
+  }
+  walk(root);
+  return out.sort();
+}
+function detectLanguage(file) {
+  const ext = path5.extname(file).toLowerCase();
+  const map = {
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".py": "Python",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".swift": "Swift",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".cs": "C#",
+    ".scala": "Scala",
+    ".sh": "Shell",
+    ".zsh": "Shell",
+    ".yaml": "YAML",
+    ".yml": "YAML",
+    ".json": "JSON",
+    ".sql": "SQL",
+    ".md": "Markdown"
+  };
+  return map[ext] || "Other";
+}
+function summarizeModules(repoPath, files) {
+  const modules = /* @__PURE__ */ new Map();
+  for (const abs of files) {
+    const rel = safeRel(repoPath, abs);
+    const seg = rel.split("/").filter(Boolean);
+    const top = seg[0] || "root";
+    if (!modules.has(top))
+      modules.set(top, { files: [], langs: /* @__PURE__ */ new Map() });
+    const bucket = modules.get(top);
+    bucket.files.push(rel);
+    const lang = detectLanguage(abs);
+    bucket.langs.set(lang, (bucket.langs.get(lang) || 0) + 1);
+  }
+  return [...modules.entries()].map(([name, data]) => ({
+    name,
+    root: name,
+    fileCount: data.files.length,
+    languages: [...data.langs.entries()].sort((a, b) => b[1] - a[1]).map(([l]) => l).slice(0, 5),
+    entryCandidates: data.files.filter((f) => /(index|main|app|server|cli)\./i.test(path5.basename(f))).slice(0, 10)
+  })).sort((a, b) => b.fileCount - a.fileCount || a.name.localeCompare(b.name));
+}
+function runGit(repoPath, command) {
+  return execSync(`git -C ${JSON.stringify(repoPath)} ${command}`, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+}
+function getGitCommits(repoPath, since = "180 days ago", maxCommits = 1e3) {
+  try {
+    const raw = runGit(
+      repoPath,
+      `log --since=${JSON.stringify(since)} -n ${Math.max(1, maxCommits)} --date=short --pretty=format:%H%x09%ad%x09%an%x09%s --name-only --reverse`
+    );
+    const lines = raw.split(/\r?\n/);
+    const commits = [];
+    let current = null;
+    for (const line of lines) {
+      if (!line.trim()) {
+        if (current) {
+          commits.push(current);
+          current = null;
+        }
+        continue;
+      }
+      if (line.includes("	") && line.split("	").length >= 4) {
+        if (current)
+          commits.push(current);
+        const [hash, date, author, ...subjectRest] = line.split("	");
+        current = { hash, date, author, subject: subjectRest.join("	").trim(), files: [] };
+      } else if (current) {
+        current.files.push(line.trim());
+      }
+    }
+    if (current)
+      commits.push(current);
+    return commits;
+  } catch {
+    return [];
+  }
+}
+function extractDecisions(commits) {
+  const decisionPattern = /(refactor|migrate|deprecat|remove|replace|introduce|adopt|switch|upgrade|breaking|architecture|feat|fix)/i;
+  return commits.filter((c) => decisionPattern.test(c.subject));
+}
+function buildTimeline(commits) {
+  const timeline = /* @__PURE__ */ new Map();
+  for (const c of commits) {
+    const key = (c.date || "").slice(0, 7) || "unknown";
+    if (!timeline.has(key))
+      timeline.set(key, []);
+    timeline.get(key).push(c);
+  }
+  return new Map([...timeline.entries()].sort((a, b) => a[0].localeCompare(b[0])));
+}
+function buildGlossary(files) {
+  const stop = /* @__PURE__ */ new Set(["src", "test", "dist", "lib", "core", "index", "main", "app", "server", "client", "utils"]);
+  const freq = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    const base = path5.basename(f, path5.extname(f));
+    const tokens = base.split(/[^a-zA-Z0-9]+/).flatMap((t) => t.split(/(?=[A-Z])/)).map((t) => t.toLowerCase()).filter((t) => t.length >= 3 && !stop.has(t));
+    for (const t of tokens)
+      freq.set(t, (freq.get(t) || 0) + 1);
+  }
+  return [...freq.entries()].filter(([, count]) => count >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 80).map(([term]) => term);
+}
+function writeFile(filePath, content) {
+  mkdirp(path5.dirname(filePath));
+  fs6.writeFileSync(filePath, content, "utf8");
+}
+function confidenceByEvidence(sourceCount) {
+  if (sourceCount >= 3)
+    return "high";
+  if (sourceCount >= 1)
+    return "mid";
+  return "low";
+}
+function sourceLine(source) {
+  return `- source: ${source}`;
+}
+function loadExistingManifest(outDir) {
+  try {
+    const p = path5.join(outDir, "sources", "manifest.json");
+    if (!fs6.existsSync(p))
+      return null;
+    const data = JSON.parse(fs6.readFileSync(p, "utf8"));
+    return data;
+  } catch {
+    return null;
+  }
+}
+function listMarkdownOutputs(outDir) {
+  const out = [];
+  const stack = [outDir];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+      const full = path5.join(dir, entry.name);
+      if (entry.isDirectory())
+        stack.push(full);
+      else if (entry.isFile() && entry.name.endsWith(".md"))
+        out.push(full);
+    }
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+async function bootstrapKnowledgeBase(options) {
+  const repoPath = path5.resolve(options.repoPath);
+  const outDir = path5.resolve(options.outDir);
+  const maxCommits = options.maxCommits ?? 1e3;
+  const existingManifest = options.incremental ? loadExistingManifest(outDir) : null;
+  const incrementalSince = existingManifest?.lastCommitDate || existingManifest?.generatedAt;
+  const since = options.since || incrementalSince || "180 days ago";
+  const codeFiles = walkCodeFiles(repoPath);
+  const modules = summarizeModules(repoPath, codeFiles);
+  const commits = getGitCommits(repoPath, since, maxCommits);
+  const decisions = extractDecisions(commits);
+  const timeline = buildTimeline(commits);
+  const glossary = buildGlossary(codeFiles);
+  const generatedFiles = [];
+  const sections = {
+    overview: path5.join(outDir, "overview"),
+    modules: path5.join(outDir, "modules"),
+    decisions: path5.join(outDir, "decisions"),
+    timeline: path5.join(outDir, "timeline"),
+    glossary: path5.join(outDir, "glossary"),
+    sources: path5.join(outDir, "sources")
+  };
+  for (const sectionDir of Object.values(sections)) {
+    mkdirp(sectionDir);
+  }
+  const overviewPath = path5.join(sections.overview, "overview.md");
+  const overview = [
+    "# Codebase Overview",
+    "",
+    `- generatedAt: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "- deterministicPipeline: true",
+    `- repo: ${repoPath}`,
+    `- filesAnalyzed: ${codeFiles.length}`,
+    `- commitsAnalyzed: ${commits.length}`,
+    `- confidence: ${confidenceByEvidence(modules.length > 0 ? 3 : 0)}`,
+    "",
+    "## Directory / Module Map",
+    ...modules.slice(0, 50).map((m) => `- ${m.name}: ${m.fileCount} files (${m.languages.join(", ") || "n/a"})`),
+    "",
+    "## Fact",
+    "- Generated from deterministic file scan and git history parsing.",
+    "",
+    "## Inference",
+    "- Module responsibilities should be reviewed by maintainers for nuanced boundaries.",
+    "",
+    "## Sources",
+    sourceLine(`repo-scan:${repoPath}`),
+    sourceLine(`git-log:since=${since};max=${maxCommits}`),
+    ""
+  ].join("\n");
+  writeFile(overviewPath, overview);
+  generatedFiles.push(overviewPath);
+  const touchedRoots = new Set(
+    commits.flatMap((c) => c.files).map((f) => f.split("/").filter(Boolean)[0]).filter(Boolean)
+  );
+  const moduleTargets = options.incremental && touchedRoots.size > 0 ? modules.filter((m) => touchedRoots.has(m.root)).slice(0, 200) : modules.slice(0, 200);
+  for (const m of moduleTargets) {
+    const relatedCommits = commits.filter((c) => c.files.some((f) => f.startsWith(`${m.root}/`))).slice(0, 15);
+    const content = [
+      `# Module: ${m.name}`,
+      "",
+      `- responsibility: inferred from top-level path \`${m.root}/\``,
+      `- files: ${m.fileCount}`,
+      `- languages: ${m.languages.join(", ") || "n/a"}`,
+      `- confidence: ${confidenceByEvidence(relatedCommits.length)}`,
+      "",
+      "## Entry Candidates",
+      ...m.entryCandidates.length > 0 ? m.entryCandidates.map((f) => `- ${f}`) : ["- none detected"],
+      "",
+      "## Related Commits (recent sample)",
+      ...relatedCommits.length > 0 ? relatedCommits.map((c) => `- ${c.date} ${c.hash.slice(0, 8)} ${c.subject}`) : ["- none in selected range"],
+      "",
+      "## Sources",
+      sourceLine(`repo-path:${m.root}/**`),
+      ...relatedCommits.map((c) => sourceLine(`commit:${c.hash}`)),
+      ""
+    ].join("\n");
+    const modulePath = path5.join(sections.modules, `${m.name.replace(/[^a-z0-9._-]+/gi, "-").toLowerCase()}.md`);
+    writeFile(modulePath, content);
+    generatedFiles.push(modulePath);
+  }
+  const decisionsPath = path5.join(sections.decisions, "decisions.md");
+  const decisionsMd = [
+    "# Decisions (extracted)",
+    "",
+    `- confidence: ${confidenceByEvidence(decisions.length)}`,
+    "",
+    ...decisions.length > 0 ? decisions.slice(0, 500).map((d) => [
+      `## ${d.date} | ${d.subject}`,
+      "- status: active (inferred)",
+      sourceLine(`commit:${d.hash}`),
+      `- author: ${d.author}`,
+      `- changedFiles: ${d.files.length}`,
+      `- confidence: ${confidenceByEvidence(d.files.length > 0 ? 2 : 1)}`,
+      ""
+    ].join("\n")) : ["- No decision-like commits found in selected range.", ""],
+    "## Sources",
+    sourceLine(`git-log:since=${since};max=${maxCommits}`),
+    ""
+  ].join("\n");
+  writeFile(decisionsPath, decisionsMd);
+  generatedFiles.push(decisionsPath);
+  const timelinePath = path5.join(sections.timeline, "timeline.md");
+  const timelineMd = [
+    "# Timeline",
+    "",
+    `- confidence: ${confidenceByEvidence(commits.length > 0 ? 2 : 0)}`,
+    "",
+    ...[...timeline.entries()].flatMap(([month, list]) => [
+      `## ${month}`,
+      ...list.slice(0, 40).map((c) => `- ${c.date} ${c.hash.slice(0, 8)} ${c.subject}`),
+      ""
+    ]),
+    "## Sources",
+    sourceLine(`git-log:since=${since};max=${maxCommits}`),
+    ""
+  ].join("\n");
+  writeFile(timelinePath, timelineMd);
+  generatedFiles.push(timelinePath);
+  const glossaryPath = path5.join(sections.glossary, "glossary.md");
+  const glossaryMd = [
+    "# Glossary (auto-extracted)",
+    "",
+    `- confidence: ${confidenceByEvidence(glossary.length > 0 ? 1 : 0)}`,
+    "",
+    ...glossary.map((t) => `- ${t}`),
+    "",
+    "## Sources",
+    sourceLine(`repo-scan:${repoPath}`),
+    ""
+  ].join("\n");
+  writeFile(glossaryPath, glossaryMd);
+  generatedFiles.push(glossaryPath);
+  const outputs = generatedFiles.map((f) => safeRel(outDir, f)).sort((a, b) => a.localeCompare(b));
+  const allOutputs = listMarkdownOutputs(outDir).map((f) => safeRel(outDir, f));
+  const sourceItems = [
+    ...codeFiles.slice(0, 200).map((f) => ({ type: "file", ref: safeRel(repoPath, f) })),
+    ...commits.slice(0, 400).map((c) => ({ type: "commit", ref: c.hash, date: c.date, subject: c.subject }))
+  ];
+  const latestCommitDate = commits.length > 0 ? commits[commits.length - 1].date : void 0;
+  const manifest = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    deterministicPipeline: true,
+    mode: options.incremental ? "incremental" : "full",
+    repoPath,
+    options: { since, maxCommits, incremental: Boolean(options.incremental) },
+    stats: {
+      filesAnalyzed: codeFiles.length,
+      modules: modules.length,
+      modulesGenerated: moduleTargets.length,
+      commits: commits.length,
+      decisions: decisions.length,
+      glossaryTerms: glossary.length
+    },
+    lastCommitDate: latestCommitDate,
+    outputs,
+    allOutputs,
+    sources: sourceItems
+  };
+  const manifestJsonPath = path5.join(sections.sources, "manifest.json");
+  writeFile(manifestJsonPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  generatedFiles.push(manifestJsonPath);
+  const manifestMdPath = path5.join(sections.sources, "manifest.md");
+  const manifestMd = [
+    "# Sources Manifest",
+    "",
+    "- deterministicPipeline: true",
+    `- mode: ${options.incremental ? "incremental" : "full"}`,
+    `- sourceCount: ${sourceItems.length}`,
+    "",
+    "## Outputs",
+    ...outputs.map((o) => `- ${o}`),
+    "",
+    "## Sources (sample)",
+    ...sourceItems.slice(0, 300).map((s) => `- ${s.type}:${s.ref}`),
+    ""
+  ].join("\n");
+  writeFile(manifestMdPath, manifestMd);
+  generatedFiles.push(manifestMdPath);
+  return {
+    outDir,
+    fileCount: codeFiles.length,
+    moduleCount: modules.length,
+    commitCount: commits.length,
+    generatedFiles: generatedFiles.sort((a, b) => a.localeCompare(b))
+  };
+}
+
 // src/server/index.ts
-import { Hono as Hono7 } from "hono";
+import { Hono as Hono11 } from "hono";
 import { cors } from "hono/cors";
 import { logger } from "hono/logger";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
-import * as path3 from "path";
-import * as fs3 from "fs";
+import * as path8 from "path";
+import * as fs8 from "fs";
 
 // src/server/api/index.ts
-import { Hono as Hono6 } from "hono";
+import { Hono as Hono10 } from "hono";
 
 // src/server/api/sessions.ts
 import { Hono } from "hono";
+
+// src/server/api/utils.ts
+import * as path6 from "path";
+import * as os3 from "os";
+function getServiceFromQuery(c) {
+  const project = c.req.query("project");
+  if (project) {
+    const isHash = /^[a-f0-9]{8}$/.test(project);
+    let storagePath;
+    if (isHash) {
+      storagePath = path6.join(os3.homedir(), ".claude-code", "memory", "projects", project);
+    } else {
+      const crypto3 = __require("crypto");
+      const normalized = project.replace(/\/+$/, "") || "/";
+      const hash = crypto3.createHash("sha256").update(normalized).digest("hex").slice(0, 8);
+      storagePath = path6.join(os3.homedir(), ".claude-code", "memory", "projects", hash);
+    }
+    return new MemoryService({
+      storagePath,
+      readOnly: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: { enabled: false }
+    });
+  }
+  return getReadOnlyMemoryService();
+}
+
+// src/server/api/sessions.ts
 var sessionsRouter = new Hono();
 sessionsRouter.get("/", async (c) => {
   const page = parseInt(c.req.query("page") || "1", 10);
   const pageSize = parseInt(c.req.query("pageSize") || "20", 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const recentEvents = await memoryService.getRecentEvents(1e3);
@@ -5635,7 +7811,7 @@ sessionsRouter.get("/", async (c) => {
 });
 sessionsRouter.get("/:id", async (c) => {
   const { id } = c.req.param();
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const events = await memoryService.getSessionHistory(id);
@@ -5676,18 +7852,36 @@ var eventsRouter = new Hono2();
 eventsRouter.get("/", async (c) => {
   const sessionId = c.req.query("sessionId");
   const eventType = c.req.query("type");
+  const level = c.req.query("level");
+  const sort = c.req.query("sort") || "recent";
   const limit = parseInt(c.req.query("limit") || "100", 10);
   const offset = parseInt(c.req.query("offset") || "0", 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
-    let events = await memoryService.getRecentEvents(limit + offset + 1e3);
+    let events;
+    if (level) {
+      events = await memoryService.getEventsByLevel(level, { limit: limit + offset + 1e3, offset: 0 });
+    } else {
+      events = await memoryService.getRecentEvents(limit + offset + 1e3);
+    }
     if (sessionId) {
       events = events.filter((e) => e.sessionId === sessionId);
     }
     if (eventType) {
       events = events.filter((e) => e.eventType === eventType);
     }
+    if (sort === "accessed") {
+      events.sort((a, b) => {
+        const aTime = a.last_accessed_at || "";
+        const bTime = b.last_accessed_at || "";
+        return bTime.localeCompare(aTime);
+      });
+    } else if (sort === "most-accessed") {
+      events.sort((a, b) => (b.access_count || 0) - (a.access_count || 0));
+    } else if (sort === "oldest") {
+      events.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
     const total = events.length;
     events = events.slice(offset, offset + limit);
     return c.json({
@@ -5697,7 +7891,9 @@ eventsRouter.get("/", async (c) => {
         timestamp: e.timestamp,
         sessionId: e.sessionId,
         preview: e.content.slice(0, 200) + (e.content.length > 200 ? "..." : ""),
-        contentLength: e.content.length
+        contentLength: e.content.length,
+        accessCount: e.access_count || 0,
+        lastAccessedAt: e.last_accessed_at || null
       })),
       total,
       limit,
@@ -5712,7 +7908,7 @@ eventsRouter.get("/", async (c) => {
 });
 eventsRouter.get("/:id", async (c) => {
   const { id } = c.req.param();
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const recentEvents = await memoryService.getRecentEvents(1e4);
@@ -5752,7 +7948,7 @@ eventsRouter.get("/:id", async (c) => {
 import { Hono as Hono3 } from "hono";
 var searchRouter = new Hono3();
 searchRouter.post("/", async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     const body = await c.req.json();
     if (!body.query) {
@@ -5796,7 +7992,7 @@ searchRouter.get("/", async (c) => {
     return c.json({ error: 'Query parameter "q" is required' }, 400);
   }
   const topK = parseInt(c.req.query("topK") || "5", 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const result = await memoryService.retrieveMemories(query, { topK });
@@ -5824,7 +8020,7 @@ searchRouter.get("/", async (c) => {
 import { Hono as Hono4 } from "hono";
 var statsRouter = new Hono4();
 statsRouter.get("/shared", async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const sharedStats = await memoryService.getSharedStoreStats();
@@ -5881,7 +8077,7 @@ statsRouter.get("/levels/:level", async (c) => {
   if (!validLevels.includes(level)) {
     return c.json({ error: `Invalid level. Must be one of: ${validLevels.join(", ")}` }, 400);
   }
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     let events = await memoryService.getEventsByLevel(level, { limit: limit * 2, offset });
@@ -5928,7 +8124,7 @@ statsRouter.get("/levels/:level", async (c) => {
   }
 });
 statsRouter.get("/", async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const stats = await memoryService.getStats();
@@ -5945,6 +8141,7 @@ statsRouter.get("/", async (c) => {
       acc[day] = (acc[day] || 0) + 1;
       return acc;
     }, {});
+    const retrievalTrace = await memoryService.getRetrievalTraceStats();
     return c.json({
       storage: {
         eventCount: stats.totalEvents,
@@ -5962,7 +8159,8 @@ statsRouter.get("/", async (c) => {
         heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
         heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024)
       },
-      levelStats: stats.levelStats
+      levelStats: stats.levelStats,
+      retrievalTrace
     });
   } catch (error) {
     return c.json({ error: error.message }, 500);
@@ -5972,7 +8170,7 @@ statsRouter.get("/", async (c) => {
 });
 statsRouter.get("/most-accessed", async (c) => {
   const limit = parseInt(c.req.query("limit") || "10", 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     console.log("[most-accessed] Fetching most accessed memories, limit:", limit);
@@ -6003,7 +8201,7 @@ statsRouter.get("/most-accessed", async (c) => {
 });
 statsRouter.get("/timeline", async (c) => {
   const days = parseInt(c.req.query("days") || "7", 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const recentEvents = await memoryService.getRecentEvents(1e4);
@@ -6033,8 +8231,75 @@ statsRouter.get("/timeline", async (c) => {
     await memoryService.shutdown();
   }
 });
+statsRouter.get("/helpfulness", async (c) => {
+  const limit = parseInt(c.req.query("limit") || "10", 10);
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const stats = await memoryService.getHelpfulnessStats();
+    const topMemories = await memoryService.getHelpfulMemories(limit);
+    return c.json({
+      ...stats,
+      topMemories: topMemories.map((m) => ({
+        eventId: m.eventId,
+        summary: m.summary,
+        helpfulnessScore: m.helpfulnessScore,
+        accessCount: m.accessCount,
+        evaluationCount: m.evaluationCount
+      }))
+    });
+  } catch (error) {
+    return c.json({
+      avgScore: 0,
+      totalEvaluated: 0,
+      totalRetrievals: 0,
+      helpful: 0,
+      neutral: 0,
+      unhelpful: 0,
+      topMemories: []
+    });
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+statsRouter.get("/retrieval-traces", async (c) => {
+  const limit = parseInt(c.req.query("limit") || "50", 10);
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const traces = await memoryService.getRecentRetrievalTraces(limit);
+    const traceStats = await memoryService.getRetrievalTraceStats();
+    return c.json({
+      stats: traceStats,
+      traces: traces.map((t) => ({
+        traceId: t.traceId,
+        sessionId: t.sessionId || null,
+        projectHash: t.projectHash || null,
+        queryText: t.queryText,
+        strategy: t.strategy || null,
+        candidateEventIds: t.candidateEventIds,
+        selectedEventIds: t.selectedEventIds,
+        candidateDetails: t.candidateDetails || [],
+        selectedDetails: t.selectedDetails || [],
+        candidateCount: t.candidateCount,
+        selectedCount: t.selectedCount,
+        confidence: t.confidence || null,
+        fallbackTrace: t.fallbackTrace,
+        createdAt: t.createdAt.toISOString()
+      }))
+    });
+  } catch (error) {
+    return c.json({
+      stats: { totalQueries: 0, avgCandidateCount: 0, avgSelectedCount: 0, selectionRate: 0 },
+      traces: [],
+      error: error.message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 statsRouter.post("/graduation/run", async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const result = await memoryService.forceGraduation();
@@ -6095,7 +8360,7 @@ var citationsRouter = new Hono5();
 citationsRouter.get("/:id", async (c) => {
   const { id } = c.req.param();
   const citationId = parseCitationId(id) || id;
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const recentEvents = await memoryService.getRecentEvents(1e4);
@@ -6129,7 +8394,7 @@ citationsRouter.get("/:id", async (c) => {
 citationsRouter.get("/:id/related", async (c) => {
   const { id } = c.req.param();
   const citationId = parseCitationId(id) || id;
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const recentEvents = await memoryService.getRecentEvents(1e4);
@@ -6165,23 +8430,415 @@ citationsRouter.get("/:id/related", async (c) => {
   }
 });
 
+// src/server/api/turns.ts
+import { Hono as Hono6 } from "hono";
+var turnsRouter = new Hono6();
+turnsRouter.get("/", async (c) => {
+  const sessionId = c.req.query("sessionId");
+  const limit = parseInt(c.req.query("limit") || "20", 10);
+  const offset = parseInt(c.req.query("offset") || "0", 10);
+  if (!sessionId) {
+    return c.json({ error: "sessionId is required" }, 400);
+  }
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const turns = await memoryService.getSessionTurns(sessionId, { limit, offset });
+    const totalTurns = await memoryService.countSessionTurns(sessionId);
+    return c.json({
+      turns: turns.map((t) => ({
+        turnId: t.turnId,
+        startedAt: t.startedAt.toISOString(),
+        promptPreview: t.promptPreview,
+        eventCount: t.eventCount,
+        toolCount: t.toolCount,
+        hasResponse: t.hasResponse,
+        events: t.events.map((e) => ({
+          id: e.id,
+          eventType: e.eventType,
+          timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp,
+          preview: e.content.slice(0, 300) + (e.content.length > 300 ? "..." : ""),
+          contentLength: e.content.length
+        }))
+      })),
+      total: totalTurns,
+      limit,
+      offset,
+      hasMore: offset + limit < totalTurns
+    });
+  } catch (error) {
+    return c.json({ error: error.message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+turnsRouter.get("/:turnId", async (c) => {
+  const { turnId } = c.req.param();
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const events = await memoryService.getEventsByTurn(turnId);
+    if (events.length === 0) {
+      return c.json({ error: "Turn not found" }, 404);
+    }
+    const promptEvent = events.find((e) => e.eventType === "user_prompt");
+    const toolEvents = events.filter((e) => e.eventType === "tool_observation");
+    const responseEvents = events.filter((e) => e.eventType === "agent_response");
+    return c.json({
+      turnId,
+      sessionId: events[0].sessionId,
+      startedAt: events[0].timestamp instanceof Date ? events[0].timestamp.toISOString() : events[0].timestamp,
+      prompt: promptEvent ? {
+        id: promptEvent.id,
+        content: promptEvent.content,
+        timestamp: promptEvent.timestamp instanceof Date ? promptEvent.timestamp.toISOString() : promptEvent.timestamp
+      } : null,
+      tools: toolEvents.map((e) => {
+        let toolName = "";
+        let success = true;
+        try {
+          const parsed = JSON.parse(e.content);
+          toolName = parsed.toolName || "";
+          success = parsed.success !== false;
+        } catch {
+        }
+        return {
+          id: e.id,
+          toolName,
+          success,
+          timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp,
+          preview: e.content.slice(0, 500) + (e.content.length > 500 ? "..." : "")
+        };
+      }),
+      responses: responseEvents.map((e) => ({
+        id: e.id,
+        content: e.content,
+        timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp
+      })),
+      totalEvents: events.length
+    });
+  } catch (error) {
+    return c.json({ error: error.message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+turnsRouter.post("/backfill", async (c) => {
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const updated = await memoryService.backfillTurnIds();
+    return c.json({
+      success: true,
+      updated,
+      message: `Backfilled turn_id for ${updated} events`
+    });
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: error.message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// src/server/api/projects.ts
+import { Hono as Hono7 } from "hono";
+import * as fs7 from "fs";
+import * as path7 from "path";
+import * as os4 from "os";
+var projectsRouter = new Hono7();
+projectsRouter.get("/", async (c) => {
+  try {
+    const projectsDir = path7.join(os4.homedir(), ".claude-code", "memory", "projects");
+    if (!fs7.existsSync(projectsDir)) {
+      return c.json({ projects: [] });
+    }
+    const projectHashes = fs7.readdirSync(projectsDir).filter((name) => {
+      const fullPath = path7.join(projectsDir, name);
+      return fs7.statSync(fullPath).isDirectory();
+    });
+    const registry = loadSessionRegistry();
+    const hashToPath = /* @__PURE__ */ new Map();
+    for (const entry of Object.values(registry.sessions)) {
+      if (!hashToPath.has(entry.projectHash)) {
+        hashToPath.set(entry.projectHash, entry.projectPath);
+      }
+    }
+    const projects = projectHashes.map((hash) => {
+      const dirPath = path7.join(projectsDir, hash);
+      const dbPath = path7.join(dirPath, "events.sqlite");
+      let dbSize = 0;
+      if (fs7.existsSync(dbPath)) {
+        dbSize = fs7.statSync(dbPath).size;
+      }
+      const projectPath = hashToPath.get(hash) || `unknown (${hash})`;
+      return {
+        hash,
+        projectPath,
+        projectName: path7.basename(projectPath),
+        dbSize,
+        dbSizeHuman: formatBytes(dbSize)
+      };
+    });
+    projects.sort((a, b) => a.projectName.localeCompare(b.projectName));
+    return c.json({ projects });
+  } catch (error) {
+    return c.json({ projects: [], error: error.message }, 500);
+  }
+});
+function formatBytes(bytes) {
+  if (bytes === 0)
+    return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + " " + sizes[i];
+}
+
+// src/server/api/chat.ts
+import { Hono as Hono8 } from "hono";
+import { streamSSE } from "hono/streaming";
+import { spawn } from "child_process";
+var chatRouter = new Hono8();
+var CLAUDE_TIMEOUT_MS = 12e4;
+chatRouter.post("/", async (c) => {
+  let body;
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: "Invalid JSON body" }, 400);
+  }
+  if (!body.message?.trim()) {
+    return c.json({ error: "Message is required" }, 400);
+  }
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    let memoryContext = "";
+    let statsContext = "";
+    try {
+      const result = await memoryService.retrieveMemories(body.message, {
+        topK: 8,
+        minScore: 0.5
+      });
+      if (result.memories.length > 0) {
+        const parts = ["## Relevant Memories\n"];
+        for (const m of result.memories) {
+          const date = new Date(m.event.timestamp).toISOString().split("T")[0];
+          const content = m.event.content.slice(0, 500);
+          parts.push(`### [${m.event.eventType}] ${date} (score: ${m.score.toFixed(2)})`);
+          parts.push(content);
+          if (m.sessionContext) {
+            parts.push(`_Context: ${m.sessionContext}_`);
+          }
+          parts.push("");
+        }
+        memoryContext = parts.join("\n");
+      }
+    } catch {
+    }
+    try {
+      const stats = await memoryService.getStats();
+      const levels = stats.levelStats.map((l) => `${l.level}: ${l.count}`).join(", ");
+      statsContext = [
+        "## Memory Stats",
+        `- Total events: ${stats.totalEvents}`,
+        `- Vector nodes: ${stats.vectorCount}`,
+        `- By level: ${levels}`
+      ].join("\n");
+    } catch {
+    }
+    const fullPrompt = buildPrompt(
+      statsContext,
+      memoryContext,
+      body.history || [],
+      body.message
+    );
+    return streamSSE(c, async (stream) => {
+      try {
+        await streamClaudeResponse(fullPrompt, stream);
+      } catch (err) {
+        await stream.writeSSE({
+          event: "error",
+          data: JSON.stringify({ error: err.message })
+        });
+      }
+    });
+  } catch (error) {
+    return c.json({ error: error.message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+function buildPrompt(statsContext, memoryContext, history, currentMessage) {
+  const parts = [];
+  parts.push("You are a helpful assistant that answers questions about the user's code memory data.");
+  parts.push("The memory system tracks coding sessions, tool usage, prompts, and responses.");
+  parts.push("Answer concisely based on the memory context below. If you don't have enough data, say so.");
+  parts.push("Use markdown formatting in your responses.\n");
+  if (statsContext) {
+    parts.push(statsContext);
+    parts.push("");
+  }
+  if (memoryContext) {
+    parts.push(memoryContext);
+  } else {
+    parts.push("No directly relevant memories found for this query.");
+    parts.push("Answer based on general knowledge or suggest the user rephrase.\n");
+  }
+  parts.push("---\n");
+  const recentHistory = history.slice(-10);
+  if (recentHistory.length > 0) {
+    parts.push("## Conversation History\n");
+    for (const msg of recentHistory) {
+      const prefix = msg.role === "user" ? "User" : "Assistant";
+      parts.push(`**${prefix}:** ${msg.content}
+`);
+    }
+  }
+  parts.push(`**User:** ${currentMessage}`);
+  return parts.join("\n");
+}
+function streamClaudeResponse(prompt, stream) {
+  return new Promise((resolve4, reject) => {
+    const proc = spawn("claude", [
+      "-p",
+      "--output-format",
+      "stream-json",
+      "--verbose"
+    ], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env }
+    });
+    const timeout = setTimeout(() => {
+      proc.kill("SIGTERM");
+      reject(new Error("Chat response timed out after 2 minutes"));
+    }, CLAUDE_TIMEOUT_MS);
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+    let buffer = "";
+    let lastSentText = "";
+    proc.stdout.on("data", async (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        if (!line.trim())
+          continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.type === "assistant" && parsed.message?.content) {
+            const textBlocks = parsed.message.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+            if (textBlocks.length > lastSentText.length) {
+              const delta = textBlocks.slice(lastSentText.length);
+              lastSentText = textBlocks;
+              await stream.writeSSE({
+                event: "message",
+                data: JSON.stringify({ content: delta })
+              });
+            }
+          }
+          if (parsed.type === "result") {
+            await stream.writeSSE({ event: "done", data: "{}" });
+          }
+        } catch {
+        }
+      }
+    });
+    proc.stderr.on("data", (chunk) => {
+      if (process.env.CLAUDE_MEMORY_DEBUG) {
+        console.error("[chat] claude stderr:", chunk.toString());
+      }
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timeout);
+      if (err.code === "ENOENT") {
+        reject(new Error("Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code"));
+      } else {
+        reject(err);
+      }
+    });
+    proc.on("close", async (code) => {
+      clearTimeout(timeout);
+      if (buffer.trim()) {
+        try {
+          const parsed = JSON.parse(buffer);
+          if (parsed.type === "result") {
+            await stream.writeSSE({ event: "done", data: "{}" });
+          }
+        } catch {
+        }
+      }
+      if (code !== 0 && code !== null) {
+        reject(new Error(`Claude CLI exited with code ${code}`));
+      } else {
+        resolve4();
+      }
+    });
+  });
+}
+
+// src/server/api/health.ts
+import { Hono as Hono9 } from "hono";
+var healthRouter = new Hono9();
+healthRouter.get("/", async (c) => {
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const [stats, outbox] = await Promise.all([
+      memoryService.getStats(),
+      memoryService.getOutboxStats()
+    ]);
+    const outboxPending = outbox.embedding.pending + outbox.vector.pending;
+    const outboxFailed = outbox.embedding.failed + outbox.vector.failed;
+    const status = outboxFailed > 0 ? "needs-attention" : "ok";
+    return c.json({
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      storage: {
+        totalEvents: stats.totalEvents,
+        vectorCount: stats.vectorCount
+      },
+      outbox: {
+        embedding: outbox.embedding,
+        vector: outbox.vector,
+        totals: {
+          pending: outboxPending,
+          failed: outboxFailed
+        }
+      },
+      levelStats: stats.levelStats
+    });
+  } catch (error) {
+    return c.json({
+      status: "error",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: error.message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
 // src/server/api/index.ts
-var apiRouter = new Hono6().route("/sessions", sessionsRouter).route("/events", eventsRouter).route("/search", searchRouter).route("/stats", statsRouter).route("/citations", citationsRouter);
+var apiRouter = new Hono10().route("/sessions", sessionsRouter).route("/events", eventsRouter).route("/search", searchRouter).route("/stats", statsRouter).route("/citations", citationsRouter).route("/turns", turnsRouter).route("/projects", projectsRouter).route("/chat", chatRouter).route("/health", healthRouter);
 
 // src/server/index.ts
-var app = new Hono7();
+var app = new Hono11();
 app.use("/*", cors());
 app.use("/*", logger());
 app.route("/api", apiRouter);
 app.get("/health", (c) => c.json({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
-var uiPath = path3.join(__dirname, "../../dist/ui");
-if (fs3.existsSync(uiPath)) {
+var uiPath = path8.join(__dirname, "../../dist/ui");
+if (fs8.existsSync(uiPath)) {
   app.use("/*", serveStatic({ root: uiPath }));
 }
 app.get("*", (c) => {
-  const indexPath = path3.join(uiPath, "index.html");
-  if (fs3.existsSync(indexPath)) {
-    return c.html(fs3.readFileSync(indexPath, "utf-8"));
+  const indexPath = path8.join(uiPath, "index.html");
+  if (fs8.existsSync(indexPath)) {
+    return c.html(fs8.readFileSync(indexPath, "utf-8"));
   }
   return c.text('UI not built. Run "npm run build:ui" first.', 404);
 });
@@ -6218,29 +8875,303 @@ if (isMainModule) {
   startServer(port);
 }
 
+// src/core/mongo-sync-worker.ts
+import { randomUUID as randomUUID10 } from "crypto";
+import * as os5 from "os";
+import { MongoClient } from "mongodb";
+function redactMongoUri(uri) {
+  const schemeIdx = uri.indexOf("://");
+  if (schemeIdx === -1)
+    return uri;
+  const atIdx = uri.indexOf("@", schemeIdx + 3);
+  if (atIdx === -1)
+    return uri;
+  const creds = uri.slice(schemeIdx + 3, atIdx);
+  const colonIdx = creds.indexOf(":");
+  if (colonIdx === -1)
+    return uri;
+  const prefix = uri.slice(0, schemeIdx + 3 + colonIdx + 1);
+  const suffix = uri.slice(atIdx);
+  return `${prefix}***${suffix}`;
+}
+function parseIntOrZero(value) {
+  if (!value)
+    return 0;
+  const n = parseInt(value, 10);
+  return Number.isFinite(n) ? n : 0;
+}
+var MongoSyncWorker = class {
+  constructor(sqliteStore, config) {
+    this.sqliteStore = sqliteStore;
+    this.config = {
+      uri: config.uri,
+      dbName: config.dbName,
+      projectKey: config.projectKey,
+      direction: config.direction ?? "both",
+      intervalMs: config.intervalMs ?? 3e4,
+      batchSize: config.batchSize ?? 500,
+      instanceId: config.instanceId ?? randomUUID10()
+    };
+  }
+  config;
+  intervalHandle = null;
+  running = false;
+  client = null;
+  db = null;
+  counters = null;
+  events = null;
+  indexesEnsured = false;
+  stats = {
+    lastSyncAt: null,
+    pushedEvents: 0,
+    pulledEvents: 0,
+    errors: 0,
+    status: "idle"
+  };
+  start() {
+    if (this.running)
+      return;
+    this.running = true;
+    this.stats.status = "idle";
+    this.syncNow().catch((err) => {
+      console.error("[MongoSyncWorker] Initial sync failed:", err);
+    });
+    this.intervalHandle = setInterval(() => {
+      this.syncNow().catch((err) => {
+        console.error("[MongoSyncWorker] Periodic sync failed:", err);
+      });
+    }, this.config.intervalMs);
+  }
+  stop() {
+    this.running = false;
+    this.stats.status = "stopped";
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+  }
+  async shutdown() {
+    this.stop();
+    await this.disconnect();
+  }
+  getStats() {
+    return { ...this.stats };
+  }
+  isRunning() {
+    return this.running;
+  }
+  async syncNow() {
+    if (this.stats.status === "syncing")
+      return { pushed: 0, pulled: 0 };
+    this.stats.status = "syncing";
+    let pushed = 0;
+    let pulled = 0;
+    try {
+      await this.sqliteStore.initialize();
+      await this.ensureConnected();
+      await this.ensureIndexes();
+      if (this.config.direction === "push" || this.config.direction === "both") {
+        pushed = await this.pushEvents();
+        this.stats.pushedEvents += pushed;
+      }
+      if (this.config.direction === "pull" || this.config.direction === "both") {
+        pulled = await this.pullEvents();
+        this.stats.pulledEvents += pulled;
+      }
+      this.stats.lastSyncAt = /* @__PURE__ */ new Date();
+      this.stats.status = "idle";
+      return { pushed, pulled };
+    } catch (error) {
+      this.stats.errors++;
+      this.stats.status = "error";
+      throw error;
+    }
+  }
+  async ensureConnected() {
+    if (this.client && this.db && this.counters && this.events)
+      return;
+    try {
+      this.client = new MongoClient(this.config.uri, {
+        appName: "claude-memory-layer",
+        serverSelectionTimeoutMS: 5e3
+      });
+      await this.client.connect();
+      this.db = this.client.db(this.config.dbName);
+      this.counters = this.db.collection("cml_counters");
+      this.events = this.db.collection("cml_events");
+    } catch (err) {
+      const safeUri = redactMongoUri(this.config.uri);
+      throw new Error(`MongoDB connection failed (${safeUri}, db=${this.config.dbName}): ${String(err)}`);
+    }
+  }
+  async disconnect() {
+    try {
+      await this.client?.close();
+    } finally {
+      this.client = null;
+      this.db = null;
+      this.counters = null;
+      this.events = null;
+      this.indexesEnsured = false;
+    }
+  }
+  async ensureIndexes() {
+    if (this.indexesEnsured)
+      return;
+    if (!this.events || !this.counters)
+      throw new Error("Mongo not connected");
+    try {
+      await this.events.createIndex({ projectKey: 1, seq: 1 }, { unique: true });
+      await this.events.createIndex({ projectKey: 1, eventId: 1 }, { unique: true });
+      await this.events.createIndex({ projectKey: 1, dedupeKey: 1 });
+    } catch (err) {
+      console.warn("[MongoSyncWorker] Failed to ensure indexes (continuing):", err);
+    }
+    this.indexesEnsured = true;
+  }
+  counterKey(kind) {
+    return `${kind}:${this.config.projectKey}`;
+  }
+  async allocateSeqRange(kind, count) {
+    if (!this.counters)
+      throw new Error("Mongo not connected");
+    if (count <= 0)
+      return 1;
+    const key = this.counterKey(kind);
+    const doc = await this.counters.findOneAndUpdate(
+      { _id: key },
+      { $inc: { seq: count } },
+      { upsert: true, returnDocument: "after" }
+    );
+    const endSeq = doc?.seq;
+    if (typeof endSeq !== "number") {
+      throw new Error(`Failed to allocate seq range for ${key}`);
+    }
+    return endSeq - count + 1;
+  }
+  pushTargetName() {
+    return `mongo_push_events_rowid:${this.config.projectKey}`;
+  }
+  pullTargetName() {
+    return `mongo_pull_events_seq:${this.config.projectKey}`;
+  }
+  async pushEvents() {
+    if (!this.events)
+      throw new Error("Mongo not connected");
+    const position = await this.sqliteStore.getSyncPosition(this.pushTargetName());
+    let lastRowid = parseIntOrZero(position.lastEventId);
+    let pushed = 0;
+    while (true) {
+      const batch = await this.sqliteStore.getEventsSinceRowid(lastRowid, this.config.batchSize);
+      if (batch.length === 0)
+        break;
+      const startSeq = await this.allocateSeqRange("events", batch.length);
+      const now = /* @__PURE__ */ new Date();
+      const hostname2 = os5.hostname();
+      const ops = batch.map((item, idx) => {
+        const event = item.event;
+        const seq = startSeq + idx;
+        const docId = `${this.config.projectKey}:${event.id}`;
+        return {
+          updateOne: {
+            filter: { _id: docId },
+            update: {
+              $setOnInsert: {
+                _id: docId,
+                projectKey: this.config.projectKey,
+                seq,
+                eventId: event.id,
+                eventType: event.eventType,
+                sessionId: event.sessionId,
+                timestamp: event.timestamp,
+                content: event.content,
+                canonicalKey: event.canonicalKey,
+                dedupeKey: event.dedupeKey,
+                metadata: event.metadata ?? null,
+                insertedAt: now,
+                updatedAt: now,
+                source: { hostname: hostname2, instanceId: this.config.instanceId }
+              }
+            },
+            upsert: true
+          }
+        };
+      });
+      await this.events.bulkWrite(ops, { ordered: false });
+      const last = batch[batch.length - 1];
+      lastRowid = last.rowid;
+      await this.sqliteStore.updateSyncPosition(
+        this.pushTargetName(),
+        String(lastRowid),
+        last.event.timestamp.toISOString()
+      );
+      pushed += batch.length;
+      if (batch.length < this.config.batchSize)
+        break;
+    }
+    return pushed;
+  }
+  async pullEvents() {
+    if (!this.events)
+      throw new Error("Mongo not connected");
+    const position = await this.sqliteStore.getSyncPosition(this.pullTargetName());
+    let lastSeq = parseIntOrZero(position.lastEventId);
+    let pulled = 0;
+    while (true) {
+      const docs = await this.events.find(
+        { projectKey: this.config.projectKey, seq: { $gt: lastSeq } },
+        { sort: { seq: 1 }, limit: this.config.batchSize }
+      ).toArray();
+      if (docs.length === 0)
+        break;
+      const events = docs.map((d) => ({
+        id: d.eventId,
+        eventType: d.eventType,
+        sessionId: d.sessionId,
+        timestamp: d.timestamp instanceof Date ? d.timestamp : new Date(d.timestamp),
+        content: d.content,
+        canonicalKey: d.canonicalKey,
+        dedupeKey: d.dedupeKey,
+        metadata: d.metadata ?? void 0
+      }));
+      const result = await this.sqliteStore.importEvents(events);
+      pulled += result.inserted;
+      lastSeq = docs[docs.length - 1].seq;
+      await this.sqliteStore.updateSyncPosition(
+        this.pullTargetName(),
+        String(lastSeq),
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+      if (docs.length < this.config.batchSize)
+        break;
+    }
+    return pulled;
+  }
+};
+
 // src/cli/index.ts
-var CLAUDE_SETTINGS_PATH = path4.join(os3.homedir(), ".claude", "settings.json");
+var CLAUDE_SETTINGS_PATH = path9.join(os6.homedir(), ".claude", "settings.json");
 function getPluginPath() {
   const possiblePaths = [
-    path4.join(__dirname, ".."),
+    path9.join(__dirname, ".."),
     // When running from dist/cli
-    path4.join(__dirname, "../..", "dist"),
+    path9.join(__dirname, "../..", "dist"),
     // When running from src
-    path4.join(process.cwd(), "dist")
+    path9.join(process.cwd(), "dist")
     // Current working directory
   ];
   for (const p of possiblePaths) {
-    const hooksPath = path4.join(p, "hooks", "user-prompt-submit.js");
-    if (fs4.existsSync(hooksPath)) {
+    const hooksPath = path9.join(p, "hooks", "user-prompt-submit.js");
+    if (fs9.existsSync(hooksPath)) {
       return p;
     }
   }
-  return path4.join(os3.homedir(), ".npm-global", "lib", "node_modules", "claude-memory-layer", "dist");
+  return path9.join(os6.homedir(), ".npm-global", "lib", "node_modules", "claude-memory-layer", "dist");
 }
 function loadClaudeSettings() {
   try {
-    if (fs4.existsSync(CLAUDE_SETTINGS_PATH)) {
-      const content = fs4.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+    if (fs9.existsSync(CLAUDE_SETTINGS_PATH)) {
+      const content = fs9.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
       return JSON.parse(content);
     }
   } catch (error) {
@@ -6249,13 +9180,13 @@ function loadClaudeSettings() {
   return {};
 }
 function saveClaudeSettings(settings) {
-  const dir = path4.dirname(CLAUDE_SETTINGS_PATH);
-  if (!fs4.existsSync(dir)) {
-    fs4.mkdirSync(dir, { recursive: true });
+  const dir = path9.dirname(CLAUDE_SETTINGS_PATH);
+  if (!fs9.existsSync(dir)) {
+    fs9.mkdirSync(dir, { recursive: true });
   }
   const tempPath = CLAUDE_SETTINGS_PATH + ".tmp";
-  fs4.writeFileSync(tempPath, JSON.stringify(settings, null, 2));
-  fs4.renameSync(tempPath, CLAUDE_SETTINGS_PATH);
+  fs9.writeFileSync(tempPath, JSON.stringify(settings, null, 2));
+  fs9.renameSync(tempPath, CLAUDE_SETTINGS_PATH);
 }
 function getHooksConfig(pluginPath) {
   return {
@@ -6265,7 +9196,7 @@ function getHooksConfig(pluginPath) {
         hooks: [
           {
             type: "command",
-            command: `node ${path4.join(pluginPath, "hooks", "user-prompt-submit.js")}`
+            command: `node ${path9.join(pluginPath, "hooks", "user-prompt-submit.js")}`
           }
         ]
       }
@@ -6276,7 +9207,7 @@ function getHooksConfig(pluginPath) {
         hooks: [
           {
             type: "command",
-            command: `node ${path4.join(pluginPath, "hooks", "post-tool-use.js")}`
+            command: `node ${path9.join(pluginPath, "hooks", "post-tool-use.js")}`
           }
         ]
       }
@@ -6284,12 +9215,12 @@ function getHooksConfig(pluginPath) {
   };
 }
 var program = new Command();
-program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.0");
+program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.12");
 program.command("install").description("Install hooks into Claude Code settings").option("--path <path>", "Custom plugin path (defaults to auto-detect)").action(async (options) => {
   try {
     const pluginPath = options.path || getPluginPath();
-    const userPromptHook = path4.join(pluginPath, "hooks", "user-prompt-submit.js");
-    if (!fs4.existsSync(userPromptHook)) {
+    const userPromptHook = path9.join(pluginPath, "hooks", "user-prompt-submit.js");
+    if (!fs9.existsSync(userPromptHook)) {
       console.error(`
 \u274C Hook files not found at: ${pluginPath}`);
       console.error('   Make sure you have built the plugin with "npm run build"');
@@ -6355,7 +9286,7 @@ program.command("status").description("Check plugin installation status").action
     console.log("Hooks:");
     console.log(`  UserPromptSubmit: ${hasUserPromptHook ? "\u2705 Installed" : "\u274C Not installed"}`);
     console.log(`  PostToolUse: ${hasPostToolHook ? "\u2705 Installed" : "\u274C Not installed"}`);
-    const hooksExist = fs4.existsSync(path4.join(pluginPath, "hooks", "user-prompt-submit.js"));
+    const hooksExist = fs9.existsSync(path9.join(pluginPath, "hooks", "user-prompt-submit.js"));
     console.log(`
 Plugin files: ${hooksExist ? "\u2705 Found" : "\u274C Not found"}`);
     console.log(`  Path: ${pluginPath}`);
@@ -6483,95 +9414,352 @@ program.command("process").description("Process pending embeddings").option("-p,
     process.exit(1);
   }
 });
-program.command("import").description("Import existing Claude Code conversation history").option("-p, --project <path>", "Import from specific project path").option("-s, --session <file>", "Import specific session file (JSONL)").option("-a, --all", "Import all sessions from all projects").option("-l, --limit <number>", "Limit messages per session").option("-v, --verbose", "Show detailed progress").action(async (options) => {
+program.command("mongo-sync").description("Sync events with MongoDB for multi-server collaboration (optional)").option("-p, --project <path>", "Project path (defaults to cwd)").option("--mongo-uri <uri>", "MongoDB connection URI (env: CLAUDE_MEMORY_MONGO_URI)").option("--mongo-db <name>", "MongoDB database name (env: CLAUDE_MEMORY_MONGO_DB)").option("--mongo-project <key>", "Remote project key (env: CLAUDE_MEMORY_MONGO_PROJECT, default: basename(projectPath))").option("--direction <dir>", "push|pull|both", "both").option("--batch-size <n>", "Batch size", "500").option("--interval <ms>", "Watch interval ms", "30000").option("--watch", "Run continuously").action(async (options) => {
+  const projectPath = options.project || process.cwd();
+  const mongoUri = options.mongoUri || process.env.CLAUDE_MEMORY_MONGO_URI;
+  const mongoDb = options.mongoDb || process.env.CLAUDE_MEMORY_MONGO_DB;
+  const projectKey = options.mongoProject || process.env.CLAUDE_MEMORY_MONGO_PROJECT || path9.basename(projectPath);
+  const direction = String(options.direction || "both").toLowerCase();
+  if (!mongoUri || !mongoDb) {
+    console.error("\n\u274C MongoDB sync is not configured.");
+    console.error("   Set --mongo-uri/--mongo-db or env CLAUDE_MEMORY_MONGO_URI/CLAUDE_MEMORY_MONGO_DB.\n");
+    process.exit(1);
+  }
+  if (!["push", "pull", "both"].includes(direction)) {
+    console.error("\n\u274C Invalid --direction. Use: push | pull | both\n");
+    process.exit(1);
+  }
+  const storagePath = getProjectStoragePath(projectPath);
+  if (!fs9.existsSync(storagePath)) {
+    fs9.mkdirSync(storagePath, { recursive: true });
+  }
+  const batchSizeParsed = parseInt(options.batchSize, 10);
+  const intervalParsed = parseInt(options.interval, 10);
+  const batchSize = Number.isFinite(batchSizeParsed) && batchSizeParsed > 0 ? batchSizeParsed : 500;
+  const intervalMs = Number.isFinite(intervalParsed) && intervalParsed > 0 ? intervalParsed : 3e4;
+  const sqliteStore = new SQLiteEventStore(path9.join(storagePath, "events.sqlite"));
+  const worker = new MongoSyncWorker(sqliteStore, {
+    uri: mongoUri,
+    dbName: mongoDb,
+    projectKey,
+    direction,
+    batchSize,
+    intervalMs
+  });
+  const runOnce = async () => {
+    const { pushed, pulled } = await worker.syncNow();
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    process.stdout.write(`[mongo-sync] ${ts} project=${projectKey} pushed=${pushed} pulled=${pulled}
+`);
+  };
+  try {
+    if (!options.watch) {
+      await runOnce();
+      await worker.shutdown();
+      sqliteStore.close();
+      return;
+    }
+    console.log(`[mongo-sync] Watch mode started (interval=${intervalMs}ms, project=${projectKey})`);
+    const handle = setInterval(() => {
+      runOnce().catch((err) => {
+        console.error("[mongo-sync] Sync failed:", err);
+      });
+    }, intervalMs);
+    const shutdown = async () => {
+      clearInterval(handle);
+      console.log("\n[mongo-sync] Shutting down...");
+      try {
+        await worker.shutdown();
+      } finally {
+        sqliteStore.close();
+      }
+      process.exit(0);
+    };
+    process.on("SIGINT", () => {
+      void shutdown();
+    });
+    process.on("SIGTERM", () => {
+      void shutdown();
+    });
+    await runOnce();
+    await new Promise(() => {
+    });
+  } catch (error) {
+    console.error("[mongo-sync] Failed:", error);
+    process.exit(1);
+  }
+});
+function renderProgress(event) {
+  switch (event.phase) {
+    case "scan":
+      console.log(`  \u{1F50D} ${event.message}`);
+      break;
+    case "session-start": {
+      const pct = Math.round(event.sessionIndex / event.totalSessions * 100);
+      const sessionName = path9.basename(event.filePath, ".jsonl").slice(0, 8);
+      process.stdout.write(
+        `\r  \u{1F4C4} [${event.sessionIndex + 1}/${event.totalSessions}] ${pct}% | Session ${sessionName}... `
+      );
+      break;
+    }
+    case "session-progress": {
+      process.stdout.write(
+        `\r  \u{1F4C4} [${event.sessionIndex + 1}/...] ${event.messagesProcessed} msgs | +${event.imported} imported, ~${event.skipped} skipped `
+      );
+      break;
+    }
+    case "session-done": {
+      const imported = event.importedPrompts + event.importedResponses;
+      if (imported > 0) {
+        process.stdout.write(
+          `\r  \u2705 [${event.sessionIndex + 1}] +${event.importedPrompts} prompts, +${event.importedResponses} responses${event.skipped > 0 ? `, ~${event.skipped} skipped` : ""}     
+`
+        );
+      } else if (event.skipped > 0) {
+        process.stdout.write(
+          `\r  \u23ED\uFE0F  [${event.sessionIndex + 1}] All ${event.skipped} already imported                          
+`
+        );
+      } else {
+        process.stdout.write(
+          `\r  \u23ED\uFE0F  [${event.sessionIndex + 1}] Empty session                                              
+`
+        );
+      }
+      break;
+    }
+    case "embedding":
+      process.stdout.write(
+        `\r  \u{1F9E0} Embeddings: ${event.processed}/${event.total} processed `
+      );
+      if (event.processed >= event.total) {
+        process.stdout.write("\n");
+      }
+      break;
+    case "done":
+      break;
+  }
+}
+function printImportSummary(result, embedCount) {
+  console.log("\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  console.log("\u2502       \u2705 Import Complete         \u2502");
+  console.log("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  console.log(`\u2502  Sessions processed:  ${String(result.totalSessions).padStart(8)} \u2502`);
+  console.log(`\u2502  Total messages:      ${String(result.totalMessages).padStart(8)} \u2502`);
+  console.log(`\u2502  Imported prompts:    ${String(result.importedPrompts).padStart(8)} \u2502`);
+  console.log(`\u2502  Imported responses:  ${String(result.importedResponses).padStart(8)} \u2502`);
+  console.log(`\u2502  Skipped duplicates:  ${String(result.skippedDuplicates).padStart(8)} \u2502`);
+  console.log(`\u2502  Embeddings queued:   ${String(embedCount).padStart(8)} \u2502`);
+  console.log("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+  if (result.errors.length > 0) {
+    console.log(`
+\u26A0\uFE0F  Errors (${result.errors.length}):`);
+    for (const error of result.errors.slice(0, 5)) {
+      console.log(`  - ${error}`);
+    }
+    if (result.errors.length > 5) {
+      console.log(`  ... and ${result.errors.length - 5} more`);
+    }
+  }
+}
+function sanitizeSegment3(input, fallback) {
+  const v = (input || "").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return v || fallback;
+}
+async function listMarkdownFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    const entries = await fs9.promises.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const full = path9.join(dir, e.name);
+      if (e.isDirectory())
+        stack.push(full);
+      else if (e.isFile() && e.name.endsWith(".md") && e.name !== "_index.md")
+        out.push(full);
+    }
+  }
+  return out.sort();
+}
+function deriveNamespaceCategory(sourceRoot, filePath) {
+  const rel = path9.relative(sourceRoot, filePath);
+  const dirSeg = path9.dirname(rel).split(path9.sep).filter(Boolean);
+  if (dirSeg.length >= 2) {
+    const namespace = sanitizeSegment3(dirSeg[0], "default");
+    const categoryPath = dirSeg.slice(1).map((s) => sanitizeSegment3(s, "uncategorized"));
+    return { namespace, categoryPath: categoryPath.length > 0 ? categoryPath : ["uncategorized"] };
+  }
+  return { namespace: "default", categoryPath: ["uncategorized"] };
+}
+function extractImportEvidence(markdown) {
+  const confidenceMatch = markdown.match(/^-\s*confidence:\s*([^\n]+)/m);
+  const sources = markdown.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("- source:")).map((line) => line.replace(/^-\s*source:\s*/i, "").trim()).filter(Boolean).slice(0, 30);
+  return {
+    confidence: confidenceMatch ? confidenceMatch[1].trim() : void 0,
+    sources
+  };
+}
+program.command("organize-import [sourceDir]").description("Import existing markdown memory files, or bootstrap knowledge docs from codebase/git when markdown is missing").option("-p, --project <path>", "Project path (defaults to cwd)").option("--session <id>", "Session id for imported events (default: import:organized)").option("--limit <n>", "Limit number of files to import").option("--dry-run", "Preview mapping without writing").option("--bootstrap", "Force-generate structured markdown from codebase + git history before import").option("--bootstrap-if-empty", "Auto-bootstrap when source has no markdown files (default: true)", true).option("--no-bootstrap-if-empty", "Disable auto-bootstrap when source has no markdown files").option("--force-bootstrap", "Run bootstrap even when markdown files exist").option("--repo <path>", "Repository root for bootstrap analysis (default: project path)").option("--out <path>", "Output directory for generated bootstrap markdown (default: <sourceDir>/bootstrap-kb)").option("--since <range>", 'Git history range for bootstrap (default: "180 days ago")').option("--max-commits <n>", "Max commits to analyze for bootstrap (default: 1000)").option("--incremental", "Use previous bootstrap manifest as baseline for incremental updates (default: true)", true).option("--no-incremental", "Disable incremental bootstrap; regenerate full snapshot").action(async (sourceDir, options) => {
+  const projectPath = options.project || process.cwd();
+  const sessionId = options.session || "import:organized";
+  const sourceRoot = path9.resolve(sourceDir || options.out || projectPath);
+  const repoPath = path9.resolve(options.repo || projectPath);
+  if (!fs9.existsSync(sourceRoot)) {
+    fs9.mkdirSync(sourceRoot, { recursive: true });
+  }
+  const service = getMemoryServiceForProject(projectPath);
+  try {
+    let activeSourceRoot = sourceRoot;
+    let importRoot = sourceRoot;
+    let files = await listMarkdownFiles(importRoot);
+    const hasMarkdown = files.length > 0;
+    const shouldBootstrap = Boolean(options.forceBootstrap || options.bootstrap || !hasMarkdown && options.bootstrapIfEmpty);
+    if (shouldBootstrap) {
+      const outDir = path9.resolve(options.out || path9.join(sourceRoot, "bootstrap-kb"));
+      const since = options.since || "180 days ago";
+      const maxCommits = options.maxCommits ? Math.max(1, parseInt(options.maxCommits, 10)) : 1e3;
+      console.log("\n\u{1F9E0} Bootstrapping markdown knowledge base...");
+      const bootstrap = await bootstrapKnowledgeBase({
+        repoPath,
+        outDir,
+        since,
+        maxCommits,
+        incremental: options.incremental
+      });
+      console.log(`  Repo: ${repoPath}`);
+      console.log(`  Output: ${bootstrap.outDir}`);
+      console.log(`  Files analyzed: ${bootstrap.fileCount}`);
+      console.log(`  Commits analyzed: ${bootstrap.commitCount}`);
+      console.log(`  Modules: ${bootstrap.moduleCount}`);
+      activeSourceRoot = outDir;
+      importRoot = outDir;
+      files = await listMarkdownFiles(importRoot);
+    }
+    if (files.length === 0) {
+      console.error("\n\u274C organize-import found no markdown files to import.\n");
+      process.exit(1);
+    }
+    const limit = options.limit ? Math.max(1, parseInt(options.limit, 10)) : files.length;
+    const targets = files.slice(0, limit);
+    console.log(`
+\u{1F4E6} organize-import`);
+    console.log(`  Source: ${activeSourceRoot}`);
+    console.log(`  Project: ${projectPath}`);
+    console.log(`  Files: ${targets.length}${targets.length < files.length ? `/${files.length}` : ""}`);
+    console.log(`  Dry-run: ${options.dryRun ? "yes" : "no"}
+`);
+    if (!options.dryRun) {
+      await service.initialize();
+    }
+    let imported = 0;
+    let skipped = 0;
+    for (const file of targets) {
+      const text = await fs9.promises.readFile(file, "utf8");
+      if (!text.trim()) {
+        skipped += 1;
+        continue;
+      }
+      const { namespace, categoryPath } = deriveNamespaceCategory(activeSourceRoot, file);
+      const rel = path9.relative(activeSourceRoot, file);
+      const evidence = extractImportEvidence(text);
+      if (options.dryRun) {
+        console.log(`- ${rel} -> namespace=${namespace} category=${categoryPath.join("/")} confidence=${evidence.confidence || "n/a"} sources=${evidence.sources.length}`);
+        continue;
+      }
+      await service.storeSessionSummary(sessionId, text, {
+        namespace,
+        categoryPath,
+        confidence: evidence.confidence,
+        sources: evidence.sources,
+        import: {
+          sourceFile: rel,
+          importedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          bootstrap: shouldBootstrap === true
+        }
+      });
+      imported += 1;
+    }
+    if (!options.dryRun) {
+      const embed = await service.processPendingEmbeddings();
+      await service.shutdown();
+      console.log(`
+\u2705 Imported: ${imported}, skipped-empty: ${skipped}, embeddings: ${embed}
+`);
+    } else {
+      console.log(`
+\u2705 Dry-run complete (planned imports: ${targets.length - skipped}, skipped-empty: ${skipped})
+`);
+    }
+  } catch (error) {
+    console.error("\n\u274C organize-import failed:", error);
+    process.exit(1);
+  }
+});
+program.command("import").description("Import existing Claude Code conversation history").option("-p, --project <path>", "Import from specific project path").option("-s, --session <file>", "Import specific session file (JSONL)").option("-a, --all", "Import all sessions from all projects").option("-l, --limit <number>", "Limit messages per session").option("-f, --force", "Force reimport: delete existing events and reimport with turn_id grouping").option("-v, --verbose", "Show detailed progress").action(async (options) => {
+  const startTime = Date.now();
   const targetProjectPath = options.project || process.cwd();
   const service = getMemoryServiceForProject(targetProjectPath);
   const importer = createSessionHistoryImporter(service);
+  const importOpts = {
+    limit: options.limit ? parseInt(options.limit) : void 0,
+    force: options.force,
+    verbose: options.verbose,
+    onProgress: renderProgress
+  };
   try {
+    console.log("\n\u23F3 Initializing memory service...");
     await service.initialize();
+    console.log("  \u2705 Ready\n");
+    if (options.force) {
+      console.log("\u{1F504} Force mode: existing events will be deleted and reimported with turn_id grouping\n");
+    }
     let result;
     if (options.session) {
-      console.log(`
-\u{1F4E5} Importing session: ${options.session}`);
-      console.log(`   Target project: ${targetProjectPath}
+      console.log(`\u{1F4E5} Importing session: ${options.session}`);
+      console.log(`   Target: ${targetProjectPath}
 `);
       result = await importer.importSessionFile(options.session, {
-        projectPath: targetProjectPath,
-        limit: options.limit ? parseInt(options.limit) : void 0,
-        verbose: options.verbose
+        ...importOpts,
+        projectPath: targetProjectPath
       });
     } else if (options.project) {
-      console.log(`
-\u{1F4E5} Importing project: ${options.project}
+      console.log(`\u{1F4E5} Importing project: ${options.project}
 `);
-      result = await importer.importProject(options.project, {
-        limit: options.limit ? parseInt(options.limit) : void 0,
-        verbose: options.verbose
-      });
+      result = await importer.importProject(options.project, importOpts);
     } else if (options.all) {
-      console.log("\n\u{1F4E5} Importing all sessions from all projects");
+      console.log("\u{1F4E5} Importing all sessions from all projects");
       console.log("   \u26A0\uFE0F  Using global storage (use -p for project-specific)\n");
       const globalService = getDefaultMemoryService();
       const globalImporter = createSessionHistoryImporter(globalService);
       await globalService.initialize();
-      result = await globalImporter.importAll({
-        limit: options.limit ? parseInt(options.limit) : void 0,
-        verbose: options.verbose
-      });
-      console.log("\n\u23F3 Processing embeddings...");
+      result = await globalImporter.importAll(importOpts);
+      console.log("\n\u{1F9E0} Processing embeddings...");
       const embedCount2 = await globalService.processPendingEmbeddings();
-      console.log("\n\u2705 Import Complete\n");
-      console.log(`Sessions processed: ${result.totalSessions}`);
-      console.log(`Total messages: ${result.totalMessages}`);
-      console.log(`Imported prompts: ${result.importedPrompts}`);
-      console.log(`Imported responses: ${result.importedResponses}`);
-      console.log(`Skipped duplicates: ${result.skippedDuplicates}`);
-      console.log(`Embeddings processed: ${embedCount2}`);
-      if (result.errors.length > 0) {
-        console.log(`
-\u26A0\uFE0F  Errors (${result.errors.length}):`);
-        for (const error of result.errors.slice(0, 5)) {
-          console.log(`  - ${error}`);
-        }
-        if (result.errors.length > 5) {
-          console.log(`  ... and ${result.errors.length - 5} more`);
-        }
-      }
+      const elapsed2 = ((Date.now() - startTime) / 1e3).toFixed(1);
+      printImportSummary(result, embedCount2);
+      console.log(`
+\u23F1\uFE0F  Completed in ${elapsed2}s`);
       await globalService.shutdown();
       return;
     } else {
       const cwd = process.cwd();
-      console.log(`
-\u{1F4E5} Importing sessions for current project: ${cwd}
+      console.log(`\u{1F4E5} Importing sessions for: ${cwd}
 `);
       result = await importer.importProject(cwd, {
-        projectPath: cwd,
-        limit: options.limit ? parseInt(options.limit) : void 0,
-        verbose: options.verbose
+        ...importOpts,
+        projectPath: cwd
       });
     }
-    console.log("\n\u23F3 Processing embeddings...");
+    console.log("\n\u{1F9E0} Processing embeddings...");
     const embedCount = await service.processPendingEmbeddings();
-    console.log("\n\u2705 Import Complete\n");
-    console.log(`Sessions processed: ${result.totalSessions}`);
-    console.log(`Total messages: ${result.totalMessages}`);
-    console.log(`Imported prompts: ${result.importedPrompts}`);
-    console.log(`Imported responses: ${result.importedResponses}`);
-    console.log(`Skipped duplicates: ${result.skippedDuplicates}`);
-    console.log(`Embeddings processed: ${embedCount}`);
-    if (result.errors.length > 0) {
-      console.log(`
-\u26A0\uFE0F  Errors (${result.errors.length}):`);
-      for (const error of result.errors.slice(0, 5)) {
-        console.log(`  - ${error}`);
-      }
-      if (result.errors.length > 5) {
-        console.log(`  ... and ${result.errors.length - 5} more`);
-      }
-    }
+    const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+    printImportSummary(result, embedCount);
+    console.log(`
+\u23F1\uFE0F  Completed in ${elapsed}s`);
     await service.shutdown();
   } catch (error) {
-    console.error("Import failed:", error);
+    console.error("\n\u274C Import failed:", error);
     process.exit(1);
   }
 });