@modusensus/dsh-mneme 0.6.1 → 0.6.5

package/src/dream/tag-extractor.js

@@ -0,0 +1,149 @@
+// v0.6.2 auto-tag: a lightweight LLM pass that runs after an autoDream
+// consolidation and extracts 1-3 tags per retained memory. Opt-in via
+// config.autoTagEnabled (default false); autoTagMaxPerRun (default 10) bounds
+// how many memories are tagged per run.
+//
+// Design notes:
+//   - ONE batched LLM call per run (the consolidation route is reused). Each
+//     memory is a prompt line; the model replies with a JSON array of
+//     {"id","tags"} entries — the per-memory contract is `{"tags":[...]}`.
+//   - Fail-safe everywhere: a missing route / aborted stream / unparseable
+//     JSON / unknown id / illegal tag are all skipped, never thrown. Tagging
+//     must never degrade the consolidation run it rides on.
+//   - The actual writes go through service.applyMemoryTags inside a
+//     service.transaction, so the mirror re-renders exactly once per pass and
+//     the write hooks fire once (never per memory).
+import { sanitizeTags, MAX_TAG_LENGTH } from "../parser/tag.js";
+
+const TAG_PROMPT = `你是记忆库标签助手。下面是保留的记忆条目（id、标题、内容）。
+对每条记忆提取 1-3 个中文或英文标签，用于检索分类。
+标签规则：
+- 只允许字符：字母、数字、下划线、中文、连字符（如：linux、考研、deepseek-r1）
+- 标签长度 ≤ ${MAX_TAG_LENGTH} 字符
+- 宁缺毋滥：提取最核心的 1-3 个，不要凑数
+- 不要输出内容里没有依据的标签
+只输出一个 JSON 数组，每项形如 { "id": "<记忆id>", "tags": ["标签1", "标签2"] }。
+不要输出其他文字。`;
+
+/** Same stream consumption contract as dream.js. Returns accumulated text or
+ *  undefined when the stream aborted/errored. */
+async function streamText(ctx, options) {
+  if (!ctx?.llm?.stream) return undefined;
+  let text = "";
+  for await (const chunk of ctx.llm.stream(options)) {
+    if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+    if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+      return undefined;
+    }
+  }
+  return text;
+}
+
+/** Pull the outermost JSON array out of a model reply (same tolerant contract
+ *  as sleep.js parseJsonArray): find the first `[` … last `]` and parse. */
+function parseJsonArray(text) {
+  if (typeof text !== "string") return undefined;
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end <= start) return undefined;
+  try {
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolve the LLM route for the tag pass: the caller-provided consolidation
+ *  route first, then dreamProvider/dreamModel. Falls through to undefined. */
+function resolveTagRoute(route, config, logger) {
+  if (route?.provider && route?.model) return route;
+  if (config?.dreamProvider && config?.dreamModel) return { provider: config.dreamProvider, model: config.dreamModel };
+  logger?.warn?.("dsh-mneme auto-tag: no llm route available");
+  return undefined;
+}
+
+/**
+ * Run the auto-tag pass over retained memories.
+ * @param {object} opts
+ * @param {object} opts.ctx        — { llm, logger }
+ * @param {object} opts.service    — service handle (all/transaction/applyMemoryTags)
+ * @param {object} opts.config     — plugin config (autoTagMaxPerRun, dreamProvider…)
+ * @param {object} [opts.route]    — already-resolved consolidation route
+ * @returns {Promise<{ok: boolean, tagged: number, skipped: number, failed: number, skippedBy: boolean}>}
+ */
+export async function runAutoTag({ ctx, service, config, route }) {
+  const logger = ctx?.logger;
+  const maxPerRun = Number.isInteger(config?.autoTagMaxPerRun) && config.autoTagMaxPerRun > 0
+    ? config.autoTagMaxPerRun
+    : 10;
+  // Retained = post-consolidation active memories, newest first, capped.
+  const memories = service.all()
+    .filter((m) => !m.forgotten && !m.archived && !m.session_disposed_at && m.type !== "summary")
+    .sort((a, b) => {
+      const ta = String(a.updated_at ?? "");
+      const tb = String(b.updated_at ?? "");
+      if (ta < tb) return 1;
+      if (ta > tb) return -1;
+      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    })
+    .slice(0, Math.max(1, maxPerRun));
+  if (!memories.length) return { ok: true, tagged: 0, skipped: 0, failed: 0, skippedBy: "empty" };
+  const tagRoute = resolveTagRoute(route, config, logger);
+  if (!tagRoute) return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "no-route" };
+
+  const listText = memories
+    .map((m) => `id=${m.id} | title=${m.title} | content=${m.content}`)
+    .join("\n");
+  const text = await streamText(ctx, {
+    provider: tagRoute.provider,
+    model: tagRoute.model,
+    purpose: "compaction",
+    maxTokens: Math.min(2048, config?.dreamMaxTokens ?? 2048),
+    messages: [
+      { role: "system", content: [{ type: "text", text: TAG_PROMPT }] },
+      { role: "user", content: [{ type: "text", text: listText }] }
+    ]
+  });
+  if (text === undefined) return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "llm-failed" };
+
+  const entries = parseJsonArray(text);
+  if (!entries) {
+    logger?.warn?.("dsh-mneme auto-tag: no json array in llm output");
+    return { ok: false, tagged: 0, skipped: memories.length, failed: 0, skippedBy: "bad-json" };
+  }
+
+  // Validate ids against the candidate set (unknown ids are ignored, never
+  // written — a stray id could otherwise tag an unrelated memory).
+  const candidateIds = new Set(memories.map((m) => m.id));
+  const toWrite = [];
+  let skipped = 0;
+  let failed = 0;
+  const seenIds = new Set();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") { failed++; continue; }
+    const id = typeof entry.id === "string" ? entry.id : undefined;
+    if (!id || !candidateIds.has(id)) { failed++; continue; }
+    if (seenIds.has(id)) continue; // first entry per id wins
+    seenIds.add(id);
+    // Reuse the shared sanitizer: strip, ≤20 chars, drop illegal, dedupe.
+    const tags = sanitizeTags(entry.tags);
+    if (!tags.length) { skipped++; continue; }
+    toWrite.push({ id, tags });
+  }
+
+  // Write the whole batch under one transaction: mirror re-renders once.
+  let tagged = 0;
+  try {
+    service.transaction(() => {
+      for (const { id, tags } of toWrite) {
+        service.applyMemoryTags(id, tags);
+        tagged++;
+      }
+    });
+  } catch (error) {
+    logger?.warn?.(`dsh-mneme auto-tag: write failed: ${String(error)}`);
+    return { ok: false, tagged, skipped, failed, skippedBy: "write-failed" };
+  }
+  return { ok: true, tagged, skipped, failed, skippedBy: false };
+}

