@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/scripts/lib/memory/admin/reembed.js

@@ -0,0 +1,285 @@
+import { openStore, closeStore, syncStore } from '../store.js';
+import { loadSchema, writeSchema, bumpVersion } from '../schema.js';
+import { entRelName } from '../cozo.js';
+import { putEntity } from '../writes.js';
+import { invalidateStore } from '../singleton.js';
+
+function assertEmbedder(embedder) {
+  if (!embedder) throw new Error('reembed requires an embedder');
+}
+
+function assertDimensions(newDimensions) {
+  if (!Number.isInteger(newDimensions) || newDimensions <= 0) {
+    throw new Error('newDimensions must be positive integer');
+  }
+}
+
+function assertDbPath(dbAbsolutePath) {
+  if (!dbAbsolutePath) throw new Error('reembed requires dbAbsolutePath');
+}
+
+function assertRawIO(rawIO) {
+  if (!rawIO) throw new Error('reembed requires rawIO for absolute path operations');
+}
+
+function validateReembedParams(opts) {
+  assertEmbedder(opts.embedder);
+  assertDimensions(opts.newDimensions);
+  assertDbPath(opts.dbAbsolutePath);
+  assertRawIO(opts.rawIO);
+}
+
+function assertVectorLength(v, expected) {
+  const len = Array.isArray(v) ? v.length : 'n/a';
+  if (!Array.isArray(v) || v.length !== expected) {
+    throw new Error(`reembed: vector length ${len} != expected ${expected}`);
+  }
+}
+
+async function harvestRows(foundryDir, schema, io, dbPath) {
+  const entityTypes = Object.keys(schema.entities);
+  const store = await openStore({
+    foundryDir, schema, io, dbAbsolutePath: dbPath,
+  });
+  const rowsByType = {};
+  try {
+    for (const type of entityTypes) {
+      const rel = entRelName(type);
+      const res = await store.db.run(
+        `?[name, value] := *${rel}{name, value}`,
+      );
+      rowsByType[type] = res.rows.map(([name, value]) => ({ name, value }));
+    }
+  } finally {
+    closeStore(store);
+  }
+  return { rowsByType, entityTypes };
+}
+
+async function embedChunk(store, chunk, vectors, dims, vocab) {
+  for (let j = 0; j < chunk.length; j++) {
+    assertVectorLength(vectors[j], dims);
+    const entry = {
+      type: chunk[j].type,
+      name: chunk[j].name,
+      value: chunk[j].value,
+    };
+    await putEntity(store, entry, vocab, {
+      embedder: async () => [vectors[j]],
+    });
+  }
+}
+
+async function processBatch(opts) {
+  const chunk = opts.rows
+    .slice(opts.start, opts.start + opts.batchSize)
+    .map((r) => ({ ...r, type: opts.type }));
+  const vectors = await opts.embedder(chunk.map((r) => r.value));
+  await embedChunk(
+    opts.store, chunk, vectors, opts.dims, opts.vocab,
+  );
+}
+
+async function embedType(store, type, rows, opts) {
+  for (let i = 0; i < rows.length; i += opts.batchSize) {
+    await processBatch({
+      store, rows, start: i,
+      batchSize: opts.batchSize, type,
+      embedder: opts.embedder,
+      dims: opts.newDimensions,
+      vocab: opts.vocab,
+    });
+  }
+}
+
+async function buildStagingDb(opts) {
+  const vocab = {
+    entities: opts.newSchema.entities,
+    edges: opts.newSchema.edges,
+  };
+  const stagingStore = await openStore({
+    foundryDir: opts.foundryDir,
+    schema: opts.newSchema,
+    io: opts.io,
+    dbAbsolutePath: opts.stagingPath,
+  });
+
+  const embedOpts = {
+    batchSize: opts.batchSize,
+    embedder: opts.embedder,
+    newDimensions: opts.newDimensions,
+    vocab,
+  };
+
+  try {
+    for (const type of opts.entityTypes) {
+      const rows = opts.rowsByType[type] ?? [];
+      await embedType(stagingStore, type, rows, embedOpts);
+    }
+  } catch (err) {
+    try { closeStore(stagingStore); } catch { /* best effort */ }
+    throw err;
+  }
+
+  closeStore(stagingStore);
+}
+
+async function swapDatabases(opts) {
+  await writeSchema(opts.foundryDir, opts.newSchema, opts.io);
+  renameDbFiles(opts.stagingPath, opts.dbAbsolutePath, opts.rawIO);
+}
+
+async function refreshStore(opts) {
+  const reopened = await openStore({
+    foundryDir: opts.foundryDir,
+    schema: opts.newSchema,
+    io: opts.io,
+    dbAbsolutePath: opts.dbAbsolutePath,
+  });
+  try {
+    await syncStore({ store: reopened, io: opts.io });
+  } finally {
+    closeStore(reopened);
+  }
+  invalidateStore(opts.worktreeRoot);
+}
+
+async function runPipeline(opts) {
+  const buildOpts = {
+    stagingPath: opts.stagingPath,
+    newSchema: opts.newSchema,
+    io: opts.io,
+    foundryDir: opts.foundryDir,
+    entityTypes: opts.entityTypes,
+    rowsByType: opts.rowsByType,
+    embedder: opts.embedder,
+    batchSize: opts.batchSize,
+    newDimensions: opts.newDimensions,
+  };
+  await buildStagingDb(buildOpts);
+
+  const swapOpts = {
+    stagingPath: opts.stagingPath,
+    dbAbsolutePath: opts.dbAbsolutePath,
+    foundryDir: opts.foundryDir,
+    newSchema: opts.newSchema,
+    io: opts.io,
+    rawIO: opts.rawIO,
+  };
+  await swapDatabases(swapOpts);
+
+  await refreshStore({
+    foundryDir: opts.foundryDir,
+    newSchema: opts.newSchema,
+    io: opts.io,
+    dbAbsolutePath: opts.dbAbsolutePath,
+    worktreeRoot: opts.worktreeRoot,
+  });
+}
+
+function withCleanup(stagingPath, rawIO, fn) {
+  return fn().catch((err) => {
+    unlinkDbFiles(stagingPath, rawIO);
+    throw err;
+  });
+}
+
+/**
+ * Atomic re-embedding via a staging DB.
+ *
+ * Builds the new state in a sibling staging DB while the original `memory.db`
+ * and on-disk schema remain untouched. After every entity is re-embedded
+ * successfully, we swap atomically: rename the staging DB over the live DB,
+ * write the new schema, and refresh NDJSON.
+ *
+ * On any failure — provider error, unexpected vector length, Cozo error —
+ * the staging DB is closed and unlinked and the original state is preserved.
+ */
+export async function reembed({
+  worktreeRoot,
+  io,
+  rawIO,
+  dbAbsolutePath,
+  newModel,
+  newDimensions,
+  embedder,
+  batchSize = 64,
+}) {
+  validateReembedParams({
+    embedder, newDimensions, dbAbsolutePath, rawIO,
+  });
+
+  const foundryDir = 'foundry';
+  const oldSchema = await loadSchema(foundryDir, io);
+  const { rowsByType, entityTypes } = await harvestRows(
+    foundryDir, oldSchema, io, dbAbsolutePath,
+  );
+
+  const stagingPath = `${dbAbsolutePath}.reembed-tmp`;
+  unlinkDbFiles(stagingPath, rawIO);
+
+  const newSchema = {
+    ...oldSchema,
+    embeddings: { model: newModel, dimensions: newDimensions },
+  };
+  bumpVersion(newSchema);
+
+  await withCleanup(stagingPath, rawIO, () => runPipeline({
+    stagingPath, newSchema, io, foundryDir,
+    entityTypes, rowsByType, embedder, batchSize,
+    newDimensions, dbAbsolutePath, rawIO, worktreeRoot,
+  }));
+
+  return {
+    model: newModel,
+    dimensions: newDimensions,
+    types: entityTypes.length,
+  };
+}
+
+/**
+ * Remove a Cozo sqlite DB file and its WAL/SHM sidecars if present.
+ * Operates on absolute filesystem paths (reembed works outside the IO
+ * shim's foundry-relative tree).
+ */
+function unlinkDbFiles(dbPath, rawIO) {
+  for (const suffix of ['', '-wal', '-shm']) {
+    const p = dbPath + suffix;
+    try {
+      if (rawIO.exists(p)) rawIO.unlink(p);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+function tryUnlinkIfExists(rawIO, path) {
+  if (rawIO.exists(path)) {
+    try { rawIO.unlink(path); } catch { /* ignore */ }
+  }
+}
+
+function tryRenameIfExists(rawIO, src, dest) {
+  if (rawIO.exists(src)) {
+    try {
+      rawIO.rename(src, dest);
+    } catch {
+      try { rawIO.unlink(src); } catch { /* ignore */ }
+    }
+  }
+}
+
+/**
+ * Atomically move a Cozo sqlite DB plus its WAL/SHM sidecars into place.
+ *
+ * Sqlite treats the main DB file as the authoritative name; WAL/SHM files
+ * are recreated on next open. We still move them when present so that a
+ * subsequent open picks up any pending state.
+ */
+function renameDbFiles(fromPath, toPath, rawIO) {
+  tryUnlinkIfExists(rawIO, toPath + '-wal');
+  tryUnlinkIfExists(rawIO, toPath + '-shm');
+  rawIO.rename(fromPath, toPath);
+  tryRenameIfExists(rawIO, fromPath + '-wal', toPath + '-wal');
+  tryRenameIfExists(rawIO, fromPath + '-shm', toPath + '-shm');
+}

package/dist/scripts/lib/memory/admin/rename-edge-type.js

@@ -0,0 +1,54 @@
+
+import { memoryPaths } from '../paths.js';
+import { loadSchema, writeSchema, bumpVersion, hashFrontmatter } from '../schema.js';
+import { invalidateStore } from '../singleton.js';
+import { parseFrontmatter } from '../frontmatter.js';
+import { renderEdgeFrontmatter, composeMarkdown } from './helpers.js';
+
+const IDENT = /^[a-z][a-z0-9_]*$/;
+
+function validateIdentifiers(from, to) {
+  if (!IDENT.test(to)) throw new Error(`invalid identifier: '${to}'`);
+  if (from === to) throw new Error(`from and to identical`);
+}
+
+function validateSchemaState(schema, from, to) {
+  if (!schema.edges[from]) throw new Error(`edge type '${from}' not declared`);
+  if (schema.edges[to] || schema.entities[to]) throw new Error(`'${to}' already exists`);
+}
+
+export async function renameEdgeType({ worktreeRoot, io, from, to }) {
+  validateIdentifiers(from, to);
+
+  const foundryDir = 'foundry';
+  const p = memoryPaths(foundryDir);
+  const schema = await loadSchema(foundryDir, io);
+  validateSchemaState(schema, from, to);
+
+  const oldFile = p.edgeTypeFile(from);
+  const text = await io.readFile(oldFile);
+  const parsed = parseFrontmatter(text, { filename: oldFile });
+  if (!parsed.hasFrontmatter) throw new Error(`edge type file lacks frontmatter`);
+  const fm = parsed.frontmatter;
+  fm.type = to;
+  const body = parsed.body;
+  await io.writeFile(p.edgeTypeFile(to), composeMarkdown(renderEdgeFrontmatter(fm), body));
+  await io.unlink(oldFile);
+
+  const oldRel = p.relationFile(from);
+  if (await io.exists(oldRel)) {
+    const rel = await io.readFile(oldRel);
+    await io.writeFile(p.relationFile(to), rel);
+    await io.unlink(oldRel);
+  } else {
+    await io.writeFile(p.relationFile(to), '');
+  }
+
+  schema.edges[to] = { frontmatterHash: hashFrontmatter({ type: to, sources: fm.sources, targets: fm.targets }) };
+  delete schema.edges[from];
+  bumpVersion(schema);
+  await writeSchema(foundryDir, schema, io);
+
+  invalidateStore(worktreeRoot);
+  return { from, to };
+}

package/dist/scripts/lib/memory/admin/rename-entity-type.js

@@ -0,0 +1,151 @@
+
+import { memoryPaths } from '../paths.js';
+import { loadSchema, writeSchema, bumpVersion, hashFrontmatter } from '../schema.js';
+import { parseEdgeRows, serialiseEdgeRows, parseEntityRows, serialiseEntityRows } from '../ndjson.js';
+import { invalidateStore } from '../singleton.js';
+import { parseFrontmatter } from '../frontmatter.js';
+import { renderEdgeFrontmatter, composeMarkdown } from './helpers.js';
+
+const IDENT = /^[a-z][a-z0-9_]*$/;
+const TYPE_LINE = /^type:\s*\S.*$/m;
+const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+function assertValidIdentifier(id) {
+  if (!IDENT.test(id)) throw new Error(`invalid identifier: '${id}'`);
+}
+
+function assertDistinct(from, to) {
+  if (from === to) throw new Error(`from and to are identical`);
+}
+
+function assertSourceExists(schema, from) {
+  if (!schema.entities[from]) throw new Error(`entity type '${from}' not declared`);
+}
+
+function assertTargetFree(schema, to) {
+  if (schema.entities[to]) throw new Error(`'${to}' already exists`);
+  if (schema.edges[to]) throw new Error(`'${to}' already exists`);
+}
+
+function validateRename(schema, from, to) {
+  assertValidIdentifier(to);
+  assertDistinct(from, to);
+  assertSourceExists(schema, from);
+  assertTargetFree(schema, to);
+}
+
+async function rewriteEntityTypeFile(from, to, p, io) {
+  const oldFile = p.entityTypeFile(from);
+  const text = await io.readFile(oldFile);
+  const newText = text.replace(FRONTMATTER_BLOCK, (_, fm) => {
+    const replaced = fm.replace(TYPE_LINE, `type: ${to}`);
+    return `---\n${replaced}\n---`;
+  });
+  await io.writeFile(p.entityTypeFile(to), newText);
+  await io.unlink(oldFile);
+}
+
+async function rewriteEntityRelationFile(from, to, p, io) {
+  const oldRel = p.relationFile(from);
+  if (await io.exists(oldRel)) {
+    const rows = parseEntityRows(await io.readFile(oldRel));
+    await io.writeFile(p.relationFile(to), serialiseEntityRows(rows));
+    await io.unlink(oldRel);
+  } else {
+    await io.writeFile(p.relationFile(to), '');
+  }
+}
+
+function mapEdgeArray(arr, from, to) {
+  return arr.map((x) => (x === from ? to : x));
+}
+
+function needsRename(fm, from) {
+  if (fm === 'any') return false;
+  return Array.isArray(fm) && fm.includes(from);
+}
+
+function applyRename(fm, from, to) {
+  let changed = false;
+  for (const key of ['sources', 'targets']) {
+    if (needsRename(fm[key], from)) {
+      fm[key] = mapEdgeArray(fm[key], from, to);
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function mapEdgeRows(rows, from, to) {
+  let rowsChanged = false;
+  const newRows = rows.map((r) => {
+    let nr = r;
+    if (r.from_type === from) { nr = { ...nr, from_type: to }; rowsChanged = true; }
+    if (r.to_type === from) { nr = { ...nr, to_type: to }; rowsChanged = true; }
+    return nr;
+  });
+  return { newRows, rowsChanged };
+}
+
+async function updateEdgeTypeRows(edgeName, from, to, ctx) {
+  const relFile = ctx.p.relationFile(edgeName);
+  if (await ctx.io.exists(relFile)) {
+    const rows = parseEdgeRows(await ctx.io.readFile(relFile));
+    const { newRows, rowsChanged } = mapEdgeRows(rows, from, to);
+    if (rowsChanged) await ctx.io.writeFile(relFile, serialiseEdgeRows(newRows));
+  }
+}
+
+async function updateEdgeTypeFrontmatter(edgeName, from, to, ctx) {
+  const edgeFile = ctx.p.edgeTypeFile(edgeName);
+  const edgeText = await ctx.io.readFile(edgeFile);
+  const parsed = parseFrontmatter(edgeText, { filename: edgeFile });
+  if (!parsed.hasFrontmatter) return null;
+
+  const changed = applyRename(parsed.frontmatter, from, to);
+  if (!changed) return null;
+
+  const body = parsed.body;
+  const hash = hashFrontmatter({
+    type: edgeName,
+    sources: parsed.frontmatter.sources,
+    targets: parsed.frontmatter.targets,
+  });
+  await ctx.io.writeFile(edgeFile, composeMarkdown(renderEdgeFrontmatter(parsed.frontmatter), body));
+  return hash;
+}
+
+async function updateAllEdgeTypes(from, to, ctx) {
+  const hashes = new Map();
+  for (const edgeName of Object.keys(ctx.schema.edges)) {
+    const hash = await updateEdgeTypeFrontmatter(edgeName, from, to, ctx);
+    if (hash !== null) hashes.set(edgeName, hash);
+    await updateEdgeTypeRows(edgeName, from, to, ctx);
+  }
+  for (const [edgeName, hash] of hashes) {
+    ctx.schema.edges[edgeName].frontmatterHash = hash;
+  }
+}
+
+async function updateSchema(schema, from, to, foundryDir, io) {
+  schema.entities[to] = { frontmatterHash: hashFrontmatter({ type: to }) };
+  delete schema.entities[from];
+  bumpVersion(schema);
+  await writeSchema(foundryDir, schema, io);
+}
+
+export async function renameEntityType({ worktreeRoot, io, from, to }) {
+  const foundryDir = 'foundry';
+  const p = memoryPaths(foundryDir);
+  const schema = await loadSchema(foundryDir, io);
+
+  validateRename(schema, from, to);
+  await rewriteEntityTypeFile(from, to, p, io);
+  await rewriteEntityRelationFile(from, to, p, io);
+  const ctx = { p, io, schema };
+  await updateAllEdgeTypes(from, to, ctx);
+  await updateSchema(schema, from, to, foundryDir, io);
+
+  invalidateStore(worktreeRoot);
+  return { from, to };
+}

package/dist/scripts/lib/memory/admin/reset.js

@@ -0,0 +1,24 @@
+
+import { memoryPaths } from '../paths.js';
+import { loadSchema, writeSchema, bumpVersion } from '../schema.js';
+import { invalidateStore } from '../singleton.js';
+
+export async function resetMemory({ worktreeRoot, io, confirm }) {
+  if (confirm !== true) throw new Error(`reset requires confirm: true`);
+  const foundryDir = 'foundry';
+  const p = memoryPaths(foundryDir);
+  const schema = await loadSchema(foundryDir, io);
+
+  for (const name of [...Object.keys(schema.entities), ...Object.keys(schema.edges)]) {
+    await io.writeFile(p.relationFile(name), '');
+  }
+  // Delete the live DB so it's re-imported empty on next open.
+  for (const suffix of ['', '-wal', '-shm']) {
+    if (await io.exists(p.db + suffix)) await io.unlink(p.db + suffix);
+  }
+
+  bumpVersion(schema);
+  await writeSchema(foundryDir, schema, io);
+  invalidateStore(worktreeRoot);
+  return { reset: true };
+}

package/dist/scripts/lib/memory/admin/vacuum.js

@@ -0,0 +1,9 @@
+export async function vacuumMemory({ store }) {
+  try {
+    await store.db.run('::compact');
+  } catch (err) {
+    if (!/unknown system op/i.test(String(err))) throw err;
+    // Cozo builds without ::compact silently succeed.
+  }
+  return { ok: true };
+}

package/dist/scripts/lib/memory/admin/validate.js

@@ -0,0 +1,19 @@
+import { loadMemoryConfig } from '../config.js';
+import { loadSchema } from '../schema.js';
+import { loadVocabulary } from '../types.js';
+import { detectDrift } from '../drift.js';
+
+export async function validateMemory({ io }) {
+  const issues = [];
+  try {
+    const config = await loadMemoryConfig('foundry', io);
+    if (!config.present) issues.push({ kind: 'missing-config', message: 'foundry/memory/config.md missing' });
+    const schema = await loadSchema('foundry', io);
+    const vocab = await loadVocabulary('foundry', io);
+    const drift = detectDrift({ vocabulary: vocab, schema });
+    for (const item of drift.items) issues.push(item);
+  } catch (err) {
+    issues.push({ kind: 'load-error', message: err.message });
+  }
+  return { ok: issues.length === 0, issues };
+}

package/dist/scripts/lib/memory/config.js

@@ -0,0 +1,149 @@
+import { memoryPaths } from './paths.js';
+import { parseFrontmatter, renderMarkdown } from './frontmatter.js';
+
+export const DEFAULT_CONFIG = Object.freeze({
+  enabled: false,
+  present: false,
+  validation: 'strict',
+  embeddings: Object.freeze({
+    enabled: true,
+    baseURL: 'http://localhost:11434/v1',
+    model: 'nomic-embed-text',
+    dimensions: 768,
+    apiKey: null,
+    batchSize: 64,
+    timeoutMs: 30000,
+  }),
+});
+
+function mergeEmbeddingsKey(base, key, value) {
+  if (key in base && value !== undefined) base[key] = value;
+}
+
+function mergeEmbeddings(userE) {
+  const base = { ...DEFAULT_CONFIG.embeddings };
+  if (!userE || typeof userE !== 'object') return base;
+  for (const [key, value] of Object.entries(userE)) {
+    mergeEmbeddingsKey(base, key, value);
+  }
+  return base;
+}
+
+function assertValidationValid(value) {
+  if (!['strict', 'lax'].includes(value)) {
+    throw new Error(`memory config: validation must be 'strict' or 'lax', got ${JSON.stringify(value)}`);
+  }
+}
+
+function assertEmbeddingsEnabled(e) {
+  if (typeof e.enabled !== 'boolean') throw new Error('memory config: embeddings.enabled must be boolean');
+}
+
+function assertValidBaseUrl(e) {
+  if (!(typeof e.baseURL === 'string' && e.baseURL)) throw new Error('memory config: embeddings.baseURL required');
+}
+
+function assertValidModel(e) {
+  if (!(typeof e.model === 'string' && e.model)) throw new Error('memory config: embeddings.model required');
+}
+
+function assertValidDimensions(e) {
+  if (!(Number.isInteger(e.dimensions) && e.dimensions > 0)) throw new Error('memory config: embeddings.dimensions must be positive integer');
+}
+
+function assertValidBatchSize(e) {
+  if (!(Number.isInteger(e.batchSize) && e.batchSize > 0)) throw new Error('memory config: embeddings.batchSize must be positive integer');
+}
+
+function assertEmbeddingsFields(e) {
+  assertValidBaseUrl(e);
+  assertValidModel(e);
+  assertValidDimensions(e);
+  assertValidBatchSize(e);
+}
+
+function validate(cfg) {
+  assertValidationValid(cfg.validation);
+  assertEmbeddingsEnabled(cfg.embeddings);
+  if (cfg.embeddings.enabled) {
+    assertEmbeddingsFields(cfg.embeddings);
+  }
+}
+
+function assertEnabledValid(enabled, configPath) {
+  if (enabled !== undefined && typeof enabled !== 'boolean') {
+    throw new Error(
+      `memory config (${configPath}): enabled must be a YAML boolean (true/false), got ${JSON.stringify(enabled)}`,
+    );
+  }
+}
+
+function buildConfig(fm) {
+  const cfg = {
+    present: true,
+    enabled: fm.enabled === true,
+    validation: fm.validation ?? DEFAULT_CONFIG.validation,
+    embeddings: mergeEmbeddings(fm.embeddings),
+  };
+  if (!cfg.enabled) {
+    cfg.embeddings = { ...cfg.embeddings, enabled: false };
+  }
+  return cfg;
+}
+
+export async function loadMemoryConfig(foundryDir, io) {
+  const p = memoryPaths(foundryDir);
+  if (!(await io.exists(p.config))) {
+    return { ...DEFAULT_CONFIG, embeddings: { ...DEFAULT_CONFIG.embeddings } };
+  }
+  const text = await io.readFile(p.config);
+  const { frontmatter: fm } = parseFrontmatter(text, { filename: p.config });
+  assertEnabledValid(fm.enabled, p.config);
+  const cfg = buildConfig(fm);
+  validate(cfg);
+  return cfg;
+}
+
+async function loadExistingFrontmatter(p, io) {
+  if (!(await io.exists(p.config))) {
+    return { frontmatter: {}, body: '' };
+  }
+  const text = await io.readFile(p.config);
+  const parsed = parseFrontmatter(text, { filename: p.config });
+  if (parsed.hasFrontmatter) {
+    return { frontmatter: parsed.frontmatter, body: parsed.body };
+  }
+  return { frontmatter: {}, body: text };
+}
+
+function mergeEmbeddingsUpdate(existingFm, updates) {
+  const baseE = typeof existingFm.embeddings === 'object' && existingFm.embeddings
+    ? existingFm.embeddings
+    : {};
+  return { ...baseE, ...updates.embeddings };
+}
+
+function mergeFrontmatterUpdates(existingFm, updates) {
+  const nextFm = { ...existingFm };
+  if ('enabled' in updates) nextFm.enabled = updates.enabled;
+  if ('validation' in updates) nextFm.validation = updates.validation;
+  if (updates.embeddings && typeof updates.embeddings === 'object') {
+    nextFm.embeddings = mergeEmbeddingsUpdate(existingFm, updates);
+  }
+  return nextFm;
+}
+
+/**
+ * Rewrite foundry/memory/config.md with updated embeddings settings.
+ * Preserves any existing markdown body after the frontmatter. If config.md
+ * is missing, creates a minimal one with no body.
+ *
+ * `updates.embeddings` is merged into existing embeddings frontmatter; other
+ * top-level keys in `updates` (enabled, validation) overwrite if provided.
+ */
+export async function writeMemoryConfig(foundryDir, updates, io) {
+  const p = memoryPaths(foundryDir);
+  const { frontmatter: existingFm, body } = await loadExistingFrontmatter(p, io);
+  const nextFm = mergeFrontmatterUpdates(existingFm, updates);
+  await io.writeFile(p.config, renderMarkdown(nextFm, body));
+}