march-cli 0.1.0

package/src/mcp/tools.mjs

@@ -0,0 +1,98 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+/**
+ * Build a tool name from server + tool: mcp__{server}__{tool}
+ */
+export function buildMcpToolName(server, tool) {
+  return `mcp__${sanitize(server)}__${sanitize(tool)}`;
+}
+
+/**
+ * Parse an MCP tool name back into { server, tool }.
+ */
+export function parseMcpToolName(name) {
+  const match = name.match(/^mcp__([^_]+(?:_[^_]+)*?)__([^_]+(?:_.+)?)$/);
+  if (!match) return null;
+  return { server: match[1], tool: match[2] };
+}
+
+function sanitize(s) {
+  return s.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/__+/g, "_");
+}
+
+/**
+ * Map JSON Schema type to TypeBox type.
+ * Handles the common MCP parameter schemas.
+ */
+function schemaToTypeBox(schema) {
+  if (!schema || !schema.properties) return Type.Object({});
+
+  const props = {};
+  const required = new Set(schema.required ?? []);
+
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    let box;
+    switch (prop.type) {
+      case "string":
+        box = Type.String();
+        break;
+      case "number":
+      case "integer":
+        box = Type.Number();
+        break;
+      case "boolean":
+        box = Type.Boolean();
+        break;
+      case "array":
+        box = Type.Array(
+          prop.items ? schemaToTypeBox(prop.items) : Type.Any(),
+        );
+        break;
+      case "object":
+        box = schemaToTypeBox(prop);
+        break;
+      default:
+        box = Type.Any();
+    }
+    if (prop.description) box = box({ description: prop.description });
+    if (!required.has(key)) box = Type.Optional(box);
+    props[key] = box;
+  }
+
+  return Type.Object(props);
+}
+
+/**
+ * Convert an MCP tool definition to a March-compatible tool.
+ */
+export function convertMcpTool(serverName, mcpTool, clientManager) {
+  const fullName = buildMcpToolName(serverName, mcpTool.name);
+  const description = mcpTool.description ?? `MCP tool: ${serverName}/${mcpTool.name}`;
+
+  return defineTool({
+    name: fullName,
+    label: `MCP:${serverName}/${mcpTool.name}`,
+    description: `[MCP ${serverName}] ${description}`,
+    parameters: schemaToTypeBox(mcpTool.inputSchema),
+    execute: async (_toolCallId, params) => {
+      const result = await clientManager.callTool(serverName, mcpTool.name, params);
+      return {
+        content: [{ type: "text", text: result.content }],
+        details: result.details,
+      };
+    },
+  });
+}
+
+/**
+ * Batch-convert all tools from all connected servers.
+ */
+export function convertAllMcpTools(clientManager) {
+  const tools = [];
+  const allTools = clientManager.getAllTools();
+  for (const { server, tool } of allTools) {
+    tools.push(convertMcpTool(server, tool, clientManager));
+  }
+  return tools;
+}

package/src/memory/database.mjs

