@modusensus/dsh-mneme 0.7.5 → 0.7.7

package/dsh-mneme/src/config.js

@@ -274,6 +274,15 @@ export const Config = z.object({
     z.const("high"),
     z.const("none")
   ]).default("none"),
+  // Batch entity extraction during sleep (issue #23). The write-path extractor
+  // only fires when entityExtractionEnabled is on (an LLM call per write);
+  // this additive phase backfills entities/attrs/relations for memories that
+  // never went through it, so stores that leave the write-path extractor off
+  // still accumulate an ego graph as long as sleep runs. On by default (it is
+  // a no-op until a sleep cycle fires), capped per run to bound token spend.
+  sleepEntityExtractionEnabled: z.boolean().default(true),
+  // Max memories entity-extracted per sleep run (oldest un-extracted first).
+  sleepEntityExtractionMaxPerRun: z.natural().min(1).max(100).default(20),
 
   // --- epistemic trust: memory source credibility (v0.4.5) -----------------
   // Distinguish memories by source: observation (measured / witnessed),

package/dsh-mneme/src/dream/sleep.js

@@ -19,6 +19,7 @@ import { validateDecisions, applyDecisions } from "./decisions.js";
 import { findPotentialConflicts } from "./clustering.js";
 import { buildReceipt } from "../dream.js";
 import { computeHeat } from "../heat.js";
+import { extractEntities } from "../entities/extractor.js";
 
 const SUMMARY_MAX = 120;
 // Conflict similarity threshold per strictness level (v0.4.0):
@@ -396,6 +397,123 @@ function phaseRelations(service, config, logger, runId, signal = null) {
   };
 }
 
