@modusensus/dsh-mneme 0.7.11 → 0.7.13

package/lib/summarize.js

@@ -1,9 +1,22 @@
 import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 
-const SUMMARY_PROMPT = `你是记忆库提炼助手。根据下面的会话内容，提炼 2-3 条值得跨会话记住的记忆。
-只输出 JSON 数组，每项形如 {"type":"preference|project|decision|history","title":"简短标题","content":"一句话内容","importance":1-5}。
+const SUMMARY_PROMPT = `你是记忆库提炼助手。根据下面的会话内容，提炼值得跨会话记住的原子记忆。
+原子记忆原则：每条记忆只装一个独立事实/偏好/决策，短小、自带完整上下文（把数字、名字、路径、结论等原始细节保留在 content 里，不要抽象概括）；宁可拆成多条也绝不合并丢细节。信息量一般提 2-4 条，信息密集的对话可提 4-8 条。
+只输出 JSON 数组，每项形如 {"type":"preference|project|decision|history","title":"简短标题","content":"保留原始细节的一句话","importance":1-5}。
 不要输出任何其他文字。`;
 
+// 编码记忆蒸馏 prompt（codingRetrospect 开启时启用）：在通用记忆之外，额外提取
+// 三类编码专属记忆，专治重复踩坑 / 遗忘被否决方案 / 丢失工程约束。字段仍沿用
+// title/content 单列结构（store 无结构化字段），信息浓缩进 content。
+const CODING_SUMMARY_PROMPT = `你是记忆库提炼助手。根据下面的会话内容（含用户输入、助手思考/回答、工具调用与结果），提炼值得跨会话记住的原子记忆。
+原子记忆原则：每条记忆只装一个独立事实/偏好/决策，短小、自带完整上下文（把数字、报错信息、命令、路径、结论等原始细节保留在 content 里，不要抽象概括）；宁可拆成多条也绝不合并丢细节。信息量一般提 2-4 条，信息密集的对话可提 4-8 条。
+只输出 JSON 数组，每项形如 {"type":"preference|project|decision|history|rejected_solution|pitfall|constraint","title":"简短标题","content":"保留原始细节的一句话","importance":1-5}。
+若对话涉及编码/调试，可额外提取编码类记忆：
+- rejected_solution：被否决/废弃的实现方案（content 含方案简述 + 被否决原因 + 最终采用方案）
+- pitfall：调试踩坑记录（content 含现象/报错 + 根因 + 解决/规避方法）
+- constraint：项目工程约束（content 含约束描述 + 来源）
+普通闲聊、临时无关对话一律不提取编码类记忆。不要输出任何其他文字。`;
+
 /** Extract a JSON array from LLM output that may contain prose around it. */
 export function parseSummaryJson(raw) {
   const text = String(raw ?? "");
@@ -17,7 +30,7 @@ export function parseSummaryJson(raw) {
     return [];
   }
   if (!Array.isArray(arr)) return [];
-  const VALID = new Set(["preference", "project", "decision", "history"]);
+  const VALID = new Set(["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"]);
   return arr.filter(
     (item) =>
       item &&
@@ -76,22 +89,108 @@ function toProtocolChunk(chunk) {
 // events must not leak into the memory store. Events without a data payload
 // (minimal test doubles) pass the kind check and are handled by the content
 // check below.
-// DSH ≥0.1.2-rc removed the Session.events property; events are only reachable
-// via snapshotEvents(). Older DSH builds still expose .events, so fall back.
-function getSessionEvents(session) {
-  return session?.snapshotEvents?.() ?? session?.events ?? [];
+//
+// codingRetrospect: the distill context is the FULL turn transcript —
+// user prompts plus assistant thinking/replies, tool calls + results and code
+// dispatch output — so the summarizer can see tool errors and extract pitfall
+// root causes, not just what the user typed. The same filtering stays: only
+// source.kind === "user" prompts enter (plugin/machine content is excluded).
+// The result is a single text transcript passed to the LLM as one user message
+// (SUMMARY_PROMPT already says "根据下面的会话内容").
+function collectMessages(session, maxChars = 8000) {
+  // DSH 0.1.2-rc.1 起 Session 改用 snapshotEvents()，兼容旧版 .events
+  const events = session.snapshotEvents?.() ?? session.events ?? [];
+  const lines = [];
+  // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
+  // 直接传字符串数组）。text 之外按需抽 thinking/reasoning 块。
+  const textOf = (content) => {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content
+      .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
+      .filter((s) => s)
+      .join("\n");
+  };
+  const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
+  for (const event of events) {
+    const data = event?.data ?? {};
+    const kind = data?.source?.kind;
+    switch (event.type) {
+      case "user/message": {
+        if (kind !== undefined && kind !== "user") break;
+        const text = textOf(data?.content);
+        if (text.trim()) lines.push(`用户：${text}`);
+        break;
+      }
+      case "assistant/message": {
+        const msg = data?.message;
+        const blocks = Array.isArray(msg?.content) ? msg.content : [];
+        const text = textOf(blocks);
+        if (text.trim()) lines.push(`助手：${text}`);
+        const thinking = blocks
+          .map((b) => (typeof b === "string" ? "" : (b && b.type === "reasoning" && typeof b.text === "string" ? b.text : "")))
+          .filter((s) => s)
+          .join("\n");
+        if (thinking.trim()) lines.push(`助手思考：${thinking}`);
+        break;
+      }
+      case "tool/call": {
+        const args = typeof data.arguments === "string"
+          ? data.arguments
+          : data.arguments ? JSON.stringify(data.arguments) : "";
+        lines.push(`工具调用：${data.name ?? "?"}(${trim(args, 300)})`);
+        break;
+      }
+      case "tool/result": {
+        const out = typeof data.output === "string" ? data.output : data.output ? JSON.stringify(data.output) : "";
+        const status = data.ok === false ? "失败" : "成功";
+        lines.push(`工具结果（${status}）：${trim(out, 500)}`);
+        break;
+      }
+      case "tool/code-dispatch": {
+        const out = typeof data.output === "string" ? data.output : data.output ? JSON.stringify(data.output) : "";
+        const status = data.ok === false ? "失败" : "成功";
+        lines.push(`代码执行（${status}）：${trim(out, 500)}`);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return lines.length ? [createUserMessage({ content: [{ type: "text", text: trim(lines.join("\n"), maxChars) }] })] : [];
 }
 
-function collectMessages(session) {
-  const messages = [];
-  for (const event of getSessionEvents(session)) {
-    const kind = event.data?.source?.kind;
-    if (event.type !== "user/message") continue;
-    if (kind !== undefined && kind !== "user") continue;
-    if (!event.data?.content?.length) continue; // nothing to summarize
-    messages.push(createUserMessage({ content: event.data.content }));
-  }
-  return messages.slice(-20);
+// ── 智能调速器（429 保护）─────────────────────────────────────────────
+// 对话一多时 turn/end 会批量触发蒸馏，多个 LLM 请求"一拥而上"正是 429 的
+// 来源。这里借鉴机场安检的思路：所有蒸馏调用进同一个全局串行队列，按间隔
+// distillRateLimitIntervalMs 分批放行；命中 429 时按 distillRateLimitBaseDelayMs
+// 指数退避（1s→2s→4s…）自动重试 distillRateLimitRetries 次，全程对用户透明，
+// 不把 429 错误码直接抛出去。
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function isRateLimited(error) {
+  const status = error?.status ?? error?.statusCode ?? error?.response?.status;
+  if (status === 429) return true;
+  const msg = String(error?.message ?? error ?? "");
+  return /429|rate.?limit|too many requests|请求过于频繁/i.test(msg);
+}
+
+// 全局串行链：每个蒸馏任务在前一个结束后才开始，单次失败不阻塞后续。
+// 相邻请求间隔按"距上一个结束不足 intervalMs 就补齐等待"实现——单次蒸馏
+// 零延迟（上次结束距今已超过间隔，直接放行），只有连续批量蒸馏才触发限速。
+let distillQueue = Promise.resolve();
+let lastDistillEnd = 0;
+function enqueueDistill(task, intervalMs = 0) {
+  const run = distillQueue.then(async () => {
+    if (intervalMs > 0) {
+      const wait = Math.max(0, intervalMs - (Date.now() - lastDistillEnd));
+      if (wait > 0) await sleep(wait);
+    }
+    lastDistillEnd = Date.now();
+    return task();
+  });
+  distillQueue = run.catch(() => {});
+  return run;
 }
 
 export function createSummarizer(ctx, service, config) {
@@ -104,7 +203,7 @@ export function createSummarizer(ctx, service, config) {
     if (disposed || inFlight.has(session.id)) return;
     const controller = new AbortController();
     inFlight.set(session.id, controller);
-    // Bug8: audit state for the compression call. null = no audit for this run
+    // audit state for the compression call. null = no audit for this run
     // (disabled, or no LLM call was actually made). The audit row is written in
     // the finally below — once, regardless of which exit path the call took —
     // so a failed/aborted stream still leaves a status='error' trail without
@@ -119,7 +218,9 @@ export function createSummarizer(ctx, service, config) {
           ? { provider: header.provider, model: header.model }
           : undefined;
       if (!route) return;
-      const messages = collectMessages(session);
+      // 完整转录（Codex 式）：蒸馏把整轮对话交给 LLM 提炼原子记忆，不再硬裁
+      // 8000 字截断语义；上限由 distillMaxChars 控制（默认 24000，可调大）。
+      const messages = collectMessages(session, config.distillMaxChars ?? 24000);
       if (!messages.length) return;
 
       if (config?.llmAudit?.enabled !== false && typeof service.saveLlmAudit === "function") {
@@ -134,61 +235,98 @@ export function createSummarizer(ctx, service, config) {
         };
       }
 
-      const assembler = new BlockAssembler();
-      let text = "";
       const options = {
         provider: route.provider,
         model: route.model,
         purpose: "summarization",
         messages: [
-          { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
+          { role: "system", content: [{ type: "text", text: config.codingRetrospect ? CODING_SUMMARY_PROMPT : SUMMARY_PROMPT }] },
           ...messages
         ],
         signal: controller.signal
       };
-      try {
-        for await (const chunk of ctx.llm.stream(options)) {
-          if (STREAM_CHUNK_TYPES.has(chunk.type)) assembler.push(toProtocolChunk(chunk));
-          if (chunk.type === "text-delta") {
-            text += chunk.text ?? chunk.delta ?? "";
-          }
-          if (chunk.type === "usage" && audit) {
-            const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
-            const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
-            if (Number.isFinite(i)) audit.inputTokens = i;
-            if (Number.isFinite(o)) audit.outputTokens = o;
-          }
-          if (chunk.type === "finish") {
-            const reasonKind = chunk.reason?.kind ?? chunk.kind;
-            if (reasonKind === "error" || reasonKind === "aborted") {
-              if (audit) {
-                audit.status = "error";
-                audit.errorMessage = `llm stream ${reasonKind}`;
+      // 智能调速器：整段蒸馏 LLM 调用进全局串行队列，按间隔分批放行；429 时
+      // 指数退避自动重试，全程对用户透明，不把 429 错误码直接抛出去。
+      const intervalMs = config.distillRateLimitIntervalMs ?? 1000;
+      const { text, assembledText, aborted } = await enqueueDistill(async () => {
+        const retries = config.distillRateLimitRetries ?? 3;
+        const baseDelayMs = config.distillRateLimitBaseDelayMs ?? 1000;
+        for (let attempt = 0; ; attempt++) {
+          const assembler = new BlockAssembler();
+          let text = "";
+          let aborted = false;
+          try {
+            for await (const chunk of ctx.llm.stream(options)) {
+              if (STREAM_CHUNK_TYPES.has(chunk.type)) assembler.push(toProtocolChunk(chunk));
+              if (chunk.type === "text-delta") {
+                text += chunk.text ?? chunk.delta ?? "";
+              }
+              if (chunk.type === "usage" && audit) {
+                const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
+                const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
+                if (Number.isFinite(i)) audit.inputTokens = i;
+                if (Number.isFinite(o)) audit.outputTokens = o;
               }
-              return;
+              if (chunk.type === "finish") {
+                const reasonKind = chunk.reason?.kind ?? chunk.kind;
+                if (reasonKind === "error" || reasonKind === "aborted") {
+                  // 429 也可能以 finish reason error 携带 rate-limit 信息，统一
+                  // 转抛错走指数退避重试。
+                  if (isRateLimited(chunk.reason ?? chunk)) {
+                    throw Object.assign(new Error("rate limited"), { status: 429 });
+                  }
+                  if (audit) {
+                    audit.status = "error";
+                    audit.errorMessage = `llm stream ${reasonKind}`;
+                  }
+                  aborted = true;
+                  break;
+                }
+              }
+            }
+            // Direct delta accumulation is the primary extraction path (it works
+            // for real protocol chunks {index,text} and looser {delta} shapes
+            // alike); the assembler blocks are a fallback for streams that only
+            // deliver text inside block-end. This dsh-llm exposes no public
+            // no-arg assemble() — blocks() is the message-level API.
+            const blocks = assembler.blocks();
+            const assembledText = blocks
+              .filter((b) => b.type === "text")
+              .map((b) => b.text ?? "")
+              .join("");
+            return { text, assembledText, aborted };
+          } catch (error) {
+            if (error?.name === "AbortError" || controller.signal.aborted) throw error; // dispose 中止直接放行
+            if (isRateLimited(error) && attempt < retries) {
+              const delay = baseDelayMs * 2 ** attempt;
+              ctx.logger?.warn?.(
+                `dsh-mneme: 蒸馏请求过于频繁(429)，为避免限流等待 ${delay}ms 后自动重试（第 ${attempt + 1}/${retries} 次）`
+              );
+              await sleep(delay);
+              continue;
+            }
+            // 429 重试耗尽或非 429 错误：记 audit 后抛出，保持原失败路径。
+            if (audit) {
+              audit.status = "error";
+              audit.errorMessage = String(error?.message ?? error);
             }
+            throw error;
           }
         }
-      } catch (error) {
-        if (audit) {
-          audit.status = "error";
-          audit.errorMessage = String(error?.message ?? error);
-        }
-        throw error; // caller's catch handles the failure; audit already staged
-      }
-      // Direct delta accumulation is the primary extraction path (it works
-      // for real protocol chunks {index,text} and looser {delta} shapes
-      // alike); the assembler blocks are a fallback for streams that only
-      // deliver text inside block-end. This dsh-llm exposes no public
-      // no-arg assemble() — blocks() is the message-level API.
-      const blocks = assembler.blocks();
-      const assembledText = blocks
-        .filter((b) => b.type === "text")
-        .map((b) => b.text ?? "")
-        .join("");
+      }, intervalMs);
+      if (aborted) return;
       const entries = parseSummaryJson(text || assembledText);
       for (const entry of entries) {
-        service.saveWithDedupe({ ...entry, source: `session:${session.id}` });
+        // Provenance: the summarizer runs on a real session (turn/end hook), so
+        // session.id is always available here — it rides the human-readable
+        // source label.
+        // 编码记忆类型（codingRetrospect）不带 tag：读取侧门控/加权靠 m.type
+        // （rejected_solution/pitfall/constraint）区分即可，tag 体系
+        // sanitizeTags 不认 `type:` 前缀反而会清空 tags 列（额外一次 UPDATE）。
+        service.saveWithDedupe({
+          ...entry,
+          source: `session:${session.id}`
+        });
       }
     } finally {
       if (audit) {

package/lib/tools.js

@@ -30,7 +30,7 @@ export function createTools(ctx, service, config, embedder) {
         "Call this when the user states a durable preference, a project decision is made, or a lesson is learned. " +
         "Merges into an existing entry of the same type when the title matches.",
       parameters: {
-        type: { type: "string", required: true, enum: ["preference", "project", "decision", "history"], description: "preference=user profile; project=project knowledge/state; decision=key decision; history=conversation summary" },
+        type: { type: "string", required: true, enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "preference=user profile; project=project knowledge/state; decision=key decision; history=conversation summary; rejected_solution=rejected/abandoned implementation approach; pitfall=debugging lesson (symptom+root cause+fix); constraint=engineering constraint" },
         title: { type: "string", required: true, description: "Short unique title" },
         content: { type: "string", required: true, description: "Memory body" },
         tags: { type: "array", items: { type: "string" }, description: "Optional tags" },
@@ -100,7 +100,7 @@ export function createTools(ctx, service, config, embedder) {
       name: "memory_list",
       description: "List memory entries by type, high-importance first, then newest, paginated. Set include_archived=true to also list archived (hidden) entries so they can be located and restored.",
       parameters: {
-        type: { type: "string", enum: ["preference", "project", "decision", "history"], description: "Filter by type; omit for all" },
+        type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "Filter by type; omit for all" },
         limit: { type: "integer", description: "Page size (default 50)" },
         offset: { type: "integer", description: "Page offset (default 0)" },
         include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" }
@@ -138,7 +138,7 @@ export function createTools(ctx, service, config, embedder) {
         id: { type: "string", required: true, description: "Memory id" },
         title: { type: "string" },
         content: { type: "string" },
-        type: { type: "string", enum: ["preference", "project", "decision", "history"] },
+        type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"] },
         tags: { type: "array", items: { type: "string" } },
         importance: { type: "integer", description: "1-5" },
         reason: { type: "string", description: "Optional context for the correction (what the user actually said/wanted), recorded for reflection" }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 7 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,6 +13,9 @@
   },
   "type": "module",
   "main": "lib/index.js",
+  "bin": {
+    "dsh-mneme": "bin/cli.mjs"
+  },
   "exports": {
     ".": {
       "default": "./lib/index.js"
@@ -23,6 +26,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "lib",
     "src",
     "scripts",
@@ -58,12 +62,14 @@
     "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1",
+    "c8": "^12.0.0",
     "lucide": "^1.42.0"
   },
   "scripts": {
     "sync": "node scripts/sync-lib.js",
     "prepack": "npm run sync",
     "test": "node --test test/*.test.js",
+    "test:coverage": "c8 node --test test/*.test.js",
     "e2e": "node scripts/e2e-dsh.js",
     "stress": "node scripts/stress-dsh.js"
   },

package/src/api-standalone.js

@@ -0,0 +1,264 @@
+// Standalone HTTP API (v0.7.12): a plain node:http server for ecosystem
+// integrations that live outside the DSH host and cannot reach the plugin's
+// internal webServer routes (/api/dsh-mneme/*). Mirrors the JSON semantics of
+// those routes but with mandatory Bearer-token auth on everything except
+// GET /health, so the store can be exposed safely on loopback.
+//
+// Security: the default bind host is 127.0.0.1. Pointing externalApiHost at a
+// non-loopback address exposes the whole memory store to the network — that is
+// the operator's explicit responsibility (documented in README).
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { TYPES } from "./store.js";
+
+const DEFAULT_PORT = 8790;
+const DEFAULT_HOST = "127.0.0.1";
+// Hardcoded release version (package.json is bumped at publish time and may
+// lag the code that ships in between).
+const VERSION = "0.7.12";
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(payload));
+}
+
+/** True when the request carries the configured token. */
+function isAuthorized(req, apiToken) {
+  const raw = req.headers?.authorization ?? req.headers?.["x-dsh-mneme-token"] ?? "";
+  const token = raw.startsWith("Bearer ") ? raw.slice(7).trim() : raw.trim();
+  if (token === "" || token.length !== apiToken.length) return false;
+  // Constant-time comparison: no timing oracle on the token.
+  return timingSafeEqual(Buffer.from(token), Buffer.from(apiToken));
+}
+
+/** Collect the request body as text (tolerant of transport errors). */
+function readBody(req) {
+  return new Promise((resolve) => {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => resolve(body));
+    req.on("error", () => resolve(""));
+  });
+}
+
+/**
+ * Create (and start) the standalone API server.
+ * Accepts { service, store, config, logger, settings, port, host }:
+ *   - token: persisted settings kv "external_api" wins; auto-generated
+ *     (crypto.randomBytes(24).toString("base64url")) and persisted when empty.
+ *   - port:  explicit arg > persisted settings > config.externalApiPort > 8790.
+ *   - host:  explicit arg > config.externalApiHost > "127.0.0.1".
+ * Returns { server, port, host, token, ready }: `port` is the effective bound
+ * port (updated to the OS-assigned one after `ready` resolves when asked to
+ * bind port 0), `ready` resolves once listening and rejects if the bind fails.
+ */
+export function createStandaloneApi({ service, store, config = {}, logger, settings, port, host }) {
+  const persisted = settings?.getExternalApi?.() ?? {};
+
+  let token = typeof persisted.token === "string" ? persisted.token : "";
+  if (!token) {
+    token = randomBytes(24).toString("base64url");
+    // Persist only the token; enabled/port keys stay as they are (merge).
+    try {
+      settings?.setExternalApi?.({ token });
+    } catch (error) {
+      logger?.warn?.(`[dsh-mneme] standalone API token persistence failed: ${String(error)}`);
+    }
+  }
+
+  // Persisted host (set from the panel) wins over the bundle config, same
+  // precedence as port; the explicit argument still wins over both.
+  const boundHost = host
+    ?? (typeof persisted.host === "string" && persisted.host ? persisted.host : undefined)
+    ?? config.externalApiHost
+    ?? DEFAULT_HOST;
+  const persistedPort = Number(persisted.port);
+  const boundPort = port
+    ?? (Number.isInteger(persistedPort) && persistedPort > 0 ? persistedPort : undefined)
+    ?? config.externalApiPort
+    ?? DEFAULT_PORT;
+
+  const server = createServer((req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const pathname = url.pathname;
+
+      // Health is the single unauthenticated probe (monitor checks).
+      if (req.method === "GET" && pathname === "/health") {
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+
+      // Everything else requires the Bearer token.
+      if (!isAuthorized(req, token)) {
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+      }
+
+      // --- GET /status: version + store shape + uptime -----------------------
+      if (req.method === "GET" && pathname === "/status") {
+        const byType = {};
+        for (const type of TYPES) byType[type] = service.count(type);
+        let entities = 0;
+        try {
+          entities = store.db.prepare("SELECT count(*) AS c FROM entities").get().c;
+        } catch { /* entities storage unavailable → 0 */ }
+        sendJson(res, 200, {
+          version: VERSION,
+          memories: { total: service.count(), byType },
+          entities,
+          uptime_s: Math.floor(process.uptime())
+        });
+        return;
+      }
+
+      // --- GET /memories: paged + filtered list (same semantics as the
+      //     internal /api/dsh-mneme/list) ------------------------------------
+      if (req.method === "GET" && pathname === "/memories") {
+        const type = url.searchParams.get("type") ?? undefined;
+        const limit = Number(url.searchParams.get("limit") ?? 50);
+        const offset = Number(url.searchParams.get("offset") ?? 0);
+        const order = url.searchParams.get("order") ?? undefined;
+        const minRaw = url.searchParams.get("minImportance");
+        const minImportance = minRaw !== null && minRaw !== "" && !Number.isNaN(Number(minRaw))
+          ? Number(minRaw)
+          : undefined;
+        const source = url.searchParams.get("source") || undefined;
+        const items = service.toApiList(service.list({ type, limit, offset, order, minImportance, source }));
+        // Total honors the same filters so pager math stays correct.
+        sendJson(res, 200, { items, total: service.count(type, { minImportance, source }) });
+        return;
+      }
+
+      // --- GET/DELETE /memories/:id ------------------------------------------
+      const idMatch = pathname.match(/^\/memories\/([^/]+)$/);
+      if (idMatch) {
+        let id = idMatch[1];
+        try { id = decodeURIComponent(id); } catch { /* keep raw */ }
+        if (req.method === "GET") {
+          const row = service.getById(id);
+          if (!row) {
+            sendJson(res, 404, { error: "not-found" });
+            return;
+          }
+          sendJson(res, 200, service.toApiList([row])[0]);
+          return;
+        }
+        if (req.method === "DELETE") {
+          // store.remove deletes silently — precheck for a distinguishable 404.
+          if (!service.getById(id)) {
+            sendJson(res, 404, { error: "not-found" });
+            return;
+          }
+          service.remove(id);
+          sendJson(res, 200, { ok: true });
+          return;
+        }
+        sendJson(res, 404, { error: "not-found" });
+        return;
+      }
+
+      // --- POST /memories: save with title-dedupe (safer than raw save) ------
+      if (req.method === "POST" && pathname === "/memories") {
+        void readBody(req).then((text) => {
+          let body;
+          try {
+            body = JSON.parse(text || "{}");
+          } catch {
+            sendJson(res, 400, { error: "invalid-json" });
+            return;
+          }
+          if (body === null || typeof body !== "object" || Array.isArray(body)) {
+            sendJson(res, 400, { error: "invalid-body" });
+            return;
+          }
+          // Pre-validate what store.save would throw on, so clients get a
+          // clean 400 instead of a leaked SQLite error.
+          if (!TYPES.has(body.type)) {
+            sendJson(res, 400, { error: "invalid-type" });
+            return;
+          }
+          if (typeof body.title !== "string" || !body.title.trim()) {
+            sendJson(res, 400, { error: "missing-title" });
+            return;
+          }
+          if (typeof body.content !== "string") {
+            sendJson(res, 400, { error: "missing-content" });
+            return;
+          }
+          if (body.tags !== undefined && !Array.isArray(body.tags)) {
+            sendJson(res, 400, { error: "tags-must-be-an-array" });
+            return;
+          }
+          try {
+            const { action, memory } = service.saveWithDedupe({
+              type: body.type,
+              title: body.title,
+              content: body.content,
+              importance: body.importance,
+              tags: body.tags,
+              source: body.source
+            });
+            sendJson(res, action === "created" ? 201 : 200, service.toApiList([memory])[0]);
+          } catch (error) {
+            logger?.warn?.(`[dsh-mneme] standalone API save failed: ${String(error)}`);
+            sendJson(res, 500, { error: "internal" });
+          }
+        });
+        return;
+      }
+
+      // --- GET /search: unified recall pipeline (keyword + vector + BM25) ----
+      if (req.method === "GET" && pathname === "/search") {
+        const q = url.searchParams.get("q") ?? "";
+        const limit = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20);
+        const mode = url.searchParams.get("mode") ?? "auto";
+        const rerank = url.searchParams.get("rerank") !== "false";
+        const query = q.trim();
+        if (!query) {
+          sendJson(res, 200, { items: [], mode: "keyword" });
+          return;
+        }
+        // Any vector/rerank failure degrades to keyword inside searchMemories.
+        void Promise.resolve(
+          service.searchMemories(query, { mode, topK: limit, useRerank: rerank })
+        ).then((rows) => {
+          const used = rows.some((m) => m.vector === true) ? "vector" : "keyword";
+          sendJson(res, 200, { items: service.toApiList(rows), mode: used });
+        }).catch(() => {
+          sendJson(res, 200, { items: service.toApiList(service.search(query, { limit })), mode: "keyword" });
+        });
+        return;
+      }
+
+      sendJson(res, 404, { error: "not-found" });
+    } catch {
+      sendJson(res, 500, { error: "internal" });
+    }
+  });
+
+  // A permanent error listener keeps an EADDRINUSE / runtime socket error from
+  // crashing the host process; `ready` still surfaces the first bind failure.
+  server.on("error", (error) => {
+    logger?.warn?.(`[dsh-mneme] standalone API error: ${String(error)}`);
+  });
+  const ready = new Promise((resolve, reject) => {
+    server.once("listening", resolve);
+    server.once("error", reject);
+  });
+  server.listen(boundPort, boundHost);
+  ready.then(() => {
+    const address = server.address();
+    if (address && typeof address === "object") {
+      logger?.info?.(`[dsh-mneme] standalone API listening on http://${address.address}:${address.port}`);
+    }
+  }).catch(() => { /* already logged by the error handler above */ });
+
+  const api = { server, port: boundPort, host: boundHost, token, ready };
+  // After the OS assigns the real port (bind port 0), reflect it for callers.
+  ready.then(() => {
+    const address = server.address();
+    if (address && typeof address === "object") api.port = address.port;
+  }).catch(() => { /* bind failed: port stays as configured */ });
+  return api;
+}