march-cli 0.1.0

package/src/memory/graph/graph-primitives.mjs

@@ -0,0 +1,103 @@
+import { ROOT_NODE_UUID } from "../database.mjs";
+
+export function ensureNode(db, nodeUuid) {
+  const existing = db.prepare("SELECT uuid FROM nodes WHERE uuid = ?").get(nodeUuid);
+  if (!existing) {
+    db.prepare("INSERT INTO nodes (uuid) VALUES (?)").run(nodeUuid);
+  }
+  return nodeUuid;
+}
+
+export function insertMemory(db, nodeUuid, content, deprecated = false) {
+  const result = db.prepare(
+    "INSERT INTO memories (node_uuid, content, deprecated) VALUES (?, ?, ?)"
+  ).run(nodeUuid, content, deprecated ? 1 : 0);
+  return { id: Number(result.lastInsertRowid), node_uuid: nodeUuid, content, deprecated: deprecated ? 1 : 0 };
+}
+
+export function getOrCreateEdge(db, parentUuid, childUuid, name, priority = 0, disclosure = null) {
+  const existing = db.prepare(
+    "SELECT id, parent_uuid, child_uuid, name, priority, disclosure FROM edges WHERE parent_uuid = ? AND child_uuid = ?"
+  ).get(parentUuid, childUuid);
+
+  if (existing) return { edge: existing, created: false };
+
+  const result = db.prepare(
+    "INSERT INTO edges (parent_uuid, child_uuid, name, priority, disclosure) VALUES (?, ?, ?, ?, ?)"
+  ).run(parentUuid, childUuid, name, priority, disclosure);
+  const edge = {
+    id: Number(result.lastInsertRowid), parent_uuid: parentUuid, child_uuid: childUuid,
+    name, priority, disclosure,
+  };
+  return { edge, created: true };
+}
+
+export function insertPath(db, namespace, domain, path, edgeId, nodeUuid) {
+  db.prepare(
+    "INSERT OR IGNORE INTO paths (namespace, domain, path, edge_id, node_uuid) VALUES (?, ?, ?, ?, ?)"
+  ).run(namespace, domain, path, edgeId, nodeUuid);
+}
+
+export function resolveGraphPath(db, path, domain = "core", namespace = "") {
+  if (path === "") {
+    return { node_uuid: ROOT_NODE_UUID, edge: null, path_obj: null };
+  }
+  const row = db.prepare(`
+    SELECT p.namespace, p.domain, p.path, p.edge_id, p.node_uuid,
+           e.parent_uuid, e.child_uuid, e.name, e.priority, e.disclosure
+    FROM paths p
+    JOIN edges e ON p.edge_id = e.id
+    WHERE p.namespace = ? AND p.domain = ? AND p.path = ?
+  `).get(namespace, domain, path);
+
+  if (!row) return null;
+  return {
+    path_obj: { namespace: row.namespace, domain: row.domain, path: row.path, edge_id: row.edge_id, node_uuid: row.node_uuid },
+    edge: { id: row.edge_id, parent_uuid: row.parent_uuid, child_uuid: row.child_uuid, name: row.name, priority: row.priority, disclosure: row.disclosure },
+    node_uuid: row.node_uuid,
+  };
+}
+
+export function countPathsForEdge(db, edgeId) {
+  const row = db.prepare("SELECT COUNT(*) AS cnt FROM paths WHERE edge_id = ?").get(edgeId);
+  return row.cnt;
+}
+
+export function countMemoriesForNode(db, nodeUuid) {
+  const row = db.prepare("SELECT COUNT(*) AS cnt FROM memories WHERE node_uuid = ?").get(nodeUuid);
+  return row.cnt;
+}
+
+export function getNextChildNumber(db, parentUuid, namespace) {
+  const rows = db.prepare(`
+    SELECT e.name FROM edges e
+    JOIN paths p ON p.edge_id = e.id
+    WHERE e.parent_uuid = ? AND p.namespace = ?
+  `).all(parentUuid, namespace);
+  let maxNum = 0;
+  for (const row of rows) {
+    const num = parseInt(row.name, 10);
+    if (!Number.isNaN(num) && num > maxNum) maxNum = num;
+  }
+  return maxNum + 1;
+}
+
+export function wouldCreateCycle(db, parentUuid, childUuid) {
+  if (parentUuid === ROOT_NODE_UUID) return false;
+  if (parentUuid === childUuid) return true;
+
+  const visited = new Set([childUuid]);
+  const queue = [childUuid];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const rows = db.prepare("SELECT child_uuid FROM edges WHERE parent_uuid = ?").all(current);
+    for (const row of rows) {
+      if (row.child_uuid === parentUuid) return true;
+      if (!visited.has(row.child_uuid)) {
+        visited.add(row.child_uuid);
+        queue.push(row.child_uuid);
+      }
+    }
+  }
+  return false;
+}

