@yeaft/webchat-agent 0.1.643 → 0.1.646

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.643",
+  "version": "0.1.646",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/memory/ams.js

@@ -0,0 +1,197 @@
+/**
+ * memory/ams.js — DESIGN-H2-AMS §5. Active Memory Set.
+ *
+ * Per-group session state. Three layers:
+ *
+ *   resident   summaries of all relevant scopes — always-on, high precision
+ *   recent     LRU of segments touched in last N turns — warm cache
+ *   onDemand   segments the pre-flow FTS pulled in this turn — hot recall
+ *
+ * AMS is in-memory; it's rebuilt at session start. The disk source of
+ * truth is `<scope>/memory.md` + `<scope>/summary.md`. AMS itself
+ * doesn't write to disk — that's Dream's job.
+ *
+ * Privacy (DESIGN-v2 §2.2): `vp/<other>` scopes are ALWAYS filtered out
+ * for any worker that isn't `<other>`. The owning code passes its own
+ * vpId at construction.
+ */
+
+import { approxTokens, packWithinBudget } from './budget.js';
+
+const RECENT_DEFAULT_CAPACITY = 64;
+
+/**
+ * @typedef {object} AmsLayers
+ * @property {Map<string, string>}                resident
+ * @property {Array<{ id: string, seg: import('./segment.js').Segment, ts: number }>} recent
+ * @property {Map<string, import('./segment.js').Segment>} onDemand
+ */
+
+/**
+ * @typedef {object} AmsSnapshot
+ * @property {Array<{ scope: string, summary: string }>} resident
+ * @property {import('./segment.js').Segment[]} recent
+ * @property {import('./segment.js').Segment[]} onDemand
+ * @property {{ resident: number, recent: number, onDemand: number, total: number }} usage
+ */
+
+export class ActiveMemorySet {
+  /**
+   * @param {{
+   *   ownVpId?: string | null,
+   *   budget: import('./budget.js').BudgetSplit,
+   *   recentCapacity?: number,
+   * }} opts
+   */
+  constructor(opts) {
+    if (!opts || !opts.budget) throw new Error('ActiveMemorySet: budget required');
+    this.ownVpId = opts.ownVpId || null;
+    this.budget = opts.budget;
+    this.recentCapacity = opts.recentCapacity || RECENT_DEFAULT_CAPACITY;
+    /** @type {Map<string, string>} */
+    this._resident = new Map();          // scope → summaryText
+    /** @type {Map<string, { seg: import('./segment.js').Segment, ts: number }>} */
+    this._recent = new Map();            // segId → entry (insertion-order is LRU order)
+    /** @type {Map<string, import('./segment.js').Segment>} */
+    this._onDemand = new Map();          // segId → segment
+  }
+
+  // ────────────────────────── resident ──────────────────────────
+
+  /**
+   * Replace the resident layer with a fresh set of scope→summary
+   * pairs. Foreign VP scopes are silently dropped.
+   *
+   * @param {Array<{ scope: string, summary: string }>} entries
+   */
+  setResident(entries) {
+    this._resident.clear();
+    for (const e of entries) {
+      if (this._isForeignVp(e.scope)) continue;
+      if (!e.summary) continue;
+      this._resident.set(e.scope, e.summary);
+    }
+  }
+
+  // ────────────────────────── recent ──────────────────────────
+
+  /**
+   * Touch a segment as "used this turn". LRU semantics: most-recent at
+   * the end. Trims to capacity automatically.
+   *
+   * @param {import('./segment.js').Segment} seg
+   */
+  touchRecent(seg) {
+    if (!seg || !seg.id) return;
+    if (this._isForeignVp(seg.scope)) return;
+    if (this._recent.has(seg.id)) this._recent.delete(seg.id);
+    this._recent.set(seg.id, { seg, ts: Date.now() });
+    while (this._recent.size > this.recentCapacity) {
+      const firstKey = this._recent.keys().next().value;
+      this._recent.delete(firstKey);
+    }
+  }
+
+  // ────────────────────────── onDemand ──────────────────────────
+
+  /**
+   * Replace the onDemand layer with this turn's FTS hits.
+   *
+   * @param {import('./segment.js').Segment[]} segments
+   */
+  setOnDemand(segments) {
+    this._onDemand.clear();
+    for (const seg of segments) {
+      if (this._isForeignVp(seg.scope)) continue;
+      this._onDemand.set(seg.id, seg);
+    }
+  }
+
+  /**
+   * Add segments to onDemand without clearing (used by adjustMemory).
+   *
+   * @param {import('./segment.js').Segment[]} segments
+   */
+  addOnDemand(segments) {
+    for (const seg of segments) {
+      if (this._isForeignVp(seg.scope)) continue;
+      this._onDemand.set(seg.id, seg);
+    }
+  }
+
+  /**
+   * Remove segment ids from onDemand (used by adjustMemory eviction).
+   *
+   * @param {string[]} ids
+   */
+  removeOnDemand(ids) {
+    for (const id of ids) this._onDemand.delete(id);
+  }
+
+  // ────────────────────────── snapshot ──────────────────────────
+
+  /**
+   * Produce a budget-aware snapshot that can be injected into the
+   * system prompt. Each layer is greedily packed within its budget;
+   * overflow is dropped from this turn but not from disk.
+   *
+   * @returns {AmsSnapshot}
+   */
+  snapshot() {
+    // Resident: pack scopes by priority order (caller provides via insert
+    // order — current group's own vp first, then user, etc.).
+    const resEntries = [...this._resident.entries()].map(([scope, summary]) => ({
+      scope, summary,
+    }));
+    const { picked: resPicked, cost: resCost } = packWithinBudget(
+      resEntries, this.budget.resident,
+      e => approxTokens(e.summary),
+    );
+
+    // Recent: insertion order is oldest-first; we want newest first.
+    const recentArr = [...this._recent.values()]
+      .reverse()
+      .map(e => e.seg);
+    const { picked: recPicked, cost: recCost } = packWithinBudget(
+      recentArr, this.budget.recent,
+      seg => approxTokens(seg.body),
+    );
+
+    // OnDemand: insertion order from caller (already FTS-ranked).
+    const odArr = [...this._onDemand.values()];
+    const { picked: odPicked, cost: odCost } = packWithinBudget(
+      odArr, this.budget.onDemand,
+      seg => approxTokens(seg.body),
+    );
+
+    return {
+      resident: resPicked,
+      recent: recPicked,
+      onDemand: odPicked,
+      usage: {
+        resident: resCost,
+        recent: recCost,
+        onDemand: odCost,
+        total: resCost + recCost + odCost,
+      },
+    };
+  }
+
+  /**
+   * Read-only inspectors (for tests / observability / adjustMemory input).
+   */
+  residentScopes() { return [...this._resident.keys()]; }
+  recentIds()      { return [...this._recent.keys()]; }
+  onDemandIds()    { return [...this._onDemand.keys()]; }
+  onDemandSegments() { return [...this._onDemand.values()]; }
+  size() { return this._resident.size + this._recent.size + this._onDemand.size; }
+
+  // ────────────────────────── privacy ──────────────────────────
+
+  _isForeignVp(scope) {
+    if (!scope || !scope.startsWith('vp/')) return false;
+    if (!this.ownVpId) return false;        // no own id → no filtering
+    const other = scope.slice(3).split('/')[0];
+    return other !== this.ownVpId;
+  }
+}