package/src/dream.js

@@ -1,5 +1,6 @@
 import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts } from "./dream/clustering.js";
+import { runAutoTag } from "./dream/tag-extractor.js";
 import { createHash, randomUUID } from "node:crypto";
 export { validateDecisions, applyDecisions, normalizeDecisions };
 
@@ -815,6 +816,25 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // that only froze conflicts is not a noop.
     const noChange = frozenCount === 0 && applied === 0 && committed.every((c) => c.action === "keep");
 
+    // v0.6.2 auto-tag: a light LLM pass over the retained (post-consolidation)
+    // memories. Opt-in via config.autoTagEnabled, bounded by autoTagMaxPerRun,
+    // and always fail-safe — a tag failure must never change the consolidation
+    // outcome reported below (it is logged and counted, nothing more).
+    let autoTagged = 0;
+    if (config.autoTagEnabled === true) {
+      try {
+        const tagResult = await runAutoTag({ ctx, service, config, route });
+        autoTagged = tagResult?.tagged ?? 0;
+        if (tagResult?.ok === false && tagResult?.skippedBy && tagResult.skippedBy !== "empty") {
+          logger?.warn?.(`dsh-mneme dream: auto-tag skipped (${tagResult.skippedBy})`);
+        } else if (autoTagged > 0) {
+          logger?.info?.(`[dsh-mneme] auto-tag: ${autoTagged} memory(ies) tagged`);
+        }
+      } catch (error) {
+        logger?.warn?.(`dsh-mneme dream: auto-tag failed: ${String(error)}`);
+      }
+    }
+
     // Keep the vector index consistent with the post-dream store state.
     if (semantic?.embedder && semantic?.vectorIndex) {
       try {

package/src/mirror.js

@@ -31,6 +31,15 @@ function renderMemory(m) {
     .digest("hex");
   const lines = [];
   lines.push(`## ${esc(m.title)}`);
+  // v0.6.2 tag line: entity_attrs-backed tags (attached by the service as
+  // `entityTags`) rendered as `#tag` space-separated under the title. No tags
+  // → no line. Legacy `- **标签**:` metadata below keeps the memories.tags
+  // column (still written by save/update) readable.
+  const entityTags = Array.isArray(m.entityTags) ? m.entityTags : [];
+  if (entityTags.length) {
+    lines.push("");
+    lines.push(entityTags.map((t) => `#${esc(t)}`).join(" "));
+  }
   lines.push("");
   lines.push(`- **ID**: \`${m.id}\``);
   lines.push(`- **类型**: ${m.type}`);

package/src/parser/tag.js

@@ -0,0 +1,59 @@
+/**
+ * Tag parser (v0.6.2). Given a memory's content, extract explicit hashtags of
+ * the form `#标签`. The allowed character set is `[a-zA-Z0-9_一-龥-]+` (ASCII
+ * letters/digits/underscore, CJK characters, and hyphen), so `#linux`,
+ * `#deepseek` and `#考研` are all valid tags.
+ *
+ * Rules:
+ *   - multiple tags on one line are all extracted, in source order;
+ *   - duplicates collapse to the first occurrence;
+ *   - tags longer than MAX_TAG_LENGTH (20) characters are dropped as illegal;
+ *   - edge hyphens (leading/trailing, e.g. a sentence-terminating `#tag-`) are
+ *     stripped; a tag that collapses to empty is dropped;
+ *   - markdown `## heading` never matches (the second `#`/space is not in the
+ *     allowed set).
+ *
+ * Pure module: no store, no side effects — persistence (store.setMemoryTags)
+ * is a separate step. sanitizeTags shares the same validation so LLM-extracted
+ * tag arrays (autoDream tag-extractor) are filtered identically.
+ */
+
+export const MAX_TAG_LENGTH = 20;
+
+// `一` (U+4E00) .. `龥` (U+9FA5) is the CJK Unified Ideographs block (the
+// rule's `一-龥`). Matching requires a tag character right after `#` so a bare
+// `#` and markdown `## heading` are naturally excluded (#/space not in set).
+const TAG_RE = /#[a-zA-Z0-9_一-龥-]+/g;
+const EDGE_HYPHEN = /^-+|-+$/g;
+const VALID_TAG = /^[a-zA-Z0-9_一-龥-]+$/;
+
+/** Validate + dedupe an array of tag strings. Non-strings, blanks, over-long
+ *  and illegal-character tags are dropped (fail-safe). A leading `#` is
+ *  tolerated so raw LLM output can be passed through directly. */
+export function sanitizeTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const t of tags) {
+    if (typeof t !== "string") continue;
+    let tag = t.trim();
+    if (tag.startsWith("#")) tag = tag.slice(1);
+    tag = tag.replace(EDGE_HYPHEN, "");
+    if (!tag || tag.length > MAX_TAG_LENGTH) continue;
+    if (!VALID_TAG.test(tag)) continue;
+    if (seen.has(tag)) continue; // 去重（保留首次出现顺序）
+    seen.add(tag);
+    out.push(tag);
+  }
+  return out;
+}
+
+/** @returns {string[]} validated tags in source order, deduplicated. */
+export function parseTags(content) {
+  if (typeof content !== "string" || content.length === 0) return [];
+  const raw = [];
+  TAG_RE.lastIndex = 0;
+  let m;
+  while ((m = TAG_RE.exec(content)) !== null) raw.push(m[0]);
+  return sanitizeTags(raw);
+}

package/src/search/tag-boost.js

@@ -0,0 +1,61 @@
+// v0.6.4 Tag-weighted re-rank helpers.
+// Query tags come from `#hashtags` in the query plus any known tags the query
+// mentions; candidates whose tags overlap the query tags or the session's
+// hot-memory tags get their score boosted before the final top-K cut.
+
+/**
+ * Extract tags from a query: explicit `#hashtags` (CJK allowed) plus known
+ * tags whose lowercase form appears in the query. Deduped, order-preserving.
+ */
+export function extractQueryTags(query, knownTags = []) {
+  if (typeof query !== "string" || !query) return [];
+  const set = new Set();
+  const re = /#([a-zA-Z0-9_一-龥-]+)/g;
+  let m;
+  while ((m = re.exec(query)) !== null) set.add(m[1]);
+  const q = query.toLowerCase();
+  for (const t of knownTags) {
+    if (typeof t === "string" && q.includes(t.toLowerCase())) set.add(t);
+  }
+  return Array.from(set);
+}
+
+function hasOverlap(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+  const setB = new Set(b);
+  return a.some((x) => setB.has(x));
+}
+
+/**
+ * Boost candidate scores by tag overlap with the query and/or session tags.
+ * Each candidate is expected to carry a `tags` array (enriched by the caller).
+ * Returns a new array sorted by boosted score descending; candidates that were
+ * boosted are marked `tagBoost: true`. Unchanged candidates keep their
+ * relative order (stable).
+ */
+export function applyTagBoost(
+  candidates,
+  { queryTags = [], sessionTags = [], factor = 1.15, sessionFactor = 1.08 }
+) {
+  const boosted = candidates.map((c) => {
+    const tags = c.tags ?? [];
+    let score = typeof c.score === "number" ? c.score : 0;
+    let didBoost = false;
+
+    if (queryTags.length && hasOverlap(tags, queryTags)) {
+      score = Math.min(1, score * factor);
+      didBoost = true;
+    }
+    if (sessionTags.length && hasOverlap(tags, sessionTags)) {
+      score = Math.min(1, score * sessionFactor);
+      didBoost = true;
+    }
+
+    const out = { ...c, score };
+    if (didBoost) out.tagBoost = true;
+    return out;
+  });
+
+  boosted.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+  return boosted;
+}

package/src/service.js

@@ -4,6 +4,7 @@ import { evaluateMemoryQuality } from "./quality-filter.js";
 import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
 import { parseWikiLinks } from "./parser/wiki-link.js";
+import { extractQueryTags, applyTagBoost } from "./search/tag-boost.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -327,6 +328,55 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     return hits;
   }
 