@@ -0,0 +1,219 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const ROOT_NODE_UUID = "00000000-0000-0000-0000-000000000000";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS nodes (
+  uuid TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  last_accessed_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  node_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  content TEXT NOT NULL,
+  deprecated INTEGER NOT NULL DEFAULT 0,
+  migrated_to INTEGER REFERENCES memories(id),
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  parent_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  child_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  name TEXT NOT NULL,
+  priority INTEGER NOT NULL DEFAULT 0,
+  disclosure TEXT
+);
+
+CREATE TABLE IF NOT EXISTS paths (
+  namespace TEXT NOT NULL DEFAULT '',
+  domain TEXT NOT NULL DEFAULT 'core',
+  path TEXT NOT NULL,
+  edge_id INTEGER NOT NULL REFERENCES edges(id),
+  node_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  PRIMARY KEY (namespace, domain, path)
+);
+
+CREATE TABLE IF NOT EXISTS glossary_keywords (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  keyword TEXT NOT NULL,
+  node_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  namespace TEXT NOT NULL DEFAULT ''
+);
+
+CREATE TABLE IF NOT EXISTS search_documents (
+  node_uuid TEXT NOT NULL,
+  namespace TEXT NOT NULL DEFAULT '',
+  content TEXT NOT NULL,
+  PRIMARY KEY (node_uuid, namespace)
+);
+
+CREATE TABLE IF NOT EXISTS memory_access_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  node_uuid TEXT NOT NULL REFERENCES nodes(uuid),
+  namespace TEXT NOT NULL DEFAULT '',
+  context TEXT,
+  accessed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_node ON memories(node_uuid, deprecated);
+CREATE INDEX IF NOT EXISTS idx_memories_migrated ON memories(migrated_to);
+CREATE INDEX IF NOT EXISTS idx_edges_parent ON edges(parent_uuid);
+CREATE INDEX IF NOT EXISTS idx_edges_child ON edges(child_uuid);
+CREATE INDEX IF NOT EXISTS idx_paths_node ON paths(node_uuid);
+CREATE INDEX IF NOT EXISTS idx_paths_edge ON paths(edge_id);
+CREATE INDEX IF NOT EXISTS idx_glossary_node ON glossary_keywords(node_uuid);
+CREATE INDEX IF NOT EXISTS idx_glossary_keyword ON glossary_keywords(keyword);
+`;
+
+export function openDatabase(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec(SCHEMA);
+  ensureRootNode(db);
+  return db;
+}
+
+function ensureRootNode(db) {
+  const row = db.prepare("SELECT uuid FROM nodes WHERE uuid = ?").get(ROOT_NODE_UUID);
+  if (!row) {
+    db.prepare("INSERT INTO nodes (uuid) VALUES (?)").run(ROOT_NODE_UUID);
+    db.prepare("INSERT INTO memories (node_uuid, content, deprecated) VALUES (?, ?, 0)").run(ROOT_NODE_UUID, "Root node");
+  }
+}
+
+// ── Node operations ────────────────────────────────────────────────────
+
+export function createNode(db, uuid) {
+  db.prepare("INSERT OR IGNORE INTO nodes (uuid) VALUES (?)").run(uuid);
+  return { uuid };
+}
+
+export function getNode(db, uuid) {
+  return db.prepare("SELECT * FROM nodes WHERE uuid = ?").get(uuid);
+}
+
+function touchNode(db, uuid) {
+  db.prepare("UPDATE nodes SET last_accessed_at = datetime('now') WHERE uuid = ?").run(uuid);
+}
+
+// ── Memory operations ───────────────────────────────────────────────────
+
+export function createMemory(db, nodeUuid, content) {
+  const result = db.prepare("INSERT INTO memories (node_uuid, content) VALUES (?, ?)").run(nodeUuid, content);
+  touchNode(db, nodeUuid);
+  return { id: Number(result.lastInsertRowid), node_uuid: nodeUuid, content };
+}
+
+export function getCurrentMemory(db, nodeUuid) {
+  return db.prepare("SELECT * FROM memories WHERE node_uuid = ? AND deprecated = 0 ORDER BY id DESC LIMIT 1").get(nodeUuid);
+}
+
+export function getMemoryHistory(db, nodeUuid) {
+  return db.prepare("SELECT * FROM memories WHERE node_uuid = ? ORDER BY id DESC").all(nodeUuid);
+}
+
+export function updateMemory(db, nodeUuid, newContent) {
+  const current = getCurrentMemory(db, nodeUuid);
+  if (!current) return null;
+  db.prepare("UPDATE memories SET deprecated = 1 WHERE id = ?").run(current.id);
+  const result = db.prepare("INSERT INTO memories (node_uuid, content) VALUES (?, ?)").run(nodeUuid, newContent);
+  db.prepare("UPDATE memories SET migrated_to = ? WHERE id = ?").run(Number(result.lastInsertRowid), current.id);
+  touchNode(db, nodeUuid);
+  return { id: Number(result.lastInsertRowid), node_uuid: nodeUuid, content: newContent, previous_id: current.id };
+}
+
+export function deleteMemory(db, nodeUuid) {
+  const pathRows = db.prepare("SELECT edge_id FROM paths WHERE node_uuid = ?").all(nodeUuid);
+  db.prepare("DELETE FROM paths WHERE node_uuid = ?").run(nodeUuid);
+  for (const row of pathRows) {
+    try { db.prepare("DELETE FROM edges WHERE id = ?").run(row.edge_id); } catch {}
+  }
+  db.prepare("DELETE FROM edges WHERE parent_uuid = ? OR child_uuid = ?").run(nodeUuid, nodeUuid);
+  db.prepare("DELETE FROM glossary_keywords WHERE node_uuid = ?").run(nodeUuid);
+  db.prepare("DELETE FROM search_documents WHERE node_uuid = ?").run(nodeUuid);
+  db.prepare("DELETE FROM memory_access_log WHERE node_uuid = ?").run(nodeUuid);
+  db.prepare("DELETE FROM memories WHERE node_uuid = ?").run(nodeUuid);
+  const result = db.prepare("DELETE FROM nodes WHERE uuid = ? AND uuid != ?").run(nodeUuid, ROOT_NODE_UUID);
+  return result.changes > 0;
+}
+
+// ── Edge operations ─────────────────────────────────────────────────────
+
+export function createEdge(db, parentUuid, childUuid, { name = "related", priority = 0, disclosure = null } = {}) {
+  const result = db.prepare(
+    "INSERT INTO edges (parent_uuid, child_uuid, name, priority, disclosure) VALUES (?, ?, ?, ?, ?)",
+  ).run(parentUuid, childUuid, name, priority, disclosure);
+  return { id: Number(result.lastInsertRowid), parent_uuid: parentUuid, child_uuid: childUuid, name };
+}
+
+export function getEdges(db, nodeUuid, { direction = "both" } = {}) {
+  if (direction === "children") return db.prepare("SELECT * FROM edges WHERE parent_uuid = ? ORDER BY priority DESC").all(nodeUuid);
+  if (direction === "parents") return db.prepare("SELECT * FROM edges WHERE child_uuid = ? ORDER BY priority DESC").all(nodeUuid);
+  return db.prepare("SELECT * FROM edges WHERE parent_uuid = ? OR child_uuid = ? ORDER BY priority DESC").all(nodeUuid, nodeUuid);
+}
+
+export function deleteEdge(db, edgeId) {
+  db.prepare("DELETE FROM paths WHERE edge_id = ?").run(edgeId);
+  return db.prepare("DELETE FROM edges WHERE id = ?").run(edgeId).changes > 0;
+}
+
+// ── Path operations ─────────────────────────────────────────────────────
+
+export function createPath(db, { namespace = "", domain = "core", path, edgeId, nodeUuid }) {
+  db.prepare("INSERT OR REPLACE INTO paths (namespace, domain, path, edge_id, node_uuid) VALUES (?, ?, ?, ?, ?)").run(namespace, domain, path, edgeId, nodeUuid);
+  return { namespace, domain, path, edge_id: edgeId, node_uuid: nodeUuid };
+}
+
+export function getPath(db, namespace, domain, path) {
+  return db.prepare("SELECT * FROM paths WHERE namespace = ? AND domain = ? AND path = ?").get(namespace, domain, path);
+}
+
+export function getPathsForNode(db, nodeUuid) {
+  return db.prepare("SELECT * FROM paths WHERE node_uuid = ?").all(nodeUuid);
+}
+
+export function listPaths(db, namespace = "", domain = "core", parentPath = "") {
+  const prefix = parentPath ? `${parentPath}/` : "";
+  return db.prepare("SELECT * FROM paths WHERE namespace = ? AND domain = ? AND path LIKE ? ORDER BY path").all(namespace, domain, `${prefix}%`);
+}
+
+// ── Glossary operations ─────────────────────────────────────────────────
+
+export function addGlossaryKeyword(db, keyword, nodeUuid, namespace = "") {
+  db.prepare("INSERT OR IGNORE INTO glossary_keywords (keyword, node_uuid, namespace) VALUES (?, ?, ?)").run(keyword, nodeUuid, namespace);
+}
+
+export function findNodeByKeyword(db, keyword, namespace = "") {
+  return db.prepare("SELECT * FROM glossary_keywords WHERE keyword = ? AND (namespace = ? OR namespace = '')").get(keyword, namespace);
+}
+
+export function getGlossaryKeywords(db, namespace = "") {
+  return db.prepare("SELECT * FROM glossary_keywords WHERE namespace = ? OR namespace = '' ORDER BY keyword").all(namespace);
+}
+
+// ── Search operations ───────────────────────────────────────────────────
+
+export function indexSearchDocument(db, nodeUuid, content, namespace = "") {
+  db.prepare("INSERT OR REPLACE INTO search_documents (node_uuid, namespace, content) VALUES (?, ?, ?)").run(nodeUuid, namespace, content);
+}
+
+export function searchByContent(db, query, namespace = "") {
+  return db.prepare("SELECT * FROM search_documents WHERE (namespace = ? OR namespace = '') AND content LIKE ?").all(namespace, `%${query}%`);
+}
+
+// ── Access log ──────────────────────────────────────────────────────────
+
+export function logAccess(db, nodeUuid, context = null, namespace = "") {
+  db.prepare("INSERT INTO memory_access_log (node_uuid, namespace, context) VALUES (?, ?, ?)").run(nodeUuid, namespace, context);
+}
+
+export function getRecentAccesses(db, limit = 20) {
+  return db.prepare("SELECT * FROM memory_access_log ORDER BY accessed_at DESC LIMIT ?").all(limit);
+}

package/src/memory/glossary.mjs

@@ -0,0 +1,124 @@
+export class GlossaryService {
+  constructor(db, namespace = "") {
+    this.db = db;
+    this.namespace = namespace;
+    this.fingerprint = null;
+    this.automaton = null;
+  }
+
+  // ── Aho-Corasick automaton ────────────────────────────────────────
+
+  #ensureAutomaton() {
+    const fp = this.#computeFingerprint();
+    if (fp === this.fingerprint && this.automaton) return;
+    this.fingerprint = fp;
+    this.automaton = this.#buildAutomaton();
+  }
+
+  #computeFingerprint() {
+    const row = this.db.prepare(
+      "SELECT COUNT(*) AS cnt, MAX(id) AS max_id FROM glossary_keywords WHERE namespace = ? OR namespace = 'global'"
+    ).get(this.namespace);
+    return `${row.cnt}:${row.max_id}`;
+  }
+
+  #buildAutomaton() {
+    const keywords = this.db.prepare(
+      "SELECT id, keyword, node_uuid FROM glossary_keywords WHERE namespace = ? OR namespace = 'global'"
+    ).all(this.namespace);
+
+    // Build trie
+    const go = [new Map()];
+    const fail = [0];
+    const output = [new Map()];
+
+    for (const kw of keywords) {
+      let state = 0;
+      for (const ch of kw.keyword) {
+        let next = go[state].get(ch);
+        if (next === undefined) {
+          next = go.length;
+          go.push(new Map());
+          fail.push(0);
+          output.push(new Map());
+          go[state].set(ch, next);
+        }
+        state = next;
+      }
+      output[state].set(kw.id, kw.node_uuid);
+    }
+
+    // Build failure links (BFS)
+    const queue = [];
+    for (const [ch, next] of go[0]) {
+      fail[next] = 0;
+      queue.push(next);
+    }
+
+    while (queue.length > 0) {
+      const r = queue.shift();
+      for (const [ch, s] of go[r]) {
+        queue.push(s);
+        let f = fail[r];
+        while (f > 0 && !go[f].has(ch)) f = fail[f];
+        fail[s] = go[f].has(ch) ? go[f].get(ch) : 0;
+        for (const [kwId, nodeUuid] of output[fail[s]]) {
+          output[s].set(kwId, nodeUuid);
+        }
+      }
+    }
+
+    return { go, fail, output };
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────
+
+  addKeyword(keyword, nodeUuid, namespace = "") {
+    this.db.prepare(
+      "INSERT OR IGNORE INTO glossary_keywords (keyword, node_uuid, namespace) VALUES (?, ?, ?)"
+    ).run(keyword, nodeUuid, namespace);
+    this.fingerprint = null;
+  }
+
+  removeKeyword(keywordId) {
+    this.db.prepare("DELETE FROM glossary_keywords WHERE id = ?").run(keywordId);
+    this.fingerprint = null;
+  }
+
+  findInContent(content) {
+    if (!content) return [];
+    this.#ensureAutomaton();
+    if (!this.automaton) return [];
+
+    const { go, fail, output } = this.automaton;
+    const matches = [];
+    const seen = new Set();
+    let state = 0;
+
+    for (let i = 0; i < content.length; i++) {
+      const ch = content[i];
+      while (state > 0 && !go[state].has(ch)) state = fail[state];
+      state = go[state].has(ch) ? go[state].get(ch) : 0;
+
+      for (const [kwId, nodeUuid] of output[state]) {
+        if (seen.has(kwId)) continue;
+        seen.add(kwId);
+        matches.push({ keyword_id: kwId, node_uuid: nodeUuid });
+      }
+    }
+
+    return matches;
+  }
+
+  getAllKeywords() {
+    return this.db.prepare(
+      "SELECT * FROM glossary_keywords WHERE namespace = ? OR namespace = 'global' ORDER BY keyword"
+    ).all(this.namespace);
+  }
+
+  getKeywordsForNode(nodeUuid) {
+    return this.db.prepare(
+      "SELECT * FROM glossary_keywords WHERE node_uuid = ? AND (namespace = ? OR namespace = 'global')"
+    ).all(nodeUuid, this.namespace);
+  }
+}

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

@@ -0,0 +1,109 @@
+import { ROOT_NODE_UUID } from "../database.mjs";
+import { escapeLikePath } from "./graph-path-utils.mjs";
+import {
+  countPathsForEdge,
+  insertPath,
+} from "./graph-primitives.mjs";
+
+export function deprecateNodeMemories(db, nodeUuid, successorId = null) {
+  const conditions = ["node_uuid = ?", "deprecated = 0"];
+  const params = [nodeUuid];
+  if (successorId !== null) {
+    conditions.push("id != ?");
+    params.push(successorId);
+  }
+  const ids = db.prepare(
+    `SELECT id FROM memories WHERE ${conditions.join(" AND ")}`
+  ).all(...params).map(r => r.id);
+
+  if (ids.length > 0) {
+    const placeholders = ids.map(() => "?").join(",");
+    db.prepare(
+      `UPDATE memories SET deprecated = 1, migrated_to = ? WHERE id IN (${placeholders})`
+    ).run(successorId, ...ids);
+  }
+  return ids;
+}
+
+export function cascadeCreatePaths(db, nodeUuid, domain, basePath, namespace = "", visited = new Set()) {
+  if (visited.has(nodeUuid)) return;
+  visited.add(nodeUuid);
+  try {
+    const childEdges = db.prepare(
+      "SELECT * FROM edges WHERE parent_uuid = ?"
+    ).all(nodeUuid);
+    for (const edge of childEdges) {
+      const childPath = `${basePath}/${edge.name}`;
+      insertPath(db, namespace, domain, childPath, edge.id, edge.child_uuid);
+      cascadeCreatePaths(db, edge.child_uuid, domain, childPath, namespace, visited);
+    }
+  } finally {
+    visited.delete(nodeUuid);
+  }
+}
+
+export function deleteSubtreePaths(db, domain, path, namespace = "") {
+  const safe = escapeLikePath(path);
+  const rows = db.prepare(`
+    SELECT namespace, domain, path, edge_id, node_uuid
+    FROM paths
+    WHERE namespace = ? AND domain = ? AND (path = ? OR path LIKE ? ESCAPE '\\')
+  `).all(namespace, domain, path, `${safe}/%`);
+
+  for (const row of rows) {
+    db.prepare(
+      "DELETE FROM paths WHERE namespace = ? AND domain = ? AND path = ?"
+    ).run(row.namespace, row.domain, row.path);
+  }
+  return rows;
+}
+
+export function cascadeDeleteEdge(db, edge) {
+  const edgePaths = db.prepare(
+    "SELECT * FROM paths WHERE edge_id = ?"
+  ).all(edge.id);
+
+  for (const path of edgePaths) {
+    deleteSubtreePaths(db, path.domain, path.path, path.namespace);
+  }
+  db.prepare("DELETE FROM edges WHERE id = ?").run(edge.id);
+}
+
+export function cascadeDeleteNode(db, nodeUuid) {
+  if (nodeUuid === ROOT_NODE_UUID) return null;
+
+  const edges = db.prepare(
+    "SELECT * FROM edges WHERE parent_uuid = ? OR child_uuid = ?"
+  ).all(nodeUuid, nodeUuid);
+  for (const edge of edges) {
+    cascadeDeleteEdge(db, edge);
+  }
+
+  db.prepare("DELETE FROM memories WHERE node_uuid = ?").run(nodeUuid);
+  db.prepare("DELETE FROM glossary_keywords WHERE node_uuid = ?").run(nodeUuid);
+  db.prepare("DELETE FROM nodes WHERE uuid = ?").run(nodeUuid);
+  return { deleted: nodeUuid };
+}
+
+export function gcEdgeIfPathless(db, edge) {
+  if (countPathsForEdge(db, edge.id) > 0) return null;
+  db.prepare("DELETE FROM edges WHERE id = ?").run(edge.id);
+  return { edge_id: edge.id, parent_uuid: edge.parent_uuid, child_uuid: edge.child_uuid };
+}
+
+export function gcNodeSoft(db, nodeUuid) {
+  if (nodeUuid === ROOT_NODE_UUID) return;
+
+  const row = db.prepare(
+    "SELECT COUNT(*) AS cnt FROM paths WHERE node_uuid = ?"
+  ).get(nodeUuid);
+  if (row.cnt > 0) return;
+
+  const incoming = db.prepare("SELECT * FROM edges WHERE child_uuid = ?").all(nodeUuid);
+  for (const edge of incoming) gcEdgeIfPathless(db, edge);
+
+  const outgoing = db.prepare("SELECT * FROM edges WHERE parent_uuid = ?").all(nodeUuid);
+  for (const edge of outgoing) cascadeDeleteEdge(db, edge);
+
+  deprecateNodeMemories(db, nodeUuid);
+}

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

@@ -0,0 +1,73 @@
+import { ROOT_NODE_UUID } from "../database.mjs";
+
+export function getGraphDiagnostics(db, namespace = "", daysStale = 30, maxChildren = 10) {
+  const cutoff = new Date(Date.now() - daysStale * 86400000).toISOString();
+
+  const allRows = db.prepare(`
+    SELECT p.domain, p.path, p.node_uuid, n.created_at, n.last_accessed_at,
+           e.priority, m.id AS memory_id
+    FROM paths p
+    JOIN edges e ON p.edge_id = e.id
+    JOIN nodes n ON n.uuid = e.child_uuid
+    JOIN memories m ON m.node_uuid = n.uuid AND m.deprecated = 0
+    WHERE p.namespace = ?
+  `).all(namespace);
+
+  const staleNodes = {};
+  for (const row of allRows) {
+    const effective = row.last_accessed_at ?? row.created_at ?? cutoff;
+    if (effective >= cutoff) continue;
+    const staleDays = Math.round((Date.now() - new Date(effective).getTime()) / 86400000);
+    const key = row.node_uuid;
+    if (!staleNodes[key] || (row.priority ?? 999) < (staleNodes[key].priority ?? 999)) {
+      staleNodes[key] = {
+        uuid: row.node_uuid,
+        uri: `${row.domain}://${row.path}`,
+        created_at: row.created_at,
+        last_accessed_at: row.last_accessed_at,
+        stale_days: staleDays,
+        priority: row.priority,
+        title: row.path.split("/").pop(),
+        memory_id: row.memory_id,
+      };
+    }
+  }
+
+  const crowdedRows = db.prepare(`
+    SELECT e.parent_uuid, COUNT(DISTINCT e.child_uuid) AS child_count
+    FROM edges e
+    JOIN paths p ON p.edge_id = e.id
+    WHERE p.namespace = ?
+    GROUP BY e.parent_uuid
+    HAVING child_count > ?
+  `).all(namespace, maxChildren);
+
+  const crowdedParents = {};
+  for (const row of crowdedRows) {
+    if (row.parent_uuid === ROOT_NODE_UUID) {
+      crowdedParents[row.parent_uuid] = {
+        uuid: row.parent_uuid,
+        uri: "core://",
+        title: "(root)",
+        child_count: row.child_count,
+      };
+    } else {
+      const p = db.prepare(
+        "SELECT domain, path FROM paths WHERE node_uuid = ? AND namespace = ? LIMIT 1"
+      ).get(row.parent_uuid, namespace);
+      if (p) {
+        crowdedParents[row.parent_uuid] = {
+          uuid: row.parent_uuid,
+          uri: `${p.domain}://${p.path}`,
+          title: p.path.split("/").pop(),
+          child_count: row.child_count,
+        };
+      }
+    }
+  }
+
+  return {
+    stale_nodes: Object.values(staleNodes).sort((a, b) => (a.last_accessed_at ?? a.created_at ?? "").localeCompare(b.last_accessed_at ?? b.created_at ?? "")),
+    crowded_nodes: Object.values(crowdedParents).sort((a, b) => b.child_count - a.child_count),
+  };
+}