package/src/memory/graph/graph-read.mjs

@@ -0,0 +1,159 @@
+import { ROOT_NODE_UUID } from "../database.mjs";
+
+export function getMemoryByPath(db, path, domain = "core", namespace = "") {
+  if (path === "") {
+    return {
+      id: 0, node_uuid: ROOT_NODE_UUID,
+      content: `Root node for domain '${domain}'.`,
+      priority: 0, disclosure: null, deprecated: false,
+      created_at: null, domain, path: "", alias_count: 0,
+    };
+  }
+
+  const row = db.prepare(`
+    SELECT m.id, m.node_uuid, m.content, m.deprecated, m.created_at,
+           e.priority, e.disclosure, p.domain, p.path
+    FROM paths p
+    JOIN edges e ON p.edge_id = e.id
+    JOIN memories m ON m.node_uuid = e.child_uuid AND m.deprecated = 0
+    WHERE p.namespace = ? AND p.domain = ? AND p.path = ?
+    ORDER BY m.created_at DESC
+    LIMIT 1
+  `).get(namespace, domain, path);
+
+  if (!row) return null;
+
+  const totalPaths = countIncomingPaths(db, row.node_uuid, namespace);
+  const aliasCount = Math.max(0, totalPaths - 1);
+
+  return {
+    id: row.id, node_uuid: row.node_uuid, content: row.content,
+    priority: row.priority, disclosure: row.disclosure,
+    deprecated: !!row.deprecated, created_at: row.created_at,
+    domain: row.domain, path: row.path, alias_count: aliasCount,
+  };
+}
+
+export function getChildren(db, nodeUuid = ROOT_NODE_UUID, contextDomain = null, contextPath = null, namespace = "") {
+  const rows = db.prepare(`
+    SELECT DISTINCT e.id AS edge_id, e.child_uuid, e.name, e.priority, e.disclosure,
+           m.content, m.id AS memory_id
+    FROM edges e
+    JOIN paths p ON p.edge_id = e.id
+    JOIN memories m ON m.node_uuid = e.child_uuid AND m.deprecated = 0
+    WHERE e.parent_uuid = ? AND p.namespace = ?
+    ORDER BY e.priority ASC, e.name
+  `).all(nodeUuid, namespace);
+
+  const childUuids = [...new Set(rows.map(r => r.child_uuid))];
+  const edgeIds = [...new Set(rows.map(r => r.edge_id))];
+
+  const approxChildrenMap = {};
+  if (childUuids.length > 0) {
+    const placeholders = childUuids.map(() => "?").join(",");
+    const counts = db.prepare(`
+      SELECT e.parent_uuid, COUNT(DISTINCT e.id)
+      FROM edges e
+      JOIN paths p ON p.edge_id = e.id
+      WHERE e.parent_uuid IN (${placeholders}) AND p.namespace = ?
+      GROUP BY e.parent_uuid
+    `).all(...childUuids, namespace);
+    for (const c of counts) {
+      approxChildrenMap[c[0]] = c[1];
+    }
+  }
+
+  const pathsByEdgeId = {};
+  if (edgeIds.length > 0) {
+    const placeholders = edgeIds.map(() => "?").join(",");
+    const pathRows = db.prepare(`
+      SELECT * FROM paths WHERE namespace = ? AND edge_id IN (${placeholders})
+    `).all(namespace, ...edgeIds);
+    for (const p of pathRows) {
+      if (!pathsByEdgeId[p.edge_id]) pathsByEdgeId[p.edge_id] = [];
+      pathsByEdgeId[p.edge_id].push(p);
+    }
+  }
+
+  const prefix = contextPath ? `${contextPath}/` : null;
+  const seen = new Set();
+  const children = [];
+
+  for (const row of rows) {
+    if (seen.has(row.child_uuid)) continue;
+    seen.add(row.child_uuid);
+
+    const allPaths = pathsByEdgeId[row.edge_id] ?? [];
+    if (nodeUuid === ROOT_NODE_UUID && contextDomain) {
+      if (!allPaths.some(p => p.domain === contextDomain)) continue;
+    }
+
+    const pathObj = pickBestPath(allPaths, contextDomain, prefix);
+    if (!pathObj) continue;
+
+    children.push({
+      node_uuid: row.child_uuid,
+      edge_id: row.edge_id,
+      name: row.name,
+      domain: pathObj.domain,
+      path: pathObj.path,
+      content_snippet: (row.content ?? "").slice(0, 100) + ((row.content ?? "").length > 100 ? "..." : ""),
+      priority: row.priority,
+      disclosure: row.disclosure,
+      approx_children_count: approxChildrenMap[row.child_uuid] ?? 0,
+    });
+  }
+
+  return children;
+}
+
+export function getRecentMemories(db, limit = 10, namespace = "") {
+  const rows = db.prepare(`
+    SELECT m.id AS memory_id, m.created_at, e.priority, e.disclosure, p.domain, p.path
+    FROM paths p
+    JOIN edges e ON p.edge_id = e.id
+    JOIN memories m ON m.node_uuid = e.child_uuid AND m.deprecated = 0
+    WHERE p.namespace = ?
+    ORDER BY m.created_at DESC
+  `).all(namespace);
+
+  const seen = new Set();
+  const memories = [];
+  for (const row of rows) {
+    if (seen.has(row.memory_id)) continue;
+    seen.add(row.memory_id);
+    memories.push({
+      memory_id: row.memory_id,
+      uri: `${row.domain}://${row.path}`,
+      priority: row.priority,
+      disclosure: row.disclosure,
+      created_at: row.created_at,
+    });
+    if (memories.length >= limit) break;
+  }
+  return memories;
+}
+
+function countIncomingPaths(db, nodeUuid, namespace = "") {
+  const row = db.prepare(
+    "SELECT COUNT(*) AS cnt FROM paths WHERE node_uuid = ? AND namespace = ?"
+  ).get(nodeUuid, namespace);
+  return row.cnt;
+}
+
+function pickBestPath(paths, contextDomain, prefix) {
+  if (paths.length === 0) return null;
+  if (paths.length === 1) return paths[0];
+
+  if (contextDomain && prefix) {
+    for (const p of paths) {
+      if (p.domain === contextDomain && p.path.startsWith(prefix)) return p;
+    }
+  }
+  if (contextDomain) {
+    for (const p of paths) {
+      if (p.domain === contextDomain) return p;
+    }
+  }
+  return paths[0];
+}