package/unify/memory/budget.js

@@ -0,0 +1,111 @@
+/**
+ * memory/budget.js — DESIGN-H2-AMS §5.2.
+ *
+ * Memory budget = `min(50_000, modelMaxContext * 0.10)`.
+ *
+ * Then split across the three AMS layers (resident / recent / onDemand)
+ * with a configurable ratio. The defaults are tuned for ~200k context
+ * models (Claude / GPT-5):
+ *
+ *   resident   40%   →  20k   (all relevant scope summaries)
+ *   recent     25%   →  12.5k (LRU of recently-used segments)
+ *   onDemand   35%   →  17.5k (this turn's FTS recall)
+ *
+ * Token counting here is approximate (chars / 4) — accurate enough for
+ * budget enforcement. The engine has a real tokenizer for prompt
+ * assembly; budget here is a guard rail, not the source of truth.
+ */
+
+export const ABSOLUTE_CAP = 50_000;
+export const MODEL_FRACTION = 0.10;
+
+export const DEFAULT_RATIO = {
+  resident: 0.40,
+  recent:   0.25,
+  onDemand: 0.35,
+};
+
+/**
+ * @typedef {object} BudgetSplit
+ * @property {number} total
+ * @property {number} resident
+ * @property {number} recent
+ * @property {number} onDemand
+ */
+
+/**
+ * @param {number} modelMaxContext   tokens of the model's full context window
+ * @param {Partial<typeof DEFAULT_RATIO>} [ratio]
+ * @returns {BudgetSplit}
+ */
+export function computeBudget(modelMaxContext, ratio = {}) {
+  const ctx = Number.isFinite(modelMaxContext) && modelMaxContext > 0
+    ? modelMaxContext : 200_000;
+  const total = Math.min(ABSOLUTE_CAP, Math.floor(ctx * MODEL_FRACTION));
+
+  const r = { ...DEFAULT_RATIO, ...ratio };
+  // Normalise so ratios sum to 1 (defensive).
+  const sum = r.resident + r.recent + r.onDemand;
+  const norm = sum > 0 ? sum : 1;
+  return {
+    total,
+    resident: Math.floor(total * (r.resident / norm)),
+    recent:   Math.floor(total * (r.recent   / norm)),
+    onDemand: Math.floor(total * (r.onDemand / norm)),
+  };
+}
+
+/**
+ * Approximate token count of a string. Avg English ≈ 4 chars / token,
+ * Chinese ≈ 1 char / token. We use a conservative blended estimate.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function approxTokens(text) {
+  if (!text) return 0;
+  // Count CJK chars as ~1 token each, the rest as char/4.
+  let cjk = 0;
+  let other = 0;
+  for (const ch of text) {
+    const c = ch.codePointAt(0) || 0;
+    if (
+      (c >= 0x4e00 && c <= 0x9fff) ||
+      (c >= 0x3040 && c <= 0x309f) ||
+      (c >= 0x30a0 && c <= 0x30ff) ||
+      (c >= 0xac00 && c <= 0xd7af)
+    ) {
+      cjk += 1;
+    } else {
+      other += 1;
+    }
+  }
+  return Math.ceil(cjk + other / 4);
+}
+
+/**
+ * Greedy pack: pick items in order until adding the next would exceed
+ * the budget. Returns the picked list and the total cost. Does NOT
+ * sort — caller decides ordering.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {number} budget
+ * @param {(item: T) => number} costFn
+ * @returns {{ picked: T[], cost: number, dropped: T[] }}
+ */
+export function packWithinBudget(items, budget, costFn) {
+  const picked = [];
+  const dropped = [];
+  let cost = 0;
+  for (const it of items) {
+    const c = costFn(it);
+    if (cost + c <= budget) {
+      picked.push(it);
+      cost += c;
+    } else {
+      dropped.push(it);
+    }
+  }
+  return { picked, cost, dropped };
+}