+  /**
+   * Search for memories carrying a given tag set (v0.6.2). Multiple tag:
+   * tokens in one query use AND semantics — a memory must carry every tag.
+   * Combinable with the leftover query: an entity:/attr: prefix is intersected
+   * with the tag-matched set, and plain keyword text ranks it (only rows whose
+   * keyword score > 0 survive). Tags are first-class recall, not entity-gated:
+   * the tag match itself does not depend on config.entitySearchEnabled.
+   * @param {string[]} tagTokens
+   * @param {string} q — leftover query after tag: tokens were stripped
+   * @param {object} [options]
+   * @param {number} [options.topK=20]
+   * @returns {any[]}
+   */
+  function searchByTags(tagTokens, q, options) {
+    const { topK = 20 } = options;
+    const tags = (Array.isArray(tagTokens) ? tagTokens : [])
+      .map((t) => String(t).trim()).filter(Boolean);
+    if (!tags.length) return [];
+    let hits = store.findMemoriesByTags(tags);
+    if (!hits.length) return [];
+    // Intersect with entity:/attr: prefixes present in the leftover query.
+    if (config?.entitySearchEnabled) {
+      if (q.startsWith("entity:")) {
+        const ids = new Set(searchByEntity(q.slice(7).trim(), { topK: 10000 }).map((m) => m.id));
+        hits = hits.filter((m) => ids.has(m.id));
+      }
+      if (q.startsWith("attr:")) {
+        const [key, value] = q.slice(5).split("=");
+        const ids = new Set(searchByAttr(key, value, { topK: 10000 }).map((m) => m.id));
+        hits = hits.filter((m) => ids.has(m.id));
+      }
+    }
+    // Leftover plain text ranks the tag-matched set; only rows whose title or
+    // content actually mentions the keyword survive (scoreKeyword's 0.3 base is
+    // a non-match, so the containment check is the real gate); otherwise
+    // preserve insertion order.
+    const keywordOnly = q && !q.startsWith("entity:") && !q.startsWith("attr:");
+    hits = keywordOnly
+      ? hits
+          .map((m) => ({ ...m, score: scoreKeyword(m, q), source: "tag" }))
+          .filter((m) => (m.title ?? "").toLowerCase().includes(q.toLowerCase())
+            || (m.content ?? "").toLowerCase().includes(q.toLowerCase()))
+          .sort((a, b) => b.score - a.score)
+      : hits.map((m) => ({ ...m, source: "tag" }));
+    const result = hits.slice(0, topK);
+    touchRecalled(result);
+    return result;
+  }
+
   /**
    * Semantic-aware memory search: keyword recall (store.search) plus optional
    * vector recall + rerank. mode:
@@ -433,8 +483,18 @@ export function createService({ store, mirror, config, onWrite, logger }) {
 
   async function searchMemories(query, options = {}) {
     const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = options;
-    const q = String(query ?? "").trim();
-    if (!q) return [];
+    const raw = String(query ?? "").trim();
+    if (!raw) return [];
+
+    // tag: 前缀（v0.6.2）。先把所有 tag: 令牌从 query 里剥出来，剩余的 q 仍可带
+    // entity:/attr: 前缀或普通关键词 —— searchByTags 负责交集/排序。没有 tag:
+    // 令牌则走下面的 entity:/attr:/文本原逻辑（完全向后兼容）。
+    const tagTokens = [];
+    const q = raw.replace(/\btag:([^\s]+)/g, (_, tok) => {
+      if (tok) tagTokens.push(tok);
+      return "";
+    }).trim();
+    if (tagTokens.length) return searchByTags(tagTokens, q, options);
 
     // entity:/attr: 前缀路由（v0.3.0 Phase 3）。entitySearchEnabled 关闭时走原逻辑。
     if (config?.entitySearchEnabled) {
@@ -539,7 +599,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       const ranked = [...byId.values()]
         .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
         .map((r) => ({ ...r, score: Math.max(0, Math.min(1, r.score ?? 0)) }));
-      merged = ranked.slice(0, lim);
+      // Tag boost (v0.6.4) needs the full ranked pool, not just the top-lim
+      // slice, so a tagged candidate just below the line can be re-admitted
+      // after the boost. Without boost this is the legacy lim truncation.
+      merged = config.tagBoostEnabled === true ? ranked : ranked.slice(0, lim);
       if (merged.length < lim && !merged.length) {
         // Vector unavailable entirely: fall back to plain keyword.
         merged = keyword.slice(0, lim);
@@ -565,7 +628,31 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // it is the documented text-only path and must not be altered by
     // embedding state.
     merged = mode === "keyword" ? merged : semanticDeduplicate(merged);
+
+    // Tag-weighted re-rank (v0.6.4): boost candidates whose tags overlap the
+    // query tags or the current session's hot-memory tags — applied BEFORE the
+    // final top-K cut so tagged candidates just below the line can be
+    // re-admitted. Opt-in, and skipped entirely on the keyword-only path. When
+    // a reranker is configured (opt-in), it remains the final authority on
+    // order; the boost still shapes which candidates reach it.
+    if (config.tagBoostEnabled === true && mode !== "keyword" && merged.length) {
+      const ids = merged.map((m) => m.id);
+      const tagsMap = store.getMemoryTagsMap(ids);
+      const enriched = merged.map((m) => ({ ...m, tags: tagsMap.get(m.id) ?? [] }));
+      const knownTags = [...tagsMap.values()].flat();
+      const queryTags = extractQueryTags(q, knownTags);
+      const sessionTags = Array.isArray(options?.sessionTags) ? options.sessionTags : [];
+      if (queryTags.length || sessionTags.length) {
+        merged = applyTagBoost(enriched, {
+          queryTags,
+          sessionTags,
+          factor: config.tagBoostFactor,
+          sessionFactor: config.sessionTagBoostFactor,
+        }).map(({ tags, ...rest }) => rest);
+      }
+    }
     merged = merged.slice(0, lim);
+
     let result = useRerank && reranker && merged.length
       ? await rerankCandidates(q, merged, lim)
       : merged;
@@ -1043,6 +1130,21 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     }));
   }
 
+  /**
+   * Directory view (v0.6.3): group live memories by tag. Delegates to
+   * store.getDirectory (tag-sorted groups, importance/updated DESC members,
+   * live-only filtering) and maps every memory to the wire DTO so the result
+   * is JSON-safe for the API endpoint.
+   * @returns {{groups: {tag: string, memories: object[]}[], untagged: object[]}}
+   */
+  function getDirectory() {
+    const { groups, untagged } = store.getDirectory();
+    return {
+      groups: groups.map((g) => ({ tag: g.tag, memories: toApiList(g.memories) })),
+      untagged: toApiList(untagged)
+    };
+  }
+
   /**
    * Three-way merge of in-flight human mirror edits before a re-render.
    * Runs on every syncMirror, so a human edit made between two store writes is
@@ -1150,8 +1252,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // leaving committed files mislabeled as failed and masking partial state.
       // Absent entries (a type with no memories) count as success: sync prunes
       // the stale file, which is itself a completed physical state.
+      // v0.6.2: attach entity_attrs-backed tags (entityTags) after the human-edit
+      // merge so renderMemory can draw the `#tag` line under each title. The
+      // bulk map is a single query, and a missing row simply renders no line.
+      const reconciled = reconcileHumanEdits(list);
+      const tagsMap = store.getMemoryTagsMap(reconciled.map((m) => m.id));
+      const tagged = reconciled.map((m) => ({ ...m, entityTags: tagsMap.get(m.id) ?? [] }));
       let allOk = true;
-      const results = mirror.sync(reconcileHumanEdits(list)) ?? {};
+      const results = mirror.sync(tagged) ?? {};
       for (const type of Object.keys(TYPE_FILE)) {
         const r = results[type];
         const ok = !r || r.ok === true;
@@ -1371,6 +1479,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     injectCandidates,
     mergeHumanEdits,
     toApiList,
+    getDirectory,
     transaction,
     enqueue,
     setDreamHook(fn) { dreamHook = fn; },
@@ -1585,6 +1694,25 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     saveWikiLinks: (r) => store.saveWikiLinks(r),
     listEntities: (o) => store.listEntities(o),
     getRelations: (id) => store.getRelations(id),
+    // Tag system (v0.6.2). setMemoryTags is the manual/user path: gated by
+    // config.manualTagEnabled (default true), re-renders the mirror and fires
+    // the write hook. applyMemoryTags is the raw write used by the autoDream
+    // tag pass (gated by autoTagEnabled, wrapped in a transaction by the
+    // extractor so the mirror re-renders exactly once).
+    setMemoryTags: (memoryId, tags) => {
+      if (config.manualTagEnabled === false) {
+        return { ok: false, error: "manualTagEnabled is off" };
+      }
+      const stored = store.setMemoryTags(memoryId, tags);
+      afterSync("write");
+      notifyWrite();
+      return { ok: true, tags: stored };
+    },
+    getMemoryTags: (memoryId) => store.getMemoryTags(memoryId),
+    // Read-only gate flag so the Web panel can hide tag editing when the
+    // manual path is disabled (default: manual tagging is on).
+    manualTagEnabled: () => config.manualTagEnabled !== false,
+    applyMemoryTags: (memoryId, tags) => store.setMemoryTags(memoryId, tags),
     saveAttr: (r) => store.saveAttr(r),
     createEntity: (r) => store.createEntity(r),
     findEntityByName: (n) => store.findEntityByName(n),