package/src/memory/graph.mjs

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { ROOT_NODE_UUID } from "./database.mjs";
+import {
+  getChildren,
+  getMemoryByPath,
+  getRecentMemories,
+} from "./graph/graph-read.mjs";
+import { getGraphDiagnostics } from "./graph/graph-diagnostics.mjs";
+import {
+  cascadeCreatePaths,
+  cascadeDeleteNode,
+  deprecateNodeMemories,
+} from "./graph/graph-cascades.mjs";
+import { removeGraphPath } from "./graph/graph-path-removal.mjs";
+import {
+  graphUri,
+  leafName,
+  pathExists,
+} from "./graph/graph-path-utils.mjs";
+import {
+  ensureNode,
+  getNextChildNumber,
+  getOrCreateEdge,
+  insertMemory,
+  insertPath,
+  resolveGraphPath,
+  wouldCreateCycle,
+} from "./graph/graph-primitives.mjs";
+
+export class GraphService {
+  constructor(db, { changesetStore = null, searchIndexer = null, namespace = "" } = {}) {
+    this.db = db;
+    this.changesetStore = changesetStore;
+    this.searchIndexer = searchIndexer;
+    this.namespace = namespace;
+  }
+
+  /**
+   * Resolve namespace: explicit arg takes precedence, then instance default.
+   */
+  #ns(explicit = undefined) {
+    return explicit !== undefined ? explicit : this.namespace;
+  }
+
+  // ═══════════════════════════════════════════════════════════════════
+  // Read Operations
+  // ═══════════════════════════════════════════════════════════════════
+
+  getMemoryByPath(path, domain = "core", namespace = "") {
+    return getMemoryByPath(this.db, path, domain, namespace);
+  }
+
+  getChildren(nodeUuid = ROOT_NODE_UUID, contextDomain = null, contextPath = null, namespace = "") {
+    return getChildren(this.db, nodeUuid, contextDomain, contextPath, this.#ns(namespace));
+  }
+
+  getRecentMemories(limit = 10, namespace = "") {
+    return getRecentMemories(this.db, limit, namespace);
+  }
+
+  resolvePath(path, domain = "core", namespace = "") {
+    return resolveGraphPath(this.db, path, domain, namespace);
+  }
+
+  getPathsForNode(nodeUuid, namespace = "") {
+    return this.db.prepare(
+      "SELECT * FROM paths WHERE node_uuid = ? AND namespace = ?"
+    ).all(nodeUuid, namespace);
+  }
+
+  getCurrentMemory(nodeUuid) {
+    return this.db.prepare(
+      "SELECT * FROM memories WHERE node_uuid = ? AND deprecated = 0 ORDER BY id DESC LIMIT 1"
+    ).get(nodeUuid);
+  }
+
+  touchNode(nodeUuid) {
+    this.db.prepare(
+      "UPDATE nodes SET last_accessed_at = datetime('now') WHERE uuid = ?"
+    ).run(nodeUuid);
+  }
+
+  getDiagnostics(namespace = "", daysStale = 30, maxChildren = 10) {
+    return getGraphDiagnostics(this.db, namespace, daysStale, maxChildren);
+  }
+
+  cascadeDeleteNode(nodeUuid) {
+    return cascadeDeleteNode(this.db, nodeUuid);
+  }
+
+  #createEdgeWithPaths(parentUuid, childUuid, name, domain, path, priority = 0, disclosure = null, namespace = "") {
+    const { edge, created } = getOrCreateEdge(this.db, parentUuid, childUuid, name, priority, disclosure);
+    insertPath(this.db, namespace, domain, path, edge.id, childUuid);
+    cascadeCreatePaths(this.db, childUuid, domain, path, namespace);
+    return { edge, edge_id: edge.id, edge_created: created };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════
+  // Public Write API
+  // ═══════════════════════════════════════════════════════════════════
+
+  createMemory(parentPath, content, priority, { title = null, disclosure = null, domain = "core", namespace = "" } = {}) {
+    const parentUuid = parentPath === ""
+      ? ROOT_NODE_UUID
+      : resolveGraphPath(this.db, parentPath, domain, namespace)?.node_uuid;
+
+    if (!parentUuid && parentPath !== "") {
+      throw new Error(`Parent '${domain}://${parentPath}' does not exist.`);
+    }
+
+    const finalPath = title
+      ? (parentPath ? `${parentPath}/${title}` : title)
+      : `${parentPath ? parentPath + "/" : ""}${getNextChildNumber(this.db, parentUuid, this.#ns(namespace))}`;
+
+    if (pathExists(this.db, namespace, domain, finalPath)) throw new Error(`Path '${graphUri(domain, finalPath)}' already exists`);
+
+    const newUuid = randomUUID();
+    ensureNode(this.db, newUuid);
+    const memory = insertMemory(this.db, newUuid, content);
+    const edgeName = title ?? leafName(finalPath);
+
+    const created = this.#createEdgeWithPaths(parentUuid, newUuid, edgeName, domain, finalPath, priority, disclosure, namespace);
+
+    if (this.changesetStore) {
+      this.changesetStore.record({ memoryId: memory.id, nodeUuid: newUuid, beforeContent: null, afterContent: content });
+    }
+    if (this.searchIndexer) {
+      this.searchIndexer.index(newUuid, content, namespace);
+    }
+
+    return {
+      id: memory.id, node_uuid: newUuid, domain, path: finalPath,
+      uri: graphUri(domain, finalPath), priority,
+    };
+  }
+
+  updateMemory(path, { content = null, priority = null, disclosure = null, domain = "core", namespace = "" } = {}) {
+    if (path === "") throw new Error("Cannot update the root node.");
+    if (content === null && priority === null && disclosure === null) {
+      throw new Error("At least one of content, priority, or disclosure must be set.");
+    }
+
+    const resolved = resolveGraphPath(this.db, path, domain, namespace);
+    if (!resolved || !resolved.edge) {
+      throw new Error(`Path '${graphUri(domain, path)}' not found`);
+    }
+
+    const { edge, node_uuid: nodeUuid } = resolved;
+    let oldMemoryId = null;
+    let newMemoryId = null;
+
+    // Get current memory
+    const currentMem = this.db.prepare(
+      "SELECT id FROM memories WHERE node_uuid = ? AND deprecated = 0 ORDER BY created_at DESC LIMIT 1"
+    ).get(nodeUuid);
+    oldMemoryId = currentMem?.id ?? null;
+
+    // Update edge metadata
+    if (priority !== null) {
+      this.db.prepare("UPDATE edges SET priority = ? WHERE id = ?").run(priority, edge.id);
+    }
+    if (disclosure !== null) {
+      this.db.prepare("UPDATE edges SET disclosure = ? WHERE id = ?").run(disclosure, edge.id);
+    }
+
+    // Content change → new memory version
+    if (content !== null) {
+      const newMem = insertMemory(this.db, nodeUuid, content, false);
+      newMemoryId = newMem.id;
+      deprecateNodeMemories(this.db, nodeUuid, newMemoryId);
+      this.db.prepare(
+        "UPDATE memories SET deprecated = 0, migrated_to = NULL WHERE id = ?"
+      ).run(newMemoryId);
+
+      // Record changeset + re-index
+      if (this.changesetStore) {
+        const oldContent = oldMemoryId
+          ? this.db.prepare("SELECT content FROM memories WHERE id = ?").get(oldMemoryId)?.content ?? null
+          : null;
+        this.changesetStore.record({ memoryId: newMemoryId, nodeUuid, beforeContent: oldContent, afterContent: content });
+      }
+      if (this.searchIndexer) {
+        this.searchIndexer.index(nodeUuid, content, namespace);
+      }
+    }
+
+    return {
+      domain, path, uri: graphUri(domain, path),
+      old_memory_id: oldMemoryId, new_memory_id: newMemoryId ?? oldMemoryId, node_uuid: nodeUuid,
+    };
+  }
+
+  rollbackToMemory(targetMemoryId) {
+    const target = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(targetMemoryId);
+    if (!target) throw new Error(`Memory ID ${targetMemoryId} not found`);
+
+    if (!target.deprecated) {
+      return { restored_memory_id: targetMemoryId, was_already_active: true };
+    }
+
+    deprecateNodeMemories(this.db, target.node_uuid, targetMemoryId);
+    this.db.prepare(
+      "UPDATE memories SET deprecated = 0, migrated_to = NULL WHERE id = ?"
+    ).run(targetMemoryId);
+
+    return { restored_memory_id: targetMemoryId, node_uuid: target.node_uuid };
+  }
+
+  addPath(newPath, targetPath, { newDomain = "core", targetDomain = "core", priority = 0, disclosure = null, namespace = "" } = {}) {
+    if (newPath === "") throw new Error("Cannot create alias at root path.");
+
+    const target = resolveGraphPath(this.db, targetPath, targetDomain, namespace);
+    if (!target) throw new Error(`Target '${graphUri(targetDomain, targetPath)}' not found`);
+
+    const parentUuid = newPath.includes("/")
+      ? resolveGraphPath(this.db, newPath.substring(0, newPath.lastIndexOf("/")), newDomain, namespace)?.node_uuid ?? ROOT_NODE_UUID
+      : ROOT_NODE_UUID;
+
+    if (pathExists(this.db, namespace, newDomain, newPath)) throw new Error(`Path '${graphUri(newDomain, newPath)}' already exists`);
+
+    if (wouldCreateCycle(this.db, parentUuid, target.node_uuid)) {
+      throw new Error(`Cannot create alias: would create a cycle.`);
+    }
+
+    const result = this.#createEdgeWithPaths(
+      parentUuid, target.node_uuid,
+      leafName(newPath), newDomain, newPath,
+      priority, disclosure ?? target.edge?.disclosure, namespace,
+    );
+
+    return {
+      new_uri: graphUri(newDomain, newPath),
+      target_uri: graphUri(targetDomain, targetPath),
+      node_uuid: target.node_uuid,
+      edge_id: result.edge_id, edge_created: result.edge_created,
+    };
+  }
+
+  removePath(path, domain = "core", namespace = "") {
+    return removeGraphPath(this.db, path, domain, namespace);
+  }
+
+  restorePath(path, domain, nodeUuid, { parentUuid = null, priority = 0, disclosure = null, namespace = "" } = {}) {
+    if (path === "") throw new Error("Cannot restore root path.");
+
+    // Check node exists and has an active memory
+    const node = this.db.prepare("SELECT uuid FROM nodes WHERE uuid = ?").get(nodeUuid);
+    if (!node) throw new Error(`Node '${nodeUuid}' not found`);
+
+    const activeMem = this.db.prepare(
+      "SELECT id FROM memories WHERE node_uuid = ? AND deprecated = 0"
+    ).get(nodeUuid);
+    if (!activeMem) {
+      const latest = this.db.prepare(
+        "SELECT id FROM memories WHERE node_uuid = ? ORDER BY created_at DESC LIMIT 1"
+      ).get(nodeUuid);
+      if (!latest) throw new Error(`Node '${nodeUuid}' has no memory versions`);
+      this.db.prepare(
+        "UPDATE memories SET deprecated = 0, migrated_to = NULL WHERE id = ?"
+      ).run(latest.id);
+    }
+
+    if (pathExists(this.db, namespace, domain, path)) throw new Error(`Path '${graphUri(domain, path)}' already exists`);
+
+    if (!parentUuid) {
+      if (path.includes("/")) {
+        const parentPath = path.substring(0, path.lastIndexOf("/"));
+        const parent = resolveGraphPath(this.db, parentPath, domain, namespace);
+        parentUuid = parent?.node_uuid ?? ROOT_NODE_UUID;
+      } else {
+        parentUuid = ROOT_NODE_UUID;
+      }
+    }
+
+    const edgeName = leafName(path);
+    const { edge } = getOrCreateEdge(this.db, parentUuid, nodeUuid, edgeName, priority, disclosure);
+    insertPath(this.db, namespace, domain, path, edge.id, nodeUuid);
+
+    return { uri: graphUri(domain, path), node_uuid: nodeUuid };
+  }
+}
+