package/unify/memory/index-db.js

@@ -0,0 +1,269 @@
+/**
+ * memory/index-db.js — DESIGN-H2-AMS §4. SQLite + FTS5 segment index.
+ *
+ * Source of truth: on-disk `~/.yeaft/memory/<scope>/memory.md` files.
+ * SQLite is a derived index — rebuildable from disk at any time.
+ *
+ * Schema is created idempotently; opening an older DB without the
+ * required tables triggers a fresh CREATE. A version PRAGMA guards
+ * against silent schema drift.
+ *
+ * Uses node:sqlite (Node 22.5+ built-in). Synchronous API — fine for
+ * our workload (10k segments, single-process agent).
+ */
+
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export const SCHEMA_VERSION = 1;
+
+const DDL = [
+  `PRAGMA journal_mode = WAL;`,
+  `PRAGMA synchronous = NORMAL;`,
+  `PRAGMA foreign_keys = ON;`,
+
+  `CREATE TABLE IF NOT EXISTS schema_meta (
+     key   TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+   );`,
+
+  `CREATE TABLE IF NOT EXISTS memory_segments (
+     id          TEXT PRIMARY KEY,
+     scope       TEXT NOT NULL,
+     kind        TEXT NOT NULL,
+     tags        TEXT NOT NULL DEFAULT '[]',
+     body        TEXT NOT NULL,
+     source_msgs TEXT NOT NULL DEFAULT '[]',
+     created_at  INTEGER NOT NULL,
+     updated_at  INTEGER NOT NULL
+   );`,
+
+  `CREATE INDEX IF NOT EXISTS idx_segments_scope
+     ON memory_segments(scope);`,
+
+  `CREATE INDEX IF NOT EXISTS idx_segments_updated
+     ON memory_segments(updated_at DESC);`,
+
+  `CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+     body, tags, scope,
+     content='memory_segments',
+     content_rowid='rowid',
+     tokenize='unicode61 remove_diacritics 2'
+   );`,
+
+  `CREATE TRIGGER IF NOT EXISTS seg_ai AFTER INSERT ON memory_segments BEGIN
+     INSERT INTO memory_fts(rowid, body, tags, scope)
+     VALUES (new.rowid, new.body, new.tags, new.scope);
+   END;`,
+
+  `CREATE TRIGGER IF NOT EXISTS seg_au AFTER UPDATE ON memory_segments BEGIN
+     INSERT INTO memory_fts(memory_fts, rowid, body, tags, scope)
+     VALUES('delete', old.rowid, old.body, old.tags, old.scope);
+     INSERT INTO memory_fts(rowid, body, tags, scope)
+     VALUES (new.rowid, new.body, new.tags, new.scope);
+   END;`,
+
+  `CREATE TRIGGER IF NOT EXISTS seg_ad AFTER DELETE ON memory_segments BEGIN
+     INSERT INTO memory_fts(memory_fts, rowid, body, tags, scope)
+     VALUES('delete', old.rowid, old.body, old.tags, old.scope);
+   END;`,
+];
+
+/**
+ * Open (or create) the segment index DB. Returns a thin handle with
+ * the operations the rest of the memory layer needs. The handle owns
+ * the underlying DatabaseSync; call `.close()` when done.
+ *
+ * @param {string} dbPath  Absolute path to the .db file.
+ * @returns {SegmentIndex}
+ */
+export function openSegmentIndex(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  for (const stmt of DDL) db.exec(stmt);
+
+  // Version check / set
+  const cur = db.prepare('SELECT value FROM schema_meta WHERE key=?').get('schema_version');
+  if (!cur) {
+    db.prepare('INSERT INTO schema_meta(key,value) VALUES(?,?)')
+      .run('schema_version', String(SCHEMA_VERSION));
+  } else if (cur.value !== String(SCHEMA_VERSION)) {
+    // For now, simple drop-and-recreate. v2 may add migrations.
+    db.exec('DROP TABLE IF EXISTS memory_fts');
+    db.exec('DROP TABLE IF EXISTS memory_segments');
+    db.exec('DELETE FROM schema_meta');
+    for (const stmt of DDL) db.exec(stmt);
+    db.prepare('INSERT INTO schema_meta(key,value) VALUES(?,?)')
+      .run('schema_version', String(SCHEMA_VERSION));
+  }
+
+  return makeHandle(db);
+}
+
+/**
+ * @typedef {object} SegmentIndex
+ * @property {(seg: import('./segment.js').Segment) => void} upsert
+ * @property {(ids: string[]) => void} deleteMany
+ * @property {(scope: string) => void} deleteScope
+ * @property {(id: string) => import('./segment.js').Segment | null} get
+ * @property {(scope: string) => import('./segment.js').Segment[]} listByScope
+ * @property {(opts: SearchOpts) => SearchHit[]} search
+ * @property {() => number} count
+ * @property {() => void} close
+ * @property {DatabaseSync} _db   exposed for tests / advanced ops
+ */
+
+/**
+ * @typedef {object} SearchOpts
+ * @property {string}        query        FTS5 MATCH expression
+ * @property {string[]=}     scopeFilter  if set, restrict to these scopes
+ * @property {number=}       limit        default 50
+ */
+
+/**
+ * @typedef {object} SearchHit
+ * @property {string} id
+ * @property {string} scope
+ * @property {string} kind
+ * @property {string[]} tags
+ * @property {string} body
+ * @property {string[]} sourceMessages
+ * @property {number} rank        bm25 (lower = better)
+ * @property {number} createdAt
+ * @property {number} updatedAt
+ */
+
+function makeHandle(db) {
+  const stmtUpsert = db.prepare(`
+    INSERT INTO memory_segments(id, scope, kind, tags, body, source_msgs, created_at, updated_at)
+    VALUES (@id, @scope, @kind, @tags, @body, @sourceMsgs, @createdAt, @updatedAt)
+    ON CONFLICT(id) DO UPDATE SET
+      scope=excluded.scope,
+      kind=excluded.kind,
+      tags=excluded.tags,
+      body=excluded.body,
+      source_msgs=excluded.source_msgs,
+      updated_at=excluded.updated_at
+  `);
+  const stmtDeleteOne = db.prepare('DELETE FROM memory_segments WHERE id=?');
+  const stmtDeleteScope = db.prepare('DELETE FROM memory_segments WHERE scope=?');
+  const stmtGet = db.prepare('SELECT * FROM memory_segments WHERE id=?');
+  const stmtListByScope = db.prepare(
+    'SELECT * FROM memory_segments WHERE scope=? ORDER BY created_at ASC',
+  );
+  const stmtCount = db.prepare('SELECT COUNT(*) AS n FROM memory_segments');
+
+  return {
+    _db: db,
+
+    upsert(seg) {
+      stmtUpsert.run({
+        id: seg.id,
+        scope: seg.scope,
+        kind: seg.kind,
+        tags: JSON.stringify(seg.tags || []),
+        body: seg.body,
+        sourceMsgs: JSON.stringify(seg.sourceMessages || []),
+        createdAt: toEpochMs(seg.createdAt),
+        updatedAt: toEpochMs(seg.updatedAt),
+      });
+    },
+
+    deleteMany(ids) {
+      if (!Array.isArray(ids) || ids.length === 0) return;
+      const tx = db.prepare('BEGIN');
+      tx.run();
+      try {
+        for (const id of ids) stmtDeleteOne.run(id);
+        db.prepare('COMMIT').run();
+      } catch (err) {
+        db.prepare('ROLLBACK').run();
+        throw err;
+      }
+    },
+
+    deleteScope(scope) { stmtDeleteScope.run(scope); },
+
+    get(id) {
+      const row = stmtGet.get(id);
+      return row ? rowToSegment(row) : null;
+    },
+
+    listByScope(scope) {
+      return stmtListByScope.all(scope).map(rowToSegment);
+    },
+
+    /**
+     * @param {SearchOpts} opts
+     * @returns {SearchHit[]}
+     */
+    search(opts) {
+      const limit = Number.isFinite(opts.limit) && opts.limit > 0
+        ? Math.min(500, Math.floor(opts.limit)) : 50;
+      const scopeFilter = Array.isArray(opts.scopeFilter) && opts.scopeFilter.length > 0
+        ? opts.scopeFilter : null;
+
+      // Build the SQL dynamically — scope IN (...) needs N placeholders.
+      let sql = `
+        SELECT s.*, bm25(memory_fts) AS rank
+        FROM memory_fts
+        JOIN memory_segments s ON s.rowid = memory_fts.rowid
+        WHERE memory_fts MATCH ?`;
+      const params = [opts.query];
+      if (scopeFilter) {
+        sql += ` AND s.scope IN (${scopeFilter.map(() => '?').join(',')})`;
+        params.push(...scopeFilter);
+      }
+      sql += ` ORDER BY rank LIMIT ?`;
+      params.push(limit);
+
+      const rows = db.prepare(sql).all(...params);
+      return rows.map(r => ({
+        ...rowToSegment(r),
+        rank: r.rank,
+      }));
+    },
+
+    count() {
+      return stmtCount.get().n;
+    },
+
+    close() {
+      db.close();
+    },
+  };
+}
+
+function rowToSegment(row) {
+  return {
+    id: row.id,
+    scope: row.scope,
+    kind: row.kind,
+    tags: safeJsonArr(row.tags),
+    body: row.body,
+    sourceMessages: safeJsonArr(row.source_msgs),
+    createdAt: fromEpochMs(row.created_at),
+    updatedAt: fromEpochMs(row.updated_at),
+  };
+}
+
+function safeJsonArr(s) {
+  if (!s) return [];
+  try {
+    const v = JSON.parse(s);
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+
+function toEpochMs(iso) {
+  if (typeof iso === 'number') return iso;
+  const t = Date.parse(iso || '');
+  return Number.isFinite(t) ? t : Date.now();
+}
+
+function fromEpochMs(ms) {
+  return new Date(Number(ms) || Date.now()).toISOString();
+}

package/unify/memory/segment-store.js

@@ -0,0 +1,91 @@
+/**
+ * memory/segment-store.js — disk I/O for segment-formatted memory.md.
+ *
+ * Bridges between the on-disk format (memory.md per scope, multiple
+ * segment blocks) and the SQLite segment index. This layer handles
+ * scope <-> file path mapping; the index layer is scope-agnostic.
+ *
+ * Path conventions (DESIGN-v2 §5):
+ *   ~/.yeaft/memory/user/memory.md
+ *   ~/.yeaft/memory/vp/<id>/memory.md
+ *   ~/.yeaft/memory/group/<id>/memory.md
+ *   ~/.yeaft/memory/feature/<id>/memory.md
+ *   ~/.yeaft/memory/topic/<l1>/memory.md
+ *   ~/.yeaft/memory/topic/<l1>/<l2>/memory.md
+ */
+
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync,
+  readdirSync, statSync, renameSync,
+} from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { parseSegments, serializeSegments } from './segment.js';
+
+/**
+ * Read all segments for a given scope from disk.
+ *
+ * @param {string} memoryRoot   e.g. ~/.yeaft/memory
+ * @param {string} scope
+ * @returns {import('./segment.js').Segment[]}
+ */
+export function readScope(memoryRoot, scope) {
+  const path = scopeFilePath(memoryRoot, scope);
+  if (!existsSync(path)) return [];
+  const text = readFileSync(path, 'utf8');
+  return parseSegments(text, { defaultScope: scope });
+}
+
+/**
+ * Atomically write segments for a scope. Creates the directory if
+ * needed. Empty array → empties the file (we keep the file so absence
+ * means "scope never existed").
+ *
+ * @param {string} memoryRoot
+ * @param {string} scope
+ * @param {import('./segment.js').Segment[]} segments
+ */
+export function writeScope(memoryRoot, scope, segments) {
+  const path = scopeFilePath(memoryRoot, scope);
+  mkdirSync(dirname(path), { recursive: true });
+  const text = serializeSegments(segments);
+  // atomic-ish write: tmp file + rename
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, text, 'utf8');
+  renameSync(tmp, path);
+}
+
+/**
+ * Walk the memory root and return all scopes that have a memory.md.
+ *
+ * @param {string} memoryRoot
+ * @returns {string[]}
+ */
+export function listScopes(memoryRoot) {
+  if (!existsSync(memoryRoot)) return [];
+  const out = [];
+  walk(memoryRoot, memoryRoot, out);
+  return out;
+}
+
+function walk(root, dir, out) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) {
+      walk(root, full, out);
+    } else if (entry === 'memory.md') {
+      const rel = relative(root, dir).split(sep).join('/');
+      if (rel) out.push(rel);
+    }
+  }
+}
+
+/**
+ * @param {string} memoryRoot
+ * @param {string} scope
+ * @returns {string}
+ */
+export function scopeFilePath(memoryRoot, scope) {
+  return join(memoryRoot, scope, 'memory.md');
+}