package/src/memory/graph/graph-path-removal.mjs

@@ -0,0 +1,50 @@
+import { deleteSubtreePaths, gcEdgeIfPathless, gcNodeSoft } from "./graph-cascades.mjs";
+import { escapeLikePath, graphUri } from "./graph-path-utils.mjs";
+import { resolveGraphPath } from "./graph-primitives.mjs";
+
+export function removeGraphPath(db, path, domain = "core", namespace = "") {
+  if (path === "") throw new Error("Cannot remove root path.");
+
+  const target = resolveGraphPath(db, path, domain, namespace);
+  if (!target) throw new Error(`Path '${graphUri(domain, path)}' not found`);
+
+  const targetNodeUuid = target.node_uuid;
+  const targetEdge = target.edge;
+  if (!targetEdge) throw new Error(`Path '${domain}://${path}' has no edge.`);
+
+  const wouldOrphan = findWouldOrphanChildren(db, { path, domain, namespace, targetNodeUuid });
+  if (wouldOrphan.length > 0) {
+    const details = wouldOrphan.map(e => `'${e.name}' (${e.child_uuid.slice(0, 8)}...)`).join(", ");
+    throw new Error(`Cannot remove '${graphUri(domain, path)}': children would become unreachable: ${details}`);
+  }
+
+  deleteSubtreePaths(db, domain, path, namespace);
+  gcEdgeIfPathless(db, targetEdge);
+  gcNodeSoft(db, targetNodeUuid);
+  return { deleted: graphUri(domain, path) };
+}
+
+function findWouldOrphanChildren(db, { path, domain, namespace, targetNodeUuid }) {
+  const childEdges = db.prepare("SELECT * FROM edges WHERE parent_uuid = ?").all(targetNodeUuid);
+  const wouldOrphan = [];
+  const safe = escapeLikePath(path);
+
+  for (const childEdge of childEdges) {
+    const surviving = db.prepare(`
+      SELECT COUNT(*) AS cnt FROM paths
+      WHERE node_uuid = ?
+      AND NOT (domain = ? AND (path = ? OR path LIKE ? ESCAPE '\\'))
+    `).get(childEdge.child_uuid, domain, path, `${safe}/%`);
+    if (surviving.cnt > 0) continue;
+
+    const targetSurviving = db.prepare(`
+      SELECT * FROM paths
+      WHERE node_uuid = ? AND namespace = ?
+      AND NOT (domain = ? AND (path = ? OR path LIKE ? ESCAPE '\\'))
+      ORDER BY CASE WHEN domain = ? THEN 0 ELSE 1 END, path
+      LIMIT 1
+    `).get(targetNodeUuid, namespace, domain, path, `${safe}/%`, domain);
+    if (!targetSurviving) wouldOrphan.push(childEdge);
+  }
+  return wouldOrphan;
+}

package/src/memory/graph/graph-path-utils.mjs

@@ -0,0 +1,17 @@
+export function escapeLikePath(path) {
+  return String(path).replace(/[%_]/g, "\\$&");
+}
+
+export function graphUri(domain, path) {
+  return `${domain}://${path}`;
+}
+
+export function leafName(path) {
+  return String(path).split("/").pop();
+}
+
+export function pathExists(db, namespace, domain, path) {
+  return Boolean(db.prepare(
+    "SELECT 1 FROM paths WHERE namespace = ? AND domain = ? AND path = ?"
+  ).get(namespace, domain, path));
+}