package/src/memory/markdown/markdown-delete.mjs

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { formatMemoryMarkdown, normalizeTags, parseMemoryMarkdown } from "./markdown-format.mjs";
+
+export function softDeleteMemoryFile({ path, entry = null, now = () => new Date() } = {}) {
+  if (!existsSync(path)) throw new Error(`memory not found: ${path}`);
+  const parsed = parseMemoryMarkdown(readFileSync(path, "utf8"));
+  const id = String(parsed.frontmatter.id ?? entry?.id ?? "");
+  if (!id) throw new Error(`memory file is missing id: ${path}`);
+  if (String(parsed.frontmatter.status ?? "active") === "deleted") {
+    return { id, path, status: "deleted", alreadyDeleted: true };
+  }
+  writeFileSync(path, formatMemoryMarkdown({
+    frontmatter: {
+      ...parsed.frontmatter,
+      id,
+      tags: normalizeTags(parsed.frontmatter.tags ?? entry?.tags ?? []),
+      status: "deleted",
+      updated_at: now().toISOString(),
+    },
+    body: parsed.body,
+  }), "utf8");
+  return { id, path, status: "deleted", alreadyDeleted: false };
+}

package/src/memory/markdown/markdown-format.mjs

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export function parseMemoryMarkdown(content) {
+  if (!content.startsWith("---\n")) return { frontmatter: {}, body: content, title: extractTitle(content) };
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) throw new Error("unterminated frontmatter");
+  const frontmatter = parseFrontmatter(content.slice(4, end));
+  const body = content.slice(content.indexOf("\n", end + 1) + 1);
+  return { frontmatter, body, title: extractTitle(body) };
+}
+
+export function formatMemoryMarkdown({ frontmatter, body }) {
+  const lines = ["---"];
+  for (const key of ["id", "name", "description", "status", "created_at", "updated_at"]) {
+    if (frontmatter[key] != null) lines.push(`${key}: ${formatYamlScalar(frontmatter[key])}`);
+  }
+  lines.push("tags:");
+  for (const tag of frontmatter.tags ?? []) lines.push(`  - ${formatYamlScalar(tag)}`);
+  lines.push("---", "", String(body ?? "").trimEnd(), "");
+  return lines.join("\n");
+}
+
+export function normalizeTags(tags) {
+  const raw = Array.isArray(tags) ? tags : [tags];
+  const out = [];
+  for (const tag of raw) {
+    const value = normalizeTag(tag);
+    if (value && !out.includes(value)) out.push(value);
+  }
+  return out;
+}
+
+export function expandTags(tags) {
+  const terms = [];
+  for (const tag of tags) {
+    terms.push(tag);
+    for (const part of tag.split(/[\/_-]+/)) {
+      if (part) terms.push(part);
+    }
+  }
+  return [...new Set(terms.map(normalizeText).filter(Boolean))];
+}
+
+export function quoteFtsTerm(term) {
+  return `"${String(term).replace(/"/g, '""')}"`;
+}
+
+export function normalizeText(text) {
+  return String(text ?? "").trim().toLowerCase();
+}
+
+export function generateMemoryId() {
+  return `mem_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+export function slugify(value) {
+  return String(value ?? "memory")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "memory";
+}
+
+export function walkMarkdownFiles(root) {
+  const out = [];
+  if (!existsSync(root)) return out;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) out.push(path);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+function normalizeTag(tag) {
+  return String(tag ?? "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/\/{2,}/g, "/")
+    .toLowerCase();
+}
+
+function parseFrontmatter(text) {
+  const result = {};
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    const value = match[2];
+    if (value === "") {
+      const items = [];
+      while (i + 1 < lines.length && /^\s+-\s+/.test(lines[i + 1])) {
+        i += 1;
+        items.push(unquoteYaml(lines[i].replace(/^\s+-\s+/, "")));
+      }
+      result[key] = items;
+    } else {
+      result[key] = unquoteYaml(value);
+    }
+  }
+  return result;
+}
+
+function unquoteYaml(value) {
+  const trimmed = String(value ?? "").trim();
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function formatYamlScalar(value) {
+  const text = String(value ?? "");
+  if (/[:#\n]|^\s|\s$/.test(text)) return JSON.stringify(text);
+  return text;
+}
+
+function extractTitle(body) {
+  return body.split(/\r?\n/).find((line) => line.startsWith("# "))?.slice(2).trim() ?? "";
+}