@yeaft/webchat-agent 0.1.642 → 0.1.645

package/package.json

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

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;
+}