@agfpd/iapeer-memory-core 0.1.1

package/src/memoryd.ts

@@ -0,0 +1,680 @@
+/**
+ * memoryd — the single iapeer-memory daemon (ADR-004 + ADR-012).
+ *
+ * One process owns everything live:
+ * - the WRITER role: sole SQLite owner (openDatabase + indexAll), fs.watch
+ *   over the vault with debounce, incremental re-index by content hash;
+ * - the detect subsystems (stage 8 cores): human-edit attribution,
+ *   tags-dictionary mirror, permanent smart-hash diff with COALESCED
+ *   events; INBOX_NEW on new inbox files (baseline at start — pre-existing
+ *   files never replay, parity with the reference monitor);
+ * - the event stream: signal lines on stdout (`INBOX_NEW: …`,
+ *   `PERMANENT_CHANGED: …`) — a notifier watcher forwards each line to the
+ *   Index as an IAP signal (docs/06-pipelines-and-events.md);
+ * - the heartbeat state file (consumer: every peer's SessionStart
+ *   health-check, ADR-009/010);
+ * - the MCP-http endpoint (ADR-012): localhost, port from config, three
+ *   read-only tools (vault_search / vault_graph / vault_map — ADR-008,
+ *   vault_read is NOT on the surface), caller identity from the
+ *   `X-IAPeer-Identity` header per request.
+ *
+ * The supervision (restart, hang detection, alerts) belongs to the
+ * notifier watcher registration owned by the package (ADR-010) — memoryd
+ * itself stays a plain long-running process with clean shutdown.
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+import corePkg from "../package.json";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+import type { CoreConfig } from "./config.js";
+import { openDatabase, type CoreDb } from "./db.js";
+import { indexAll } from "./indexer.js";
+import { runSearch, runGraph, runMap } from "./mcp-tools.js";
+import { decideUpdate, getZone } from "./human-edit-detect.js";
+import { decideMirror, tagsDictionarySourceRel } from "./tags-mirror.js";
+import {
+  snapshotVault,
+  detectPermanentChanges,
+  formatEventLines,
+  type VaultSnapshot,
+} from "./permanent-detect.js";
+import { makeLogger, type Logger } from "./log.js";
+
+// ── identity ────────────────────────────────────────────────────────────────
+
+const KNOWN_RUNTIME_PREFIXES = ["claude-", "codex-"];
+
+/**
+ * `X-IAPeer-Identity: <runtime>-<personality>` → personality. A bare
+ * personality (no known runtime prefix) passes through as-is; personalities
+ * may themselves contain dashes (`iapeer-memory`), so ONLY the known
+ * runtime prefixes are stripped. Missing/empty header → null (admin access,
+ * identity-dependent mechanics like the foreign-memory penalty are off).
+ */
+export function parsePersonalityFromIdentity(
+  header: string | null | undefined,
+): string | null {
+  const v = (header ?? "").trim();
+  if (!v) return null;
+  for (const prefix of KNOWN_RUNTIME_PREFIXES) {
+    if (v.startsWith(prefix) && v.length > prefix.length) {
+      return v.slice(prefix.length);
+    }
+  }
+  return v;
+}
+
+// ── MCP server (three tools, ADR-008) ───────────────────────────────────────
+
+function toResult(payload: unknown): CallToolResult {
+  const structured =
+    payload && typeof payload === "object" && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : undefined;
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    ...(structured ? { structuredContent: structured } : {}),
+  };
+}
+
+function toError(toolName: string, err: unknown, logger: Logger): CallToolResult {
+  const msg = err instanceof Error ? err.message : String(err);
+  logger.error(`tool ${toolName} failed: ${msg}`);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: msg }, null, 2) }],
+    isError: true,
+  };
+}
+
+// Zod fragments — ported from the reference server (vault_read schema
+// deliberately absent, ADR-008).
+const relatedItem = z.object({
+  path: z.string(),
+  title: z.string(),
+  direction: z.string(),
+});
+
+const searchResultItem = z.object({
+  title: z.string(),
+  path: z.string(),
+  type: z.string().nullable(),
+  status: z.string().nullable(),
+  score: z.number(),
+  snippet: z.string(),
+  related: z.array(relatedItem),
+});
+
+const pipelineStatusSchema = z.object({
+  bm25: z.string(),
+  embedding: z.string(),
+  reranker: z.string(),
+  graph: z.string(),
+  caller_agent: z.string().nullable(),
+  for_curation: z.boolean(),
+});
+
+const vaultSearchOutput = z.object({
+  query: z.string(),
+  results: z.array(searchResultItem),
+  pipeline: pipelineStatusSchema,
+});
+
+const graphNode = z.object({
+  path: z.string(),
+  title: z.string(),
+  type: z.string().nullable(),
+  status: z.string().nullable(),
+  depth: z.number(),
+  direction: z.string(),
+});
+
+const graphEdge = z.object({ from: z.string(), to: z.string() });
+
+const vaultGraphOutput = z.object({
+  center: z
+    .object({ path: z.string(), title: z.string(), type: z.string().nullable() })
+    .optional(),
+  nodes: z.array(graphNode).optional(),
+  edges: z.array(graphEdge).optional(),
+  stats: z
+    .object({ totalNodes: z.number(), totalEdges: z.number(), depth: z.number() })
+    .optional(),
+  found: z.boolean().optional(),
+  error: z.string().optional(),
+});
+
+const mapPart = z.enum(["clusters", "hubs", "bridges", "orphans", "orphan_wikilinks"]);
+
+const mapClusterFull = z.object({
+  name: z.string(),
+  size: z.number(),
+  hub: z.object({ title: z.string(), degree: z.number() }).nullable(),
+  nodes: z.array(z.string()),
+});
+const mapClusterSummary = z.object({
+  name: z.string(),
+  size: z.number(),
+  hub: z.object({ title: z.string(), degree: z.number() }).nullable(),
+  top_nodes: z.array(z.string()),
+});
+
+const mapHub = z.object({
+  title: z.string(),
+  in: z.number(),
+  out: z.number(),
+  total: z.number(),
+});
+
+const mapBridge = z.object({ title: z.string(), connects: z.array(z.string()) });
+
+const vaultMapOutput = z.object({
+  generated: z.string(),
+  stats: z.object({
+    documents: z.number(),
+    edges: z.number(),
+    clusters: z.number(),
+    hubs: z.number(),
+    bridges: z.number(),
+    orphans: z.number(),
+    orphan_wikilinks: z.number(),
+  }),
+  detail: z.enum(["summary", "full"]),
+  parts: z.array(mapPart),
+  clusters: z.array(z.union([mapClusterFull, mapClusterSummary])).optional(),
+  hubs: z.array(mapHub).optional(),
+  hubs_truncated: z.number().optional(),
+  bridges: z.array(mapBridge).optional(),
+  orphans: z.array(z.string()).optional(),
+  orphan_wikilinks: z
+    .array(z.object({ source: z.string(), target: z.string(), reason: z.string() }))
+    .optional(),
+});
+
+export const MEMORYD_SERVER_NAME = "iapeer-memory";
+
+function readCoreVersion(): string {
+  // STATIC json import (embedded by the bundler), not a runtime fs read:
+  // under `bun build --compile` import.meta.url resolves into /$bunfs/ where
+  // ../package.json does not exist (P3a compile fact-check).
+  try {
+    const v = (corePkg as { version?: unknown }).version;
+    if (typeof v === "string" && v.length > 0) return v;
+  } catch {
+    // fall through
+  }
+  return "0.0.0";
+}
+
+/**
+ * Build an MCP server instance with the three-tool surface. `identity` is
+ * the caller personality from the http header — it OVERRIDES the config's
+ * env-fallback callerAgent for this connection (ADR-012).
+ */
+export function createMcpServer(opts: {
+  db: CoreDb;
+  config: CoreConfig;
+  identity?: string | null;
+  logger?: Logger;
+}): McpServer {
+  const { db, config } = opts;
+  const logger = opts.logger ?? makeLogger("memoryd");
+  const effectiveConfig: CoreConfig = {
+    ...config,
+    callerAgent: opts.identity ?? config.callerAgent,
+  };
+
+  const server = new McpServer(
+    { name: MEMORYD_SERVER_NAME, version: readCoreVersion() },
+    {
+      instructions:
+        "iapeer-memory vault — shared team memory. vault_search is the default " +
+        "entry point when you don't have an exact path; read notes with the " +
+        "native Read tool after search. Stale-status notes are score-deboosted " +
+        "but still returned — treat them as history, not current truth.",
+    },
+  );
+
+  server.registerTool(
+    "vault_search",
+    {
+      description:
+        "Search the vault for knowledge, decisions and context when you don't know the exact note path. " +
+        "Hybrid pipeline: BM25 + optional vector/rerank providers → RRF fusion → status boost → 1-hop graph expansion → backlink boost. " +
+        "Returns up to max_results items (title, path, type, status, score, snippet, related). " +
+        "Read the found note with the native Read tool. " +
+        "The `pipeline` object reports per-component status (ok/disabled/skipped/timeout/error/circuit-open).",
+      inputSchema: {
+        query: z.string().min(1, "vault_search: query is required"),
+        forCuration: z.boolean().optional(),
+      },
+      outputSchema: vaultSearchOutput.shape,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    },
+    async ({ query, forCuration }) => {
+      try {
+        return toResult(await runSearch(db, effectiveConfig, { query, forCuration }));
+      } catch (err) {
+        return toError("vault_search", err, logger);
+      }
+    },
+  );
+
+  server.registerTool(
+    "vault_graph",
+    {
+      description:
+        "Walk the wikilink graph outward from a note, 1–3 hops in both directions. " +
+        "Returns nodes and edges of the subgraph; agent-memory backlinks of canonical notes are filtered (one-way). " +
+        "Unknown center path → {found:false}.",
+      inputSchema: {
+        path: z.string().min(1, "vault_graph: path is required"),
+        depth: z.number().int().min(1).max(3).optional(),
+      },
+      outputSchema: vaultGraphOutput.shape,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    async ({ path: p, depth }) => {
+      try {
+        return toResult(runGraph(db, effectiveConfig, { path: p, depth }));
+      } catch (err) {
+        return toError("vault_graph", err, logger);
+      }
+    },
+  );
+
+  server.registerTool(
+    "vault_map",
+    {
+      description:
+        "Global topology of the CANONICAL vault graph (agent memory excluded): " +
+        "clusters, hubs, bridges, orphans + orphan_wikilinks (opt-in part). " +
+        "Stats always returned.",
+      inputSchema: {
+        detail: z.enum(["summary", "full"]).optional(),
+        parts: z.array(mapPart).optional(),
+      },
+      outputSchema: vaultMapOutput.shape,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    async ({ detail, parts }) => {
+      try {
+        return toResult(runMap(db, effectiveConfig, { detail, parts }));
+      } catch (err) {
+        return toError("vault_map", err, logger);
+      }
+    },
+  );
+
+  return server;
+}
+
+/**
+ * Start the MCP-http endpoint (ADR-012): stateless transport, one
+ * server+transport pair per request, identity from the
+ * `X-IAPeer-Identity` header. Returns the bound port and a closer.
+ */
+export async function startMcpHttp(opts: {
+  db: CoreDb;
+  config: CoreConfig;
+  port?: number;
+  host?: string;
+  logger?: Logger;
+}): Promise<{ port: number; close: () => Promise<void> }> {
+  const logger = opts.logger ?? makeLogger("memoryd");
+  const host = opts.host ?? "127.0.0.1";
+
+  const httpServer = http.createServer((req, res) => {
+    void (async () => {
+      const url = (req.url ?? "").split("?")[0];
+      if (url !== "/mcp") {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "not found; MCP endpoint is /mcp" }));
+        return;
+      }
+      const identity = parsePersonalityFromIdentity(
+        (req.headers["x-iapeer-identity"] as string | undefined) ?? null,
+      );
+      const server = createMcpServer({ db: opts.db, config: opts.config, identity, logger });
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless: no session tracking
+      });
+      res.on("close", () => {
+        void transport.close();
+        void server.close();
+      });
+      try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+      } catch (err) {
+        logger.error(`mcp http request failed: ${String(err)}`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "internal error" }));
+        }
+      }
+    })();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(opts.port ?? 0, host, () => resolve());
+  });
+  const address = httpServer.address();
+  const port = typeof address === "object" && address ? address.port : (opts.port ?? 0);
+  logger.info(`MCP http listening on http://${host}:${port}/mcp`);
+
+  return {
+    port,
+    close: () =>
+      new Promise<void>((resolve) => {
+        // Kill keep-alive/SSE connections FIRST — otherwise close() waits
+        // for them and a daemon shutdown hangs for the keep-alive timeout.
+        httpServer.closeAllConnections?.();
+        httpServer.closeIdleConnections?.();
+        const fallback = setTimeout(resolve, 1500);
+        (fallback as { unref?: () => void }).unref?.();
+        httpServer.close(() => {
+          clearTimeout(fallback);
+          resolve();
+        });
+      }),
+  };
+}
+
+// ── detect-hash persistence (stage-9 review note 5) ─────────────────────────
+//
+// Without persistence a daemon restart zeroed the human-edit detector's
+// last-seen map: the first event per file skipped the content-hash guard.
+// The risk is LOWER here than in the reference (the startup full-scan
+// catches up indexing; the echo window suppresses spurious re-stamps), but
+// a sync-storm right after a restart could still mis-attribute — so the
+// baseline survives restarts, atomically (same tmp+rename canon).
+
+export function loadHashState(filePath: string): Map<string, string> {
+  const map = new Map<string, string>();
+  try {
+    const obj = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>;
+    for (const [k, v] of Object.entries(obj)) {
+      if (typeof v === "string" && /^[a-f0-9]{64}$/.test(v)) map.set(k, v);
+    }
+  } catch {
+    // first run / corrupt file — start empty
+  }
+  return map;
+}
+
+export function persistHashState(filePath: string, map: Map<string, string>): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(Object.fromEntries(map)), "utf-8");
+  fs.renameSync(tmp, filePath);
+}
+
+// ── the daemon ───────────────────────────────────────────────────────────────
+
+export type MemorydOptions = {
+  config: CoreConfig;
+  logger?: Logger;
+  /** Event sink; default writes signal lines to stdout. */
+  emit?: (line: string) => void;
+  /** Debounce for fs events (ms). */
+  debounceMs?: number;
+  /** Heartbeat period (ms). */
+  heartbeatMs?: number;
+  /** Heartbeat file; default `<db dir>/memoryd.heartbeat`. */
+  heartbeatPath?: string;
+  /** Tags mirror target; default `<db dir>/tags-dictionary.md`. */
+  tagsMirrorPath?: string;
+  /** Detect-hash persistence file; default `<db dir>/memoryd.hashes.json`. */
+  hashStatePath?: string;
+  /** Periodic hash-persist interval (ms). */
+  persistMs?: number;
+  /** Human owner name; human-edit detection is OFF when absent (⚖7). */
+  humanName?: string | null;
+  freshEditWindowS?: number;
+  /**
+   * MCP http port (0 = ephemeral). Pass null to disable the endpoint;
+   * omit to use `config.mcp.port` (the configured default, ADR-012).
+   */
+  mcpPort?: number | null;
+};
+
+export type MemorydHandle = {
+  mcpPort: number | null;
+  /** Force one detect pass immediately (used by tests and shutdown flush). */
+  runDetectPass: () => Promise<void>;
+  close: () => Promise<void>;
+};
+
+export async function startMemoryd(opts: MemorydOptions): Promise<MemorydHandle> {
+  const { config } = opts;
+  const logger = opts.logger ?? makeLogger("memoryd");
+  const emit = opts.emit ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const debounceMs = opts.debounceMs ?? 1500;
+  const heartbeatMs = opts.heartbeatMs ?? 30_000;
+  const dbDir = path.dirname(config.index.dbPath);
+  const heartbeatPath = opts.heartbeatPath ?? path.join(dbDir, "memoryd.heartbeat");
+  const tagsMirrorPath = opts.tagsMirrorPath ?? path.join(dbDir, "tags-dictionary.md");
+  const hashStatePath = opts.hashStatePath ?? path.join(dbDir, "memoryd.hashes.json");
+  const persistMs = opts.persistMs ?? 60_000;
+  const taxonomy = config.taxonomy;
+
+  const db = openDatabase(config);
+  await indexAll({ db, config, logger });
+
+  // Baselines: detect from NOW on; pre-existing inbox files do not replay
+  // (the Index catches them up at its own start — reference semantics).
+  let snapshot: VaultSnapshot = snapshotVault(config.vaultPath, taxonomy);
+  const inboxDir = path.join(config.vaultPath, taxonomy.folders.inbox);
+  const inboxSeen = new Set<string>(
+    fs.existsSync(inboxDir) ? fs.readdirSync(inboxDir).filter((f) => f.endsWith(".md")) : [],
+  );
+  const lastSeenHashes = loadHashState(hashStatePath);
+
+  syncTagsMirror(); // best-effort materialisation at start
+
+  function syncTagsMirror(): void {
+    const srcPath = path.join(config.vaultPath, tagsDictionarySourceRel(taxonomy));
+    let srcContent: string | null = null;
+    try {
+      srcContent = fs.readFileSync(srcPath, "utf-8");
+    } catch {
+      srcContent = null;
+    }
+    let mirrorContent: string | null = null;
+    try {
+      mirrorContent = fs.readFileSync(tagsMirrorPath, "utf-8");
+    } catch {
+      mirrorContent = null;
+    }
+    const decision = decideMirror({ srcContent, mirrorContent });
+    if (decision.action !== "write") return;
+    fs.mkdirSync(path.dirname(tagsMirrorPath), { recursive: true });
+    const tmp = `${tagsMirrorPath}.tmp`;
+    fs.writeFileSync(tmp, srcContent!, "utf-8");
+    fs.renameSync(tmp, tagsMirrorPath);
+    logger.info(`tags mirror updated (${decision.reason})`);
+  }
+
+  function humanEditPass(changedAbs: Set<string>): void {
+    const human = opts.humanName ?? null;
+    if (!human) return; // ⚖7: no human role — detection off
+    for (const filePath of changedAbs) {
+      const zone = getZone(filePath, config.vaultPath, taxonomy);
+      if (!zone) continue;
+      let content: string;
+      let stat: fs.Stats;
+      try {
+        content = fs.readFileSync(filePath, "utf-8");
+        stat = fs.statSync(filePath);
+      } catch {
+        continue; // deleted mid-debounce
+      }
+      const decision = decideUpdate({
+        content,
+        zone,
+        human,
+        nowMs: Date.now(),
+        birthtimeMs: stat.birthtime ? stat.birthtime.getTime() : 0,
+        mtimeMs: stat.mtime.getTime(),
+        basename: path.basename(filePath),
+        lastHash: lastSeenHashes.get(filePath) ?? null,
+        taxonomy,
+        freshEditWindowS: opts.freshEditWindowS,
+      });
+      if (decision.action === "skip") {
+        if (decision.recordHash !== null) lastSeenHashes.set(filePath, decision.recordHash);
+        continue;
+      }
+      const tmp = `${filePath}.memoryd.tmp`;
+      try {
+        fs.writeFileSync(tmp, decision.newContent, "utf-8");
+        fs.renameSync(tmp, filePath);
+        lastSeenHashes.set(filePath, decision.recordHash);
+        logger.info(`human-edit ${decision.reason}: ${path.relative(config.vaultPath, filePath)}`);
+      } catch (err) {
+        try {
+          fs.unlinkSync(tmp);
+        } catch {
+          // best effort
+        }
+        logger.error(`human-edit write failed for ${filePath}: ${String(err)}`);
+      }
+    }
+  }
+
+  // ── fs.watch + debounce ──
+  const pending = new Set<string>();
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let flushing: Promise<void> = Promise.resolve();
+
+  async function flush(): Promise<void> {
+    const changed = new Set(pending);
+    pending.clear();
+
+    // INBOX_NEW — new inbox files since the baseline.
+    for (const abs of changed) {
+      const rel = path.relative(config.vaultPath, abs);
+      const parts = rel.split(path.sep);
+      if (parts[0] === taxonomy.folders.inbox && parts.length === 2) {
+        const name = parts[1];
+        if (!inboxSeen.has(name) && fs.existsSync(abs)) {
+          inboxSeen.add(name);
+          emit(`INBOX_NEW: ${name}`);
+        }
+      }
+    }
+
+    humanEditPass(changed);
+    syncTagsMirror();
+    await indexAll({ db, config, logger }); // incremental by content hash
+
+    const { event, next } = detectPermanentChanges({
+      vault: config.vaultPath,
+      taxonomy,
+      prev: snapshot,
+    });
+    snapshot = next;
+    if (event) {
+      for (const line of formatEventLines(event)) emit(line);
+    }
+  }
+
+  function schedule(absPath: string): void {
+    pending.add(absPath);
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flushing = flushing.then(() => flush()).catch((err) => {
+        logger.error(`detect pass failed: ${String(err)}`);
+      });
+    }, debounceMs);
+  }
+
+  let watcher: fs.FSWatcher | null = null;
+  try {
+    watcher = fs.watch(config.vaultPath, { recursive: true }, (_event, filename) => {
+      if (!filename || !filename.toString().endsWith(".md")) return;
+      const name = filename.toString();
+      if (name.includes(".memoryd.tmp")) return;
+      schedule(path.join(config.vaultPath, name));
+    });
+  } catch (err) {
+    logger.error(`fs.watch failed (events degraded to manual passes): ${String(err)}`);
+  }
+
+  // ── heartbeat ──
+  function touchHeartbeat(): void {
+    try {
+      fs.mkdirSync(path.dirname(heartbeatPath), { recursive: true });
+      fs.writeFileSync(heartbeatPath, `${new Date().toISOString()} ${os.hostname()}\n`);
+    } catch (err) {
+      logger.error(`heartbeat write failed: ${String(err)}`);
+    }
+  }
+  touchHeartbeat();
+  const heartbeatTimer = setInterval(touchHeartbeat, heartbeatMs);
+  heartbeatTimer.unref?.();
+
+  // Periodic atomic persist of the detect baseline (only when changed —
+  // no churn); a non-graceful exit loses at most one interval.
+  let lastPersistedJson: string | null = null;
+  function persistQuiet(): void {
+    try {
+      const json = JSON.stringify(Object.fromEntries(lastSeenHashes));
+      if (json === lastPersistedJson) return;
+      persistHashState(hashStatePath, lastSeenHashes);
+      lastPersistedJson = json;
+    } catch (err) {
+      logger.error(`hash-state persist failed: ${String(err)}`);
+    }
+  }
+  const persistTimer = setInterval(persistQuiet, persistMs);
+  persistTimer.unref?.();
+
+  // ── MCP http ──
+  let mcp: { port: number; close: () => Promise<void> } | null = null;
+  if (opts.mcpPort !== null) {
+    mcp = await startMcpHttp({ db, config, port: opts.mcpPort ?? config.mcp.port, logger });
+  }
+
+  logger.info(
+    `memoryd up: vault=${config.vaultPath}, watch=${watcher ? "on" : "OFF"}, mcp=${mcp ? mcp.port : "disabled"}`,
+  );
+
+  return {
+    mcpPort: mcp?.port ?? null,
+    runDetectPass: async () => {
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      await flushing;
+      await flush();
+    },
+    close: async () => {
+      watcher?.close();
+      if (flushTimer) clearTimeout(flushTimer);
+      clearInterval(heartbeatTimer);
+      clearInterval(persistTimer);
+      await flushing;
+      persistQuiet();
+      if (mcp) await mcp.close();
+      try {
+        fs.unlinkSync(heartbeatPath);
+      } catch {
+        // best effort
+      }
+      db.close();
+    },
+  };
+}