package/unify/memory/segment-sync.js

@@ -0,0 +1,110 @@
+/**
+ * memory/segment-sync.js — disk → SQLite reconciliation.
+ *
+ * Source of truth is on-disk memory.md per scope. SQLite is a derived
+ * index. This module reads disk, diffs against SQLite, and emits
+ * upsert / delete operations.
+ *
+ * Strategy:
+ *   - For each scope on disk: read all segments → upsert into index.
+ *   - For ids that exist in index for that scope but no longer on
+ *     disk: delete.
+ *   - For scopes that exist in index but no longer on disk: deleteScope.
+ *
+ * Cost: O(N) read + O(N) upsert per call. Fine for boot-time and
+ * post-Dream sync. For high-frequency syncs caller can pass a single
+ * scope to limit work (`syncScope`).
+ */
+
+import { listScopes, readScope } from './segment-store.js';
+
+/**
+ * Full sync: walk disk, reconcile every scope into the index. Returns
+ * counts for telemetry.
+ *
+ * @param {string} memoryRoot
+ * @param {import('./index-db.js').SegmentIndex} index
+ * @returns {{ scopes: number, upserted: number, deleted: number }}
+ */
+export function syncAll(memoryRoot, index) {
+  const diskScopes = new Set(listScopes(memoryRoot));
+  const indexScopes = new Set(allScopesFromIndex(index));
+
+  let upserted = 0;
+  let deleted = 0;
+
+  for (const scope of diskScopes) {
+    const r = syncScope(memoryRoot, index, scope);
+    upserted += r.upserted;
+    deleted += r.deleted;
+  }
+
+  // Scopes in index but not on disk → drop entirely.
+  for (const scope of indexScopes) {
+    if (!diskScopes.has(scope)) {
+      const before = index.listByScope(scope).length;
+      index.deleteScope(scope);
+      deleted += before;
+    }
+  }
+
+  return { scopes: diskScopes.size, upserted, deleted };
+}
+
+/**
+ * Sync one scope. Reads disk, compares against index, applies upsert /
+ * delete. Returns counts.
+ *
+ * @param {string} memoryRoot
+ * @param {import('./index-db.js').SegmentIndex} index
+ * @param {string} scope
+ * @returns {{ upserted: number, deleted: number }}
+ */
+export function syncScope(memoryRoot, index, scope) {
+  const onDisk = readScope(memoryRoot, scope);
+  const onDiskIds = new Set(onDisk.map(s => s.id));
+  const inIndex = index.listByScope(scope);
+  const inIndexIds = new Set(inIndex.map(s => s.id));
+
+  let upserted = 0;
+  let deleted = 0;
+
+  for (const seg of onDisk) {
+    const existing = inIndex.find(e => e.id === seg.id);
+    if (!existing
+        || existing.body !== seg.body
+        || existing.kind !== seg.kind
+        || existing.updatedAt !== seg.updatedAt
+        || !sameArr(existing.tags, seg.tags)
+        || !sameArr(existing.sourceMessages, seg.sourceMessages)) {
+      index.upsert(seg);
+      upserted += 1;
+    }
+  }
+
+  const toDelete = [];
+  for (const id of inIndexIds) {
+    if (!onDiskIds.has(id)) toDelete.push(id);
+  }
+  if (toDelete.length > 0) {
+    index.deleteMany(toDelete);
+    deleted = toDelete.length;
+  }
+
+  return { upserted, deleted };
+}
+
+function allScopesFromIndex(index) {
+  // Cheap unique-scope query via the underlying db handle.
+  const rows = index._db
+    .prepare('SELECT DISTINCT scope FROM memory_segments')
+    .all();
+  return rows.map(r => r.scope);
+}
+
+function sameArr(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}