+/**
+ * Phase 4.5 — batch entity extraction. The write-path extractor (index.js)
+ * only fires when entityExtractionEnabled is on — one LLM call per write, a
+ * deliberate cost decision — so default installs never accumulate entities,
+ * which is exactly why the ego-graph panel (issue #23) renders blank for users
+ * with plenty of memories. This phase backfills the entity graph in bulk:
+ * memories that carry no entity attrs yet are passed through extractEntities
+ * one at a time (oldest first, capped per run). Write-path stays untouched —
+ * this is an additive channel for sleep users. Fail-safe per memory: one bad
+ * extract never aborts the phase or the cycle.
+ */
+async function phaseEntityExtraction(ctx, service, config, logger, runId, signal = null) {
+  if (config.sleepEntityExtractionEnabled !== true) {
+    return { status: "skipped", reason: "disabled" };
+  }
+  const route = resolveSleepRoute(ctx, config, logger);
+  if (!route) return { status: "skipped", reason: "no llm route" };
+  const maxPerRun = config.sleepEntityExtractionMaxPerRun ?? 20;
+
+  // Oldest un-extracted first. The store returns bounded pages via SQL (no
+  // O(N) full-table scan); JS pages through offsets and only pays the
+  // getAttrsByMemory cross-table check on each page, stopping once it has
+  // maxPerRun un-extracted memories or the store is exhausted. Every memory
+  // this phase touches gets stamped entity_extracted_at (successful or
+  // entity-less extracts alike) so a text with no extractable entities is not
+  // re-queued forever; failures are NOT stamped, so a transient LLM hiccup
+  // retries next cycle.
+  const candidates = [];
+  for (let offset = 0; candidates.length < maxPerRun; offset += 100) {
+    const page = service.listForEntityExtraction({ limit: 100, offset });
+    if (page.length === 0) break;
+    candidates.push(...page.filter((m) => (service.getAttrsByMemory?.(m.id) ?? []).length === 0));
+  }
+  candidates.length = Math.min(candidates.length, maxPerRun);
+  if (candidates.length === 0) return { status: "skipped", reason: "no memories to extract" };
+  if (signal?.aborted) return { status: "aborted", reason: "user activity" };
+
+  // extractEntities expects callLLM(messages, options) → text; adapt sleep's
+  // streamText + route resolution (same precedence as the other phases).
+  const callLLM = async (messages) => {
+    const r = resolveSleepRoute(ctx, config, logger);
+    if (!r) return undefined;
+    return streamText(ctx, {
+      ...r,
+      purpose: "sleep-entity-extract",
+      maxTokens: 4096,
+      ...(config.sleepReasoningEffort && config.sleepReasoningEffort !== "none"
+        ? { reasoningEffort: config.sleepReasoningEffort }
+        : {}),
+      messages
+    });
+  };
+
+  let extracted = 0;
+  let failed = 0;
+  let aborted = false;
+  const extractedIds = [];
+  for (const m of candidates) {
+    if (signal?.aborted) {
+      aborted = true;
+      break;
+    }
+    const now = new Date().toISOString();
+    try {
+      // Stamp a pending marker BEFORE the LLM call so a crash mid-extract (the
+      // stamp and the entity writes are not one transaction) cannot re-queue
+      // this memory while we are already working it. Cleared on outcome.
+      service.setMemoryMetadata?.(m.id, { pending_extracted_at: now });
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme sleep: failed to stamp pending_extracted_at for ${m.id}: ${String(error)}`);
+      failed++;
+      continue;
+    }
+    try {
+      const result = await extractEntities(m, { store: service, config, callLLM, logger });
+      if (result?.ok) {
+        extracted++;
+        extractedIds.push(m.id);
+        // Stamp done regardless of whether the LLM found entities — an empty
+        // extract is still a definitive answer for this memory.
+        try {
+          service.setMemoryMetadata?.(m.id, { entity_extracted_at: now, pending_extracted_at: null });
+        } catch (error) {
+          logger?.warn?.(`dsh-mneme sleep: failed to stamp entity_extracted_at for ${m.id}: ${String(error)}`);
+        }
+      } else {
+        failed++;
+        logger?.warn?.(`dsh-mneme sleep: entity extraction failed for ${m.id}: ${result?.error ?? "unknown"}`);
+        try {
+          service.setMemoryMetadata?.(m.id, { pending_extracted_at: null });
+        } catch (error) {
+          logger?.warn?.(`dsh-mneme sleep: failed to clear pending_extracted_at for ${m.id}: ${String(error)}`);
+        }
+      }
+    } catch (error) {
+      failed++;
+      logger?.warn?.(`dsh-mneme sleep: entity extraction threw for ${m.id}: ${String(error)}`);
+      try {
+        service.setMemoryMetadata?.(m.id, { pending_extracted_at: null });
+      } catch (err) {
+        logger?.warn?.(`dsh-mneme sleep: failed to clear pending_extracted_at for ${m.id}: ${String(err)}`);
+      }
+    }
+  }
+  return {
+    // Any success counts as ok (failures are surfaced via detail.failed + warn,
+    // matching phaseConflicts); all-failed reports failed so deriveStatus can
+    // reflect a broken route without aborting the other phases.
+    status: aborted ? "aborted" : extracted > 0 ? "ok" : failed > 0 ? "failed" : "noop",
+    scanned: candidates.length,
+    extracted,
+    failed,
+    aborted,
+    extractedIds
+  };
+}
+
 // ---------------------------------------------------------------- run
 
 function deriveStatus(phases) {
@@ -429,6 +547,9 @@ export async function runSleep(ctx, service, config, logger, semantic = null, si
   await attempt("conflicts", () => phaseConflicts(ctx, service, config, logger, runId, semantic, signal));
   await attempt("demotion", () => phaseDemotion(service, config, logger, runId, signal));
   await attempt("patterns", () => phasePatterns(ctx, service, config, logger, runId, signal));
+  // entity-extraction runs before relation completion so freshly minted
+  // entities get their orphan relations completed in the same cycle.
+  await attempt("entity-extraction", () => phaseEntityExtraction(ctx, service, config, logger, runId, signal));
   await attempt("relations", () => phaseRelations(service, config, logger, runId, signal));
 
   const status = deriveStatus(phases);

package/dsh-mneme/src/service.js

@@ -1608,9 +1608,48 @@ export function createService({ store, mirror, config, onWrite, logger, settings
     embeddedCount: () => store.embeddedCount(),
     list: (o) => store.list(o),
     all: () => store.all(),
+    listForEntityExtraction: (opts) => store.listForEntityExtraction(opts),
     count: (type, opts) => store.count(type, opts),
     stats: (opts) => store.stats(opts),
     getById: (id) => store.getById(id),
+    // issue #48: resolve a possibly-truncated id to its canonical full id.
+    // Exact hit wins; otherwise the input is treated as a prefix of the id
+    // PRIMARY KEY. Never guesses on ambiguity — returns the candidates and the
+    // caller must pass a full id. Outcome is {ok:true,id} or {ok:false,reason,
+    // message} with reason ∈ invalid | not-found | ambiguous. warnMiss logs the
+    // silent-miss case the delete tool previously swallowed (no return channel
+    // for it, so observability has to live here in the service layer).
+    resolveMemoryId: (input, { warnMiss = false } = {}) => {
+      const bad = (reason, message) => ({ ok: false, reason, message });
+      if (typeof input !== "string") return bad("invalid", "memory id is required");
+      // 手抄/上下文压缩来的 id 可能带首尾空白，统一 trim 后再做精确与前缀解析。
+      const id = input.trim();
+      if (!id) return bad("invalid", "memory id is required");
+      const exact = store.getById(id);
+      if (exact) return { ok: true, id: exact.id };
+      const matches = store.listByIdPrefix(id);
+      if (matches.length === 0) {
+        if (warnMiss) {
+          logger?.warn?.(
+            `[dsh-mneme] memory id "${id}" matched nothing (exact or prefix) — ` +
+            "no entry was deleted; ids are full-length, pass one from memory_list/memory_search output or delete by query=…"
+          );
+        }
+        return bad(
+          "not-found",
+          `memory not found: ${id} (checked exact id and prefix; use a full id from memory_list/memory_search output)`
+        );
+      }
+      if (matches.length > 1) {
+        const sample = matches.slice(0, 5).map((m) => m.id);
+        const tail = matches.length > sample.length ? ` …(+${matches.length - sample.length})` : "";
+        return bad(
+          "ambiguous",
+          `memory id prefix "${id}" matches ${matches.length} entries (${sample.join(", ")}${tail}); refusing to guess — pass a full id`
+        );
+      }
+      return { ok: true, id: matches[0].id };
+    },
     remove: (id) => {
       store.remove(id);
       afterSync("write");
@@ -1824,9 +1863,11 @@ export function createService({ store, mirror, config, onWrite, logger, settings
     applyMemoryTags: (memoryId, tags) => store.setMemoryTags(memoryId, tags),
     saveAttr: (r) => store.saveAttr(r),
     createEntity: (r) => store.createEntity(r),
+    updateEntity: (id, patch) => store.updateEntity(id, patch),
     findEntityByName: (n) => store.findEntityByName(n),
     findEntityById: (id) => store.findEntityById(id),
     getAttrsByMemory: (id) => store.getAttrsByMemory(id),
+    setMemoryMetadata: (id, metadata) => store.setMemoryMetadata(id, metadata),
     getCurrentAttrs: (id) => store.getCurrentAttrs(id),
     migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };

package/dsh-mneme/src/store.js

@@ -20,6 +20,7 @@ CREATE TABLE IF NOT EXISTS memories (
   epistemic_status TEXT NOT NULL DEFAULT 'subjective',
   last_accessed_at  TEXT,
   _full_content     TEXT,
+  metadata    TEXT,               -- JSON: free-form extras (e.g. sleep entity_extracted_at)
   created_at  TEXT NOT NULL,
   updated_at  TEXT NOT NULL
 );
@@ -314,6 +315,14 @@ function parseTags(raw) {
 
 function toRow(row) {
   if (!row) return undefined;
+  let metadata;
+  if (row.metadata != null) {
+    try {
+      metadata = JSON.parse(row.metadata);
+    } catch {
+      metadata = row.metadata;
+    }
+  }
   return {
     id: row.id,
     type: row.type,
@@ -329,6 +338,7 @@ function toRow(row) {
     content_history: parseJsonArray(row.content_history),
     quality_score: row.quality_score !== null && row.quality_score !== undefined ? Number(row.quality_score) : undefined,
     epistemic_status: row.epistemic_status ?? "subjective",
+    metadata,
     created_at: row.created_at,
     updated_at: row.updated_at,
     last_accessed_at: row.last_accessed_at ?? undefined,
@@ -589,6 +599,7 @@ export function createStore(path) {
   addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
   addColumn("memories", "session_id", "ALTER TABLE memories ADD COLUMN session_id TEXT");
+  addColumn("memories", "metadata", "ALTER TABLE memories ADD COLUMN metadata TEXT");
 
   // Composite index for session-lifecycle queries (dispose/restore/listBySession).
   // Created post-migration, NOT in SCHEMA: on legacy DBs both columns arrive via
@@ -697,6 +708,27 @@ export function createStore(path) {
     return toRow(row);
   }
 
+  /**
+   * issue #48: resolve a truncated id — as can leak through an agent's context
+   * window when list/search output is shortened — by matching it as a prefix of
+   * the id PRIMARY KEY. Exact lookups keep using getById; this only serves
+   * resolving a *candidate* id. Returns up to 51 rows so the caller can tell
+   * "unique" from "ambiguous" without a second query. LIKE wildcards are
+   * stripped from the input (a valid id fragment is hex/UUID text, never % or
+   * _). Prefix over a PK stays an index scan, so this is cheap even at scale.
+   */
+  function listByIdPrefix(idPrefix) {
+    if (typeof idPrefix !== "string" || !idPrefix.trim()) return [];
+    // LIKE 通配符不参与 id 匹配，一律剥掉。若剥完为空（如 id="%"），
+    // 不能让 SQL 退化成 `LIKE '%'` 全表命中——那会让单条记忆被误删，
+    // 一律视为无匹配返回。
+    const safe = idPrefix.replace(/[\\%_]/g, "");
+    if (!safe) return [];
+    const rows = db.prepare("SELECT * FROM memories WHERE id LIKE ? LIMIT 51")
+      .all(`${safe}%`);
+    return rows.map(toRow);
+  }
+
   /**
    * Case-insensitive exact title lookup (v0.6.1 wiki-link). COLLATE NOCASE
    * folds ASCII case (CJK titles are inherently case-free, so they match
@@ -813,6 +845,50 @@ export function createStore(path) {
     });
   }
 
+  /**
+   * Bounded scan for sleep's entity-extraction phase: oldest memories without
+   * an entity_extracted_at stamp (row-level filters only — attr presence is a
+   * cross-table check, so the caller filters the returned page via
+   * getAttrsByMemory). Caller pages with {limit, offset}; a full-table scan +
+   * JS filter would be O(N) per sleep cycle.
+   */
+  function listForEntityExtraction({ limit = 50, offset = 0 } = {}) {
+    // node:sqlite has no StatementSync#pluck; all() returns row objects.
+    return db
+      .prepare(`
+        SELECT id FROM memories
+        WHERE (archived = 0 OR archived IS NULL)
+          AND session_disposed_at IS NULL
+          AND (forgotten = 0 OR forgotten IS NULL)
+          AND type != 'summary'
+          AND content IS NOT NULL AND content != ''
+          AND (metadata IS NULL OR json_extract(metadata, '$.entity_extracted_at') IS NULL)
+        ORDER BY created_at ASC
+        LIMIT ? OFFSET ?
+      `)
+      .all(limit, offset)
+      .map((row) => getById(row.id));
+  }
+
+  /**
+   * Lightweight metadata-only update (used by sleep's batch entity extraction
+   * to stamp `entity_extracted_at` without disturbing title/content/embedding
+   * or the normal update semantics). Does not bump updated_at — metadata
+   * stamps are bookkeeping, not content, so they must not fake freshness.
+   * Incoming fields are MERGED into the existing metadata object so a stamp
+   * never clobbers metadata another path just wrote.
+   */
+  function setMemoryMetadata(id, metadata) {
+    const existing = getById(id);
+    if (!existing) throw new Error(`memory not found: ${id}`);
+    const patch = typeof metadata === "string"
+      ? JSON.parse(metadata)
+      : (metadata ?? {});
+    const merged = { ...(existing.metadata ?? {}), ...patch };
+    db.prepare("UPDATE memories SET metadata = ? WHERE id = ?").run(JSON.stringify(merged), id);
+    return getById(id);
+  }
+
   /**
    * Atomic compare-and-set update: applies `patch` only when the row still
    * carries `expectedUpdatedAt` (the version token read by the caller). Returns
@@ -2210,8 +2286,11 @@ export function createStore(path) {
     count,
     stats,
     getById,
+    listByIdPrefix,
     save,
     update,
+    listForEntityExtraction,
+    setMemoryMetadata,
     compareAndUpdate,
     remove,
     setForget,

package/dsh-mneme/src/tools.js

@@ -302,7 +302,7 @@ export function createTools(ctx, service, config, embedder) {
       name: "memory_update",
       description: "Modify an existing memory entry (title, content, type, tags, importance).",
       parameters: {
-        id: { type: "string", required: true, description: "Memory id" },
+        id: { type: "string", required: true, description: "Memory id (full id from memory_list/memory_search output, or a unique prefix of it)" },
         title: { type: "string" },
         content: { type: "string" },
         type: { type: "string", enum: ["preference", "project", "decision", "history", "user", "fact"] },
@@ -329,7 +329,9 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`Updated memory ${value.memory.id}: ${value.memory.title}`)
       },
       async execute(args) {
-        const memory = service.update(args.id, {
+        const resolved = service.resolveMemoryId(args.id);
+        if (!resolved.ok) throw new Error(resolved.message);
+        const memory = service.update(resolved.id, {
           title: args.title,
           content: args.content,
           type: args.type,
@@ -342,9 +344,9 @@ export function createTools(ctx, service, config, embedder) {
 
     defineTool({
       name: "memory_delete",
-      description: "Permanently delete a memory entry. Pass id for exact delete, or query to delete the single best-matching entry by text — lets the agent honor 'delete the memory about X' without a prior list/search round trip.",
+      description: "Permanently delete a memory entry. Pass id for exact delete (full id, or a unique prefix of it — ambiguous prefixes are rejected), or query to delete the single best-matching entry by text — lets the agent honor 'delete the memory about X' without a prior list/search round trip. An id that matches nothing is logged as a warning instead of failing silently.",
       parameters: {
-        id: { type: "string", description: "Exact memory id to delete (from memory_list/memory_search output)" },
+        id: { type: "string", description: "Memory id to delete: full id (from memory_list/memory_search output) or a unique prefix of it; a miss is logged (warn) and returns deleted:false" },
         query: { type: "string", description: "Delete the best-matching entry for this text (searches title/content/tags; uses hybrid recall when an embedder is configured)" }
       },
       output: {
@@ -353,13 +355,19 @@ export function createTools(ctx, service, config, embedder) {
           additionalProperties: false,
           properties: { deleted: { type: "boolean", required: true } }
         },
-        render: (_args, value) => TEXT_OUTPUT(value.deleted ? "Memory deleted." : "Memory not found.")
+        render: (_args, value) => TEXT_OUTPUT(value.deleted
+          ? "Memory deleted."
+          : "Memory not found — nothing was deleted. Pass a full id (or a unique prefix) from memory_list/memory_search output, or delete by query=… instead.")
       },
       async execute(args) {
         if (args.id) {
-          const existed = service.getById(args.id) !== undefined;
-          if (existed) service.remove(args.id);
-          return { deleted: existed };
+          const resolved = service.resolveMemoryId(args.id, { warnMiss: true });
+          if (!resolved.ok) {
+            if (resolved.reason === "ambiguous") throw new Error(resolved.message);
+            return { deleted: false };
+          }
+          service.remove(resolved.id);
+          return { deleted: true };
         }
         if (args.query) {
           const [best] = await service.searchMemories(args.query, { mode: "auto", topK: 1, useRerank: true });
@@ -378,7 +386,7 @@ export function createTools(ctx, service, config, embedder) {
         "Stop a memory from being auto-injected and from appearing in searches and lists without deleting it. " +
         "The entry stays in storage; pass forgotten: false to restore it.",
       parameters: {
-        id: { type: "string", required: true },
+        id: { type: "string", required: true, description: "Memory id: full id (from memory_list/memory_search output) or a unique prefix of it; ambiguous prefixes are rejected" },
         forgotten: { type: "boolean", description: "Suppress (true, default) or restore (false) the entry's visibility" }
       },
       output: {
@@ -399,10 +407,9 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`Memory ${value.memory.id} injection ${value.memory.forgotten ? "suppressed" : "restored"}.`)
       },
       async execute(args) {
-        if (service.getById(args.id) === undefined) {
-          throw new Error("memory not found");
-        }
-        const memory = service.setForget(args.id, args.forgotten ?? true);
+        const resolved = service.resolveMemoryId(args.id);
+        if (!resolved.ok) throw new Error(resolved.message);
+        const memory = service.setForget(resolved.id, args.forgotten ?? true);
         return { memory: { id: memory.id, forgotten: memory.forgotten } };
       }
     }),
@@ -414,7 +421,7 @@ export function createTools(ctx, service, config, embedder) {
         "Archived entries stay in storage and are recoverable: pass archived=false to restore, and use memory_list with " +
         "include_archived=true to find archived entries.",
       parameters: {
-        id: { type: "string", required: true, description: "Memory id" },
+        id: { type: "string", required: true, description: "Memory id: full id (from memory_list/memory_search output) or a unique prefix of it; ambiguous prefixes are rejected" },
         archived: { type: "boolean", description: "Archive (true, default) or restore (false) the entry" }
       },
       output: {
@@ -435,10 +442,9 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`Memory ${value.memory.id} ${value.memory.archived ? "archived" : "restored"}.`)
       },
       async execute(args) {
-        if (service.getById(args.id) === undefined) {
-          throw new Error("memory not found");
-        }
-        const memory = service.setArchived(args.id, args.archived ?? true);
+        const resolved = service.resolveMemoryId(args.id);
+        if (!resolved.ok) throw new Error(resolved.message);
+        const memory = service.setArchived(resolved.id, args.archived ?? true);
         return { memory: { id: memory.id, archived: memory.archived } };
       }
     })

package/dsh-mneme/test/client.test.js

@@ -5,7 +5,9 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
-const clientSource = readFileSync(join(root, "lib/client.js"), "utf8");
+// src/ is the single source of truth for every module (including the Web
+// client bundle); lib/ is build output produced by `npm run sync`.
+const clientSource = readFileSync(join(root, "src/client.js"), "utf8");
 const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
 
 // The Web client bundle registers itself via __ModuleLoader__.load. DSH
@@ -18,11 +20,14 @@ test("client bundle registers under the package name", () => {
   assert.equal(match[1], pkg.name, "registered id must equal package.json name");
 });
 
-// client.js is hand-authored under lib/ only (no src/ counterpart), so the
-// src->lib sync must never prune it.
-test("client bundle is lib-only with no src counterpart", () => {
-  assert.equal(existsSync(join(root, "src/client.js")), false, "src/ must not contain client.js");
+// client.js is authored under src/ like every other module; lib/client.js is
+// build output generated by `npm run sync` (prepack), so it must stay a
+// byte-identical copy — drift here means the sync wasn't run.
+test("client bundle is src-authored and synced into lib", () => {
+  assert.equal(existsSync(join(root, "src/client.js")), true, "src/client.js must exist");
   assert.equal(existsSync(join(root, "lib/client.js")), true, "lib/client.js must exist");
+  const libClient = readFileSync(join(root, "lib/client.js"), "utf8");
+  assert.equal(libClient, clientSource, "lib/client.js must equal src/client.js (run `npm run sync`)");
 });
 
 // The memory entry lives at the sidebar foot, not in the settings modal: the

package/dsh-mneme/test/sleep.test.js

@@ -371,3 +371,162 @@ test("sleep: runSleep is abortable via signal between phases", async () => {
   assert.equal(result.phases.conflicts, undefined, "aborted before any phase ran");
   store.close();
 });
+
+// ------------------------------------------------ entity extraction (issue #23)
+
+// Write-path extractor is gated on entityExtractionEnabled (default off), so
+// default installs never accumulate entities → ego-graph panel blank. This
+// sleep phase backfills it; these tests cover gating, idempotence and
+// fail-safe batching.
+const ENTITY_LLM_JSON = JSON.stringify({
+  entities: [{ name: "X", type: "concept", attrs: [{ key: "k", value: "v" }] }],
+  relations: []
+});
+
+test("sleep: entity extraction skips when disabled", async () => {
+  const { service, store } = setup();
+  makeMemory(service, "记忆A", "内容A", "history");
+  const ctx = mockCtx(() => ENTITY_LLM_JSON, { provider: "p", model: "m" });
+  const result = await runSleep(
+    ctx, service,
+    baseConfig({ sleepEntityExtractionEnabled: false }),
+    ctx.logger, null, null
+  );
+  assert.equal(result.phases["entity-extraction"].status, "skipped", "disabled → skipped");
+  store.close();
+});
+
+test("sleep: extracted memories are stamped and not re-extracted", async () => {
+  const { service, store } = setup();
+  const mem = makeMemory(service, "记忆B", "内容B", "history");
+  const ctx = mockCtx(() => ENTITY_LLM_JSON, { provider: "p", model: "m" });
+  const config = baseConfig({ sleepEntityExtractionEnabled: true });
+  // First cycle backfills → memory gets entity_extracted_at stamped.
+  const first = await runSleep(ctx, service, config, ctx.logger, null, null);
+  assert.equal(first.phases["entity-extraction"].status, "ok", "first cycle extracts");
+  assert.ok(service.getById(mem.id).metadata?.entity_extracted_at, "stamp written");
+  // Second cycle has nothing un-stamped left → skipped.
+  const second = await runSleep(ctx, service, config, ctx.logger, null, null);
+  assert.equal(second.phases["entity-extraction"].status, "skipped", "nothing left to extract");
+  store.close();
+});
+
+test("sleep: entity-less extracts are stamped so they are not re-queued forever", async () => {
+  const { service, store } = setup();
+  const mem = makeMemory(service, "无实体记忆", "这里没有任何实体", "history");
+  // LLM legitimately returns no entities — must still be stamped, else every
+  // sleep cycle re-extracts the same text forever (issue #23 regression).
+  const ctx = mockCtx(() => JSON.stringify({ entities: [], relations: [] }), { provider: "p", model: "m" });
+  const config = baseConfig({ sleepEntityExtractionEnabled: true });
+  const first = await runSleep(ctx, service, config, ctx.logger, null, null);
+  assert.equal(first.phases["entity-extraction"].status, "ok", "empty extract counts as handled");
+  assert.equal(first.phases["entity-extraction"].extracted, 1);
+  assert.ok(service.getById(mem.id).metadata?.entity_extracted_at, "stamp written even with no entities");
+  const second = await runSleep(ctx, service, config, ctx.logger, null, null);
+  assert.equal(second.phases["entity-extraction"].status, "skipped", "stamped → not re-queued");
+  store.close();
+});
+
+test("sleep: entity extraction backfills entities for un-extracted memories", async () => {
+  const { service, store } = setup();
+  const mem = makeMemory(service, "记忆C", "内容C", "history");
+  const ctx = mockCtx(() => ENTITY_LLM_JSON, { provider: "p", model: "m" });
+  const result = await runSleep(
+    ctx, service,
+    baseConfig({ sleepEntityExtractionEnabled: true }),
+    ctx.logger, null, null
+  );
+  const phase = result.phases["entity-extraction"];
+  assert.equal(phase.status, "ok");
+  assert.equal(phase.extracted, 1);
+  assert.ok(store.listEntities().length > 0, "entity minted");
+  assert.ok(service.getAttrsByMemory(mem.id).length > 0, "memory now carries entity attrs");
+  store.close();
+});
+
+test("sleep: a failing extraction does not abort the batch and retries next cycle", async () => {
+  const { service, store } = setup();
+  const bad = makeMemory(service, "坏记忆", "bad 内容", "history");
+  const good = makeMemory(service, "好记忆", "good 内容", "history");
+  const ctx = mockCtx(
+    (user) => (String(user).includes("bad") ? "这不是合法JSON{{{" : ENTITY_LLM_JSON),
+    { provider: "p", model: "m" }
+  );
+  const config = baseConfig({ sleepEntityExtractionEnabled: true });
+  const first = await runSleep(ctx, service, config, ctx.logger, null, null);
+  const phase = first.phases["entity-extraction"];
+  assert.equal(phase.extracted, 1, "good memory extracted");
+  assert.equal(phase.failed, 1, "bad memory counted as failed");
+  assert.equal(phase.status, "ok", "partial success is ok");
+  assert.ok(store.listEntities().length > 0, "at least one entity minted");
+  // Good memory stamped; bad one not → second cycle retries only the bad one.
+  assert.ok(service.getById(good.id).metadata?.entity_extracted_at, "good memory stamped");
+  assert.equal(service.getById(bad.id).metadata?.entity_extracted_at, undefined, "failed memory not stamped");
+  const second = await runSleep(ctx, service, config, ctx.logger, null, null);
+  assert.equal(second.phases["entity-extraction"].extracted, 0, "bad memory still fails");
+  assert.equal(second.phases["entity-extraction"].failed, 1, "failed memory retried");
+  store.close();
+});
+
+test("sleep: metadata merge keeps unrelated fields when stamping (review #4)", async () => {
+  const { service, store } = setup();
+  const mem = makeMemory(service, "记忆M", "内容M", "history");
+  service.setMemoryMetadata(mem.id, { custom_flag: "keep-me" });
+  const ctx = mockCtx(() => ENTITY_LLM_JSON, { provider: "p", model: "m" });
+  await runSleep(ctx, service, baseConfig({ sleepEntityExtractionEnabled: true }), ctx.logger, null, null);
+  const meta = service.getById(mem.id).metadata;
+  assert.equal(meta.custom_flag, "keep-me", "pre-existing metadata not clobbered");
+  assert.ok(meta.entity_extracted_at, "stamp added alongside");
+  store.close();
+});
+
+test("sleep: pending_extracted_at is cleared on success and on failure (review #3)", async () => {
+  const { service, store } = setup();
+  const good = makeMemory(service, "好记忆", "内容G", "history");
+  const bad = makeMemory(service, "坏记忆", "bad 内容", "history");
+  const ctx = mockCtx(
+    (user) => (String(user).includes("bad") ? "不是JSON{{{" : ENTITY_LLM_JSON),
+    { provider: "p", model: "m" }
+  );
+  const config = baseConfig({ sleepEntityExtractionEnabled: true });
+  const first = await runSleep(ctx, service, config, ctx.logger, null, null);
+  const phase = first.phases["entity-extraction"];
+  assert.equal(phase.extracted, 1);
+  assert.equal(phase.failed, 1);
+  assert.equal(service.getById(good.id).metadata?.pending_extracted_at, null, "success clears pending");
+  assert.equal(service.getById(bad.id).metadata?.pending_extracted_at, null, "failure clears pending");
+  store.close();
+});
+
+test("sleep: all-failed extraction surfaces failed status through deriveStatus (review #5)", async () => {
+  const { service, store } = setup();
+  makeMemory(service, "坏记忆1", "bad 一", "history");
+  makeMemory(service, "坏记忆2", "bad 二", "history");
+  const ctx = mockCtx(() => "不是JSON{{{", { provider: "p", model: "m" });
+  const result = await runSleep(ctx, service, baseConfig({ sleepEntityExtractionEnabled: true }), ctx.logger, null, null);
+  const phase = result.phases["entity-extraction"];
+  assert.equal(phase.status, "failed", "all-failed extraction reports failed");
+  assert.equal(phase.failed, 2);
+  assert.ok(["failed", "degraded"].includes(result.status), "deriveStatus folds failed into run status");
+  store.close();
+});
+
+test("store: listForEntityExtraction pages oldest un-stamped candidates (review #2)", async () => {
+  const { service, store } = setup();
+  const a = makeMemory(service, "甲", "内容甲", "history");
+  makeMemory(service, "乙", "内容乙", "history");
+  const archived = makeMemory(service, "归档", "内容归档", "history");
+  store.setArchived(archived.id, true);
+  makeMemory(service, "摘要", "内容摘要", "summary");
+  makeMemory(service, "丙", "内容丙", "history"); // second un-stamped candidate so oldest-first has two to compare
+  service.setMemoryMetadata(a.id, { entity_extracted_at: new Date().toISOString() });
+  const list = store.listForEntityExtraction({ limit: 10, offset: 0 });
+  const titles = list.map((m) => m.title);
+  assert.ok(!titles.includes("归档"), "archived excluded");
+  assert.ok(!titles.includes("摘要"), "summary excluded");
+  assert.ok(!titles.includes("甲"), "already-stamped excluded");
+  assert.ok(titles.includes("乙"), "un-stamped included");
+  assert.ok(titles.includes("丙"), "un-stamped included");
+  assert.equal(list[0].created_at <= list[1].created_at, true, "oldest first");
+  store.close();
+});