package/unify/memory/segment.js

@@ -0,0 +1,268 @@
+/**
+ * memory/segment.js — DESIGN-H2-AMS §1.
+ *
+ * A Memory Segment is Dream LLM's secondary processing of raw messages:
+ * a self-contained semantic chunk (one segment per topic). NOT a copy
+ * of messages — messages already live in conversation/messages/.
+ *
+ * Physical layout: each scope's `memory.md` is multiple segments
+ * concatenated, each with a YAML frontmatter block and a body.
+ *
+ *   ---
+ *   id: seg_<8hex>
+ *   scope: feature/auth
+ *   kind: decision        # fact|preference|decision|lesson|relation|goal|context
+ *   tags: [auth, jwt]
+ *   sourceMessages: [m_142, m_143]
+ *   createdAt: 2026-04-29T10:11:12Z
+ *   updatedAt: 2026-04-29T10:11:12Z
+ *   ---
+ *   <body — natural language, multi-sentence, detail preserved>
+ *
+ * Robustness rules:
+ *   - Frontmatter is OPTIONAL. Body-only blocks (no `---`) are treated
+ *     as one anonymous segment; missing fields are filled with defaults.
+ *   - Partial frontmatter is OK: only `id` is auto-computed when
+ *     absent; `kind` defaults to "context"; tags/sourceMessages default
+ *     to []; timestamps default to now.
+ *   - `scope` may be absent in frontmatter — the parser falls back to
+ *     the caller-supplied `defaultScope` (typically derived from the
+ *     memory.md file path).
+ *
+ * Round-trip: serializeSegments → parseSegments yields equivalent
+ * segments (modulo whitespace).
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * @typedef {object} Segment
+ * @property {string}   id              seg_<8hex>
+ * @property {string}   scope
+ * @property {string}   kind
+ * @property {string[]} tags
+ * @property {string[]} sourceMessages
+ * @property {string}   createdAt
+ * @property {string}   updatedAt
+ * @property {string}   body
+ */
+
+export const KIND_VALUES = new Set([
+  'fact', 'preference', 'decision', 'lesson', 'relation', 'goal', 'context',
+]);
+
+const SCOPE_RE = /^(user|vp\/[\w-]+|group\/[\w-]+|feature\/[\w-]+|topic\/[\w-]+(?:\/[\w-]+)?)$/;
+
+/**
+ * Compute a stable id from segment content. Same body + scope + kind →
+ * same id, even across rewrites of unchanged content.
+ *
+ * @param {{ scope: string, kind: string, body: string }} parts
+ * @returns {string}
+ */
+export function computeSegmentId({ scope, kind, body }) {
+  const h = createHash('sha256')
+    .update(`${scope}\0${kind}\0${body.trim()}`)
+    .digest('hex')
+    .slice(0, 8);
+  return `seg_${h}`;
+}
+
+/**
+ * Validate + normalize raw segment data. Throws only on truly missing
+ * essentials (scope + body). Everything else gets a default.
+ *
+ * @param {Partial<Segment>} raw
+ * @returns {Segment}
+ */
+export function makeSegment(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('makeSegment: object required');
+  }
+  const scope = String(raw.scope || '').trim();
+  if (!SCOPE_RE.test(scope)) {
+    throw new Error(`makeSegment: invalid or missing scope "${scope}"`);
+  }
+  const body = String(raw.body || '').trim();
+  if (!body) throw new Error('makeSegment: body required');
+
+  let kind = String(raw.kind || 'context').trim();
+  if (!KIND_VALUES.has(kind)) kind = 'context';
+
+  const tags = Array.isArray(raw.tags)
+    ? raw.tags.map(t => String(t).trim()).filter(Boolean)
+    : [];
+  const sourceMessages = Array.isArray(raw.sourceMessages)
+    ? raw.sourceMessages.map(t => String(t).trim()).filter(Boolean)
+    : [];
+
+  const now = new Date().toISOString();
+  const createdAt = raw.createdAt || now;
+  const updatedAt = raw.updatedAt || createdAt;
+  const id = raw.id || computeSegmentId({ scope, kind, body });
+
+  return { id, scope, kind, tags, sourceMessages, createdAt, updatedAt, body };
+}
+
+/**
+ * Parse a memory.md text into segments. Tolerant by design:
+ *   - Empty / whitespace input → [].
+ *   - Body-only (no frontmatter) → one anonymous segment using
+ *     `defaultScope`.
+ *   - Multi-block input → split on `---` boundaries; each block may
+ *     have full, partial, or no frontmatter.
+ *
+ * Blocks that would fail validation (e.g. no scope and no defaultScope)
+ * are silently dropped — the writer can always re-emit canonical form.
+ *
+ * @param {string} text
+ * @param {{ defaultScope?: string }} [opts]
+ * @returns {Segment[]}
+ */
+export function parseSegments(text, opts = {}) {
+  if (!text || typeof text !== 'string') return [];
+  const trimmed = text.replace(/^/, '').trim();
+  if (!trimmed) return [];
+  const defaultScope = opts.defaultScope || '';
+
+  // Case 1: no `---` at all → single anonymous block.
+  if (!/^---\s*$/m.test(trimmed)) {
+    return tryMake({ body: trimmed }, defaultScope);
+  }
+
+  // Case 2: split into blocks. A block starts at a line that is exactly
+  // `---`, optionally preceded by blank line(s). We walk line-by-line.
+  const lines = trimmed.split('\n');
+  const blocks = [];
+  let i = 0;
+  // Skip leading blanks
+  while (i < lines.length && !lines[i].trim()) i += 1;
+  // If the first non-blank line is not `---`, treat the prefix up to
+  // the first `---` as a body-only segment.
+  if (lines[i] !== undefined && lines[i].trim() !== '---') {
+    const start = i;
+    while (i < lines.length && lines[i].trim() !== '---') i += 1;
+    const prefix = lines.slice(start, i).join('\n').trim();
+    if (prefix) blocks.push({ frontmatter: '', body: prefix });
+  }
+  // Now i points at `---` or end. Each iteration: `---` ... `---` ... body
+  while (i < lines.length) {
+    if (lines[i].trim() !== '---') { i += 1; continue; }
+    // Found opening `---`. Find closing `---`.
+    const fmStart = i + 1;
+    let j = fmStart;
+    while (j < lines.length && lines[j].trim() !== '---') j += 1;
+    if (j >= lines.length) {
+      // Unterminated frontmatter — treat the rest as body.
+      const body = lines.slice(fmStart).join('\n').trim();
+      if (body) blocks.push({ frontmatter: '', body });
+      break;
+    }
+    const fm = lines.slice(fmStart, j).join('\n');
+    // Body runs from j+1 until the next `---` line (or end).
+    let k = j + 1;
+    while (k < lines.length && lines[k].trim() !== '---') k += 1;
+    const body = lines.slice(j + 1, k).join('\n').trim();
+    blocks.push({ frontmatter: fm, body });
+    i = k;
+  }
+
+  const out = [];
+  for (const blk of blocks) {
+    if (!blk.body) continue;
+    const fm = blk.frontmatter ? parseFrontmatter(blk.frontmatter) : {};
+    out.push(...tryMake({ ...fm, body: blk.body }, defaultScope));
+  }
+  return out;
+}
+
+function tryMake(raw, defaultScope) {
+  const scope = raw.scope || defaultScope;
+  if (!scope) return [];
+  try {
+    return [makeSegment({ ...raw, scope })];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Serialize a list of segments back to memory.md text. Round-trips with
+ * parseSegments.
+ *
+ * @param {Segment[]} segments
+ * @returns {string}
+ */
+export function serializeSegments(segments) {
+  if (!Array.isArray(segments) || segments.length === 0) return '';
+  return segments.map(serializeOne).join('\n\n') + '\n';
+}
+
+function serializeOne(seg) {
+  const fm = [
+    `id: ${seg.id}`,
+    `scope: ${seg.scope}`,
+    `kind: ${seg.kind}`,
+    `tags: [${seg.tags.map(yamlInlineString).join(', ')}]`,
+    `sourceMessages: [${seg.sourceMessages.map(yamlInlineString).join(', ')}]`,
+    `createdAt: ${seg.createdAt}`,
+    `updatedAt: ${seg.updatedAt}`,
+  ].join('\n');
+  return `---\n${fm}\n---\n${seg.body}`;
+}
+
+function yamlInlineString(s) {
+  if (/^[\w./-]+$/.test(s)) return s;
+  return JSON.stringify(s);
+}
+
+/**
+ * Tiny YAML-frontmatter parser sized for our schema. Handles:
+ *   key: value
+ *   key: [a, b, "c d"]
+ *   key: 2026-04-29T10:11:12Z   (returned as raw string)
+ * Unknown lines are ignored.
+ *
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+function parseFrontmatter(text) {
+  const out = {};
+  for (const line of text.split('\n')) {
+    const m = /^([A-Za-z_]\w*):\s*(.*)$/.exec(line);
+    if (!m) continue;
+    out[m[1]] = parseYamlScalarOrArray(m[2].trim());
+  }
+  return out;
+}
+
+function parseYamlScalarOrArray(raw) {
+  if (!raw) return '';
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1).trim();
+    if (!inner) return [];
+    return splitTopLevelCommas(inner).map(stripYamlString);
+  }
+  return stripYamlString(raw);
+}
+
+function splitTopLevelCommas(s) {
+  const parts = [];
+  let cur = '';
+  let inStr = false;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s[i];
+    if (c === '"' && s[i - 1] !== '\\') inStr = !inStr;
+    if (c === ',' && !inStr) { parts.push(cur.trim()); cur = ''; }
+    else cur += c;
+  }
+  if (cur.trim()) parts.push(cur.trim());
+  return parts;
+}
+
+function stripYamlString(s) {
+  if (s.startsWith('"') && s.endsWith('"')) {
+    try { return JSON.parse(s); } catch { return s.slice(1, -1); }
+  }
+  return s;
+}

package/unify/memory/summary-store.js

@@ -0,0 +1,63 @@
+/**
+ * memory/summary-store.js — DESIGN-H2-AMS §3.
+ *
+ * `summary.md` is a bounded, per-scope prose digest derived from all
+ * segments in that scope. Resident AMS layer = concatenation of all
+ * relevant scope summaries. Regenerated by Dream after segments change.
+ *
+ * Layout:
+ *   ~/.yeaft/memory/<scope>/summary.md
+ *
+ * Format: plain prose, optionally prefixed with a one-line metadata
+ * header `<!-- updatedAt: ISO -->`. No required schema beyond non-empty
+ * text.
+ */
+
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync, renameSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * @param {string} memoryRoot
+ * @param {string} scope
+ * @returns {string}
+ */
+export function summaryPath(memoryRoot, scope) {
+  return join(memoryRoot, scope, 'summary.md');
+}
+
+/**
+ * Read summary text for a scope (empty string if missing).
+ *
+ * @param {string} memoryRoot
+ * @param {string} scope
+ * @returns {string}
+ */
+export function readSummary(memoryRoot, scope) {
+  const p = summaryPath(memoryRoot, scope);
+  if (!existsSync(p)) return '';
+  return stripHeader(readFileSync(p, 'utf8')).trim();
+}
+
+/**
+ * Atomic write summary text. Empty string = wipe content but keep file.
+ *
+ * @param {string} memoryRoot
+ * @param {string} scope
+ * @param {string} text
+ */
+export function writeSummary(memoryRoot, scope, text) {
+  const p = summaryPath(memoryRoot, scope);
+  mkdirSync(dirname(p), { recursive: true });
+  const header = `<!-- updatedAt: ${new Date().toISOString()} -->\n`;
+  const body = (text || '').trim();
+  const final = body ? `${header}${body}\n` : header;
+  const tmp = `${p}.tmp`;
+  writeFileSync(tmp, final, 'utf8');
+  renameSync(tmp, p);
+}
+
+function stripHeader(text) {
+  return text.replace(/^<!--[^>]*-->\s*/m, '');
+}