@modusensus/dsh-mneme 0.2.11 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-373%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-404%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -92,7 +92,19 @@ v0.2 起新增**完全离线的语义记忆引擎**（本地模型 + 精排 +
 
 配置只需在 `cordis.patch.yml` 里设置 `embedProvider`（默认 `openai`，保持 v0.1 行为；改为 `local` 即离线）。升级无需迁移数据。
 
-> 📖 详见 [语义增强架构](docs/SEMANTIC.md) · [本地模型部署指南](docs/LOCAL_MODEL.md) · [从 v0.1 升级说明](docs/MIGRATION.md)
+### 实体结构化记忆（Entity Gene）🧬
+
+v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带时间轴的属性**、**实体间关系**，让搜索从"字面关键词"升级为"按实体/属性精确召回"。
+
+- **三表**：`entities` / `entity_attrs`（`valid_until` 快照式时间轴）/ `entity_relations`，旧库打开自动建表，幂等无迁移成本
+- **自动抽取**：`entityExtractionEnabled=true` 后，新写入的记忆 fire-and-forget 触发 LLM 抽取（同名实体去重、属性存时间轴、关系追加；失败绝不阻塞写入）
+- **实体搜索**（`searchMemories` 前缀路由，`entitySearchEnabled` 默认开）：
+  - `entity:阿尔托` → 属性精确关联的记忆（`_score 1.0`）排在关键词提及（`_score 0.7`）之前
+  - `attr:国籍=芬兰` → 精确匹配该属性值的记忆
+  - `attr:国籍` → 该属性键的**全部**当前有效记忆（value 为空契约）
+- **autoDream 联动**：update 决策写 `supersedes` 自引用（属性版本被替代）；merge 决策把 loser 的属性归属迁移到 keeper（keeper 已有同键当前值则失效）
+
+> 📖 详见 [实体结构化记忆设计](docs/ENTITIES.md) · [语义增强架构](docs/SEMANTIC.md) · [本地模型部署指南](docs/LOCAL_MODEL.md) · [从 v0.1 升级说明](docs/MIGRATION.md)
 
 ## 📦 安装
 
@@ -184,6 +196,11 @@ dsh web
 | `reflectionFailureTracking` | `true` | 失败追踪总开关 |
 | `reflectionUpdateMaxPerRun` | `2` | 每次整理最多 update 数 |
 | `reflectionUpdateMinAgeHours` | `24` | 新建记忆保护期（小时） |
+| `entityExtractionEnabled` | `false` | 实体抽取总开关（v0.3.0；存储层恒可用） |
+| `entityExtractionModel` | 空 | 抽取专用模型（空 = 用 agent 默认模型） |
+| `entityExtractionMaxEntities` | `10` | 每次抽取实体数上限 |
+| `entityExtractionMaxAttrs` | `20` | 每实体属性数上限 |
+| `entitySearchEnabled` | `true` | `entity:` / `attr:` 前缀搜索开关 |
 
 > 🔐 **API 安全**：DSH 无内置鉴权且默认仅监听 `127.0.0.1`。插件 API 默认开放（便于 Web 面板即装即用）。如需防护（如局域网暴露），在配置中设置 `apiToken`：写操作（画像/规则/命令）与密钥端点（`vector-config`、`vector-reindex`）需携带 `Authorization: Bearer <token>`（前端设置面板可填入同一 token），只读的 `list` / `search` / `semantic` 保持开放。`/api/dsh-mneme/vector-config` 返回的 `apiKey` 已掩码（`sk-***…`），存储仍保留明文供调用；前端回传空或掩码值表示"不改 key"。
 
@@ -219,13 +236,14 @@ src/
 ├── summarize.js      # 会话结束 LLM 摘要
 ├── dream.js          # autoDream 调度 + runDream（LLM 决策 + 摘要）
 ├── dream/decisions.js# 决策校验（fail-safe）+ 决策应用
+├── entities/extractor.js # 实体抽取器（v0.3.0：LLM JSON 抽取 + 去重 + fail-safe）
 ├── embedding.js      # OpenAI 兼容 embeddings 客户端 + 向量检索
 ├── api.js            # HTTP 路由（Web 面板数据通道）
 └── index.js          # 插件接线
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 373 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 404 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -234,7 +252,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 373 个测试
+npm test           # 运行 404 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```
@@ -250,6 +268,7 @@ npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动
 - [记忆库设计](../docs/superpowers/specs/2026-08-13-dsh-mneme-design.md)
 - [autoDream 设计](../docs/superpowers/specs/2026-08-13-dsh-mneme-autodream-design.md)
 - [实施计划](../docs/superpowers/plans/2026-08-13-dsh-memory-autodream.md)
+- [实体结构化记忆设计](docs/ENTITIES.md)
 - [语义增强架构](docs/SEMANTIC.md)
 - [本地模型部署指南](docs/LOCAL_MODEL.md)
 - [从 v0.1 升级说明](docs/MIGRATION.md)

package/lib/config.js

@@ -75,4 +75,18 @@ export const Config = z.object({
   conflictFreezeEnabled: z.boolean().default(false),
   // Maximum number of frozen conflicts to keep pending for manual review.
   conflictFreezeMaxPending: z.natural().min(1).max(1000).default(100),
+
+  // --- entity gene (v0.3.0) -----------------------------------------------
+  // Opt-in: when false (default) nothing in the pipeline extracts entities.
+  // The storage layer (entities/entity_attrs/entity_relations tables + CRUD)
+  // is always available regardless of this flag.
+  entityExtractionEnabled: z.boolean().default(false),
+  // Optional model override for entity extraction; empty = use the caller's
+  // default provider/model.
+  entityExtractionModel: z.string().default(""),
+  // Cap on entities per extraction pass and attributes per entity.
+  entityExtractionMaxEntities: z.natural().min(1).max(20).default(10),
+  entityExtractionMaxAttrs: z.natural().min(1).max(50).default(20),
+  // Prefix/semantic search over entity names (used by recall).
+  entitySearchEnabled: z.boolean().default(true),
 });

package/lib/dream/decisions.js

@@ -167,7 +167,7 @@ function casGuard(service, snapshot, ids) {
  *   committed  - the decisions that actually landed, for outcome/receipt based
  *                on real committed sub-steps rather than the raw LLM list.
  */
-export function applyDecisions(decisions, service, logger = null, snapshot = null) {
+export function applyDecisions(decisions, service, logger = null, snapshot = null, config = {}) {
   let applied = 0;
   const conflicts = [];
   const failures = [];
@@ -180,7 +180,7 @@ export function applyDecisions(decisions, service, logger = null, snapshot = nul
         committed.push({ action: "keep", ids: d.ids });
         continue;
       }
-      const outcome = applyOne(d, service, snapshot);
+      const outcome = applyOne(d, service, snapshot, config);
       if (outcome === "skipped") continue;
       applied += outcome.applied;
       committed.push(outcome.committed);
@@ -197,12 +197,12 @@ export function applyDecisions(decisions, service, logger = null, snapshot = nul
   return { applied, conflicts, failures, committed };
 }
 
-function applyOne(d, service, snapshot) {
+function applyOne(d, service, snapshot, config = {}) {
   switch (d.action) {
     case "archive": return applyArchive(d, service, snapshot);
-    case "merge": return applyMerge(d, service, snapshot);
+    case "merge": return applyMerge(d, service, snapshot, config);
     case "conflict": return applyConflict(d, service, snapshot);
-    default: return applyUpdate(d, service, snapshot);
+    default: return applyUpdate(d, service, snapshot, config);
   }
 }
 
@@ -222,7 +222,7 @@ function applyArchive(d, service, snapshot) {
   return { applied: targets.length, committed: { action: "archive", ids: targets } };
 }
 
-function applyMerge(d, service, snapshot) {
+function applyMerge(d, service, snapshot, config = {}) {
   const sources = d.ids.filter((id) => id !== d.keepSource);
   // Idempotent replay: if every other source is already archived, this merge
   // already landed — skip so a replayed/concurrent decision never double-counts
@@ -241,6 +241,18 @@ function applyMerge(d, service, snapshot) {
       const mem = service.getById(id);
       if (mem && !mem.archived) service.setArchived(id, true);
     }
+    // 4.3.2 迁移实体关联（opt-in）：将 loser（source）记忆关联的 entity_attrs 的
+    // memory_id 迁移到 keeper；keeper 已有同 entity+key 的当前属性时 loser 行被
+    // 失效。单个 source 迁移失败只告警，绝不能导致整个 merge 事务回滚（fail-safe）。
+    if (config.entityExtractionEnabled && typeof service.migrateAttrsToMemory === "function") {
+      for (const id of sources) {
+        try {
+          service.migrateAttrsToMemory(id, d.keepSource, new Date().toISOString());
+        } catch (error) {
+          logger?.warn?.(`dsh-mneme dream: failed to migrate attrs from ${id} to ${d.keepSource}: ${error.message}`);
+        }
+      }
+    }
   });
   return {
     applied: 1,
@@ -269,7 +281,7 @@ function applyConflict(d, service, snapshot) {
   return { applied: 1, committed: { action: "conflict", winner: d.winner, loser: d.loser, count_before: 2, count_after: 1 } };
 }
 
-function applyUpdate(d, service, snapshot) {
+function applyUpdate(d, service, snapshot, config = {}) {
   const id = d.ids[0];
   const mem = service.getById(id);
   if (!mem || mem.archived) return "skipped";
@@ -288,5 +300,25 @@ function applyUpdate(d, service, snapshot) {
       importance: d.importance ?? cur.importance
     });
   });
+  // 4.3.1 supersedes 关系（opt-in）：事务提交成功后，为该记忆关联的每条实体属性
+  // 建立自引用 supersedes 关系，表示"此属性版本已被替代"。仅记录、绝不阻断主流程
+  // （fail-safe）：记录失败只告警，update 本身照常生效。
+  if (config.entityExtractionEnabled && typeof service.saveRelation === "function" && typeof service.getAttrsByMemory === "function") {
+    try {
+      const oldAttrs = service.getAttrsByMemory(id);
+      for (const attr of oldAttrs) {
+        if (!attr.entity_id) continue;
+        service.saveRelation({
+          from_entity: attr.entity_id,
+          to_entity: attr.entity_id,
+          relation_type: "supersedes",
+          memory_id: id,
+          metadata: JSON.stringify({ attr_key: attr.attr_key, old_value: attr.attr_value })
+        });
+      }
+    } catch (error) {
+      logger?.warn?.(`dsh-mneme dream: failed to record supersedes relations for ${id}: ${error.message}`);
+    }
+  }
   return { applied: 1, committed: { action: "update", ids: [id], title: d.title, content: d.content, importance: d.importance, count_before: 1, count_after: 1 } };
 }

package/lib/dream.js

@@ -541,7 +541,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // a target changed during the LLM call is skipped and reported as a
     // conflict instead of being overwritten (item ①). Frozen conflicts are
     // excluded from this list (they are parked, not applied).
-    const { applied, conflicts, failures, committed } = applyDecisions(applyList, service, logger, snapshot);
+    const { applied, conflicts, failures, committed } = applyDecisions(applyList, service, logger, snapshot, config);
     // Per-record receipt chain: one row per actually-committed merge/conflict/
     // update verdict, stamped with the decision-basis digest + idempotency
     // counters (count_before → count_after). Written here, before the run audit

package/lib/entities/extractor.js

@@ -0,0 +1,242 @@
+const VALID_TYPES = new Set(["person", "project", "concept", "technology", "organization"]);
+const VALID_RELATIONS = new Set(["uses", "depends_on", "part_of", "related_to"]);
+const MAX_MEMORY_CHARS = 4000;
+
+function buildSystemPrompt(config) {
+  const maxEntities = config.entityExtractionMaxEntities ?? 10;
+  const maxAttrs = config.entityExtractionMaxAttrs ?? 20;
+  
+  return `You are an entity extraction engine. Extract named entities, their attributes, and relations from the given text.
+
+RULES:
+- Entities are concrete people, projects, technologies, concepts, or organizations.
+- Attributes are characteristic states of an entity. Only extract attributes explicitly mentioned in the text.
+- Do NOT infer, guess, or hallucinate. Only extract what is clearly stated.
+- Use canonical names (full name / primary name). Do NOT merge synonyms — different spellings of the same person are different entities.
+- Output MUST be strict JSON with this exact structure:
+{
+  "entities": [
+    {"name": "string", "type": "person|project|concept|technology|organization", "attrs": [{"key": "string", "value": "string", "confidence": 0.9}]}
+  ],
+  "relations": [
+    {"from": "entityName", "to": "entityName", "type": "uses|depends_on|part_of|related_to"}
+  ]
+}
+
+CONSTRAINTS:
+- "type" must be one of: person, project, concept, technology, organization. If unsure, use "concept".
+- "relations" from/to must reference entity names from the "entities" list.
+- Maximum ${maxEntities} entities. Maximum ${maxAttrs} attributes per entity. Truncate if exceeded.
+- Only include entity-related attributes. Ignore irrelevant miscellaneous details.
+- Return ONLY the JSON object. No explanations, no markdown, no code fences.`;
+}
+
+function buildUserMessage(memoryText) {
+  const truncated = memoryText.length > MAX_MEMORY_CHARS 
+    ? memoryText.slice(0, MAX_MEMORY_CHARS) + "..." 
+    : memoryText;
+  return truncated;
+}
+
+function extractJsonFromText(text) {
+  if (!text || typeof text !== "string") return null;
+  
+  // Try direct parse first
+  try {
+    return JSON.parse(text);
+  } catch {
+    // fall through
+  }
+  
+  // Try to find first {...} block
+  const match = text.match(/\{[\s\S]*\}/);
+  if (match) {
+    try {
+      return JSON.parse(match[0]);
+    } catch {
+      return null;
+    }
+  }
+  
+  return null;
+}
+
+function sanitizeType(type) {
+  if (VALID_TYPES.has(type)) return type;
+  return "concept";
+}
+
+function sanitizeConfidence(conf) {
+  const num = Number(conf);
+  if (Number.isNaN(num)) return 0.9;
+  return Math.min(1, Math.max(0, num));
+}
+
+function sanitizeRelationType(type) {
+  if (VALID_RELATIONS.has(type)) return type;
+  return "related_to";
+}
+
+function sanitizeExtractedData(data, config) {
+  const maxEntities = config.entityExtractionMaxEntities ?? 10;
+  const maxAttrs = config.entityExtractionMaxAttrs ?? 20;
+  
+  if (!data || !Array.isArray(data.entities)) {
+    throw new Error("Invalid extraction: missing entities array");
+  }
+  
+  const entities = [];
+  const seenNames = new Set();
+  
+  for (const rawEntity of data.entities.slice(0, maxEntities)) {
+    if (!rawEntity || typeof rawEntity.name !== "string" || !rawEntity.name.trim()) continue;
+    
+    const name = rawEntity.name.trim();
+    if (seenNames.has(name)) continue;
+    seenNames.add(name);
+    
+    const attrs = [];
+    if (Array.isArray(rawEntity.attrs)) {
+      for (const rawAttr of rawEntity.attrs.slice(0, maxAttrs)) {
+        if (!rawAttr || typeof rawAttr.key !== "string" || typeof rawAttr.value !== "string") continue;
+        attrs.push({
+          key: rawAttr.key.trim(),
+          value: rawAttr.value.trim(),
+          confidence: sanitizeConfidence(rawAttr.confidence)
+        });
+      }
+    }
+    
+    entities.push({
+      name,
+      type: sanitizeType(rawEntity.type),
+      attrs
+    });
+  }
+  
+  const relations = [];
+  if (Array.isArray(data.relations)) {
+    for (const rawRel of data.relations) {
+      if (!rawRel || typeof rawRel.from !== "string" || typeof rawRel.to !== "string") continue;
+      if (!seenNames.has(rawRel.from) || !seenNames.has(rawRel.to)) continue;
+      relations.push({
+        from: rawRel.from,
+        to: rawRel.to,
+        type: sanitizeRelationType(rawRel.type)
+      });
+    }
+  }
+  
+  return { entities, relations };
+}
+
+async function resolveEntity(entity, store) {
+  const existing = store.findEntityByName(entity.name);
+  if (existing) {
+    store.updateEntity(existing.id, {});
+    return existing.id;
+  }
+  const created = store.createEntity({ name: entity.name, type: entity.type });
+  return created.id;
+}
+
+export async function extractEntities(memory, { store, config, callLLM, logger }) {
+  try {
+    if (!memory || !memory.content) {
+      return { ok: false, error: "Invalid memory: missing content" };
+    }
+    
+    const model = config.entityExtractionModel || null;
+    const systemPrompt = buildSystemPrompt(config);
+    const userText = buildUserMessage(memory.content);
+    
+    const messages = [
+      { role: "system", content: [{ type: "text", text: systemPrompt }] },
+      { role: "user", content: [{ type: "text", text: userText }] }
+    ];
+    
+    const options = model ? { model } : {};
+    const llmResponse = await callLLM(messages, options);
+    
+    if (!llmResponse) {
+      return { ok: false, error: "LLM returned empty response" };
+    }
+    
+    const rawData = extractJsonFromText(llmResponse);
+    if (!rawData) {
+      return { ok: false, error: "Failed to parse JSON from LLM response" };
+    }
+    
+    const { entities, relations } = sanitizeExtractedData(rawData, config);
+    
+    const resolvedEntities = [];
+    const entityIdMap = new Map();
+    let skipCount = 0;
+    
+    // Resolve entities
+    for (const entity of entities) {
+      try {
+        const entityId = await resolveEntity(entity, store);
+        entityIdMap.set(entity.name, entityId);
+        resolvedEntities.push({ ...entity, entity_id: entityId });
+      } catch (err) {
+        skipCount++;
+        logger?.warn?.(`[extractor] Failed to resolve entity "${entity.name}":`, err.message);
+      }
+    }
+    
+    // Record attributes
+    const attrs = [];
+    for (const entity of resolvedEntities) {
+      for (const attr of entity.attrs) {
+        try {
+          const saved = store.saveAttr({
+            entity_id: entity.entity_id,
+            attr_key: attr.key,
+            attr_value: String(attr.value),
+            memory_id: memory.id,
+            confidence: attr.confidence,
+            source: "llm_extract"
+          });
+          attrs.push(saved);
+        } catch (err) {
+          skipCount++;
+          logger?.warn?.(`[extractor] Failed to save attr "${attr.key}" for entity "${entity.name}":`, err.message);
+        }
+      }
+    }
+    
+    // Record relations
+    const savedRelations = [];
+    for (const rel of relations) {
+      const fromId = entityIdMap.get(rel.from);
+      const toId = entityIdMap.get(rel.to);
+      if (!fromId || !toId) continue;
+      
+      try {
+        const saved = store.saveRelation({
+          from_entity: fromId,
+          to_entity: toId,
+          relation_type: rel.type,
+          memory_id: memory.id,
+          metadata: { model: model || "default" }
+        });
+        savedRelations.push(saved);
+      } catch (err) {
+        skipCount++;
+        logger?.warn?.(`[extractor] Failed to save relation "${rel.from} -> ${rel.to}":`, err.message);
+      }
+    }
+    
+    return {
+      ok: true,
+      entities: resolvedEntities,
+      attrs,
+      relations: savedRelations,
+      skipped: skipCount
+    };
+    
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}

package/lib/index.js

@@ -13,6 +13,7 @@ import { createEmbedderByProvider } from "./local-embedder.js";
 import { LocalReranker } from "./reranker.js";
 import { createVectorIndex } from "./vector-index.js";
 import { Config } from "./config.js";
+import { extractEntities } from "./entities/extractor.js";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -42,7 +43,7 @@ export const apply = (ctx, config) => {
     store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
   } catch { /* non-fatal */ }
   const mirror = createMirror(memoryDir);
-  const service = createService({ store, mirror, config: cfg });
+  const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
 
   // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
   // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
@@ -164,6 +165,45 @@ export const apply = (ctx, config) => {
     service.setDreamHook(() => dream.maybeSchedule(service));
   }
 
+  // Entity gene extraction (v0.3.0): wire the extractor into the service as a
+  // hook so saveWithDedupe can fire-and-forget an extraction pass on fresh
+  // writes. The service never sees ctx.llm — index.js adapts it here into the
+  // callLLM(messages, options) => Promise<string> contract the extractor
+  // expects, reusing the same ctx.llm.stream consumption pattern as dream.js.
+  // Explicit opt-in only (entityExtractionEnabled defaults to false); any LLM
+  // failure degrades inside the extractor to { ok:false }, never a write error.
+  if (cfg.entityExtractionEnabled && ctx.llm) {
+    const streamEntityText = async (messages, options = {}) => {
+      let route = null;
+      if (options.model) {
+        route = { model: options.model };
+      } else {
+        try {
+          const sel = ctx.agentDefaultModel?.currentSelection?.();
+          if (sel?.provider && sel?.model) route = sel;
+        } catch { /* fall through to no route */ }
+      }
+      let text = "";
+      for await (const chunk of ctx.llm.stream({
+        ...(route ?? {}),
+        purpose: "entity-extract",
+        maxTokens: 4096,
+        messages
+      })) {
+        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;
+    };
+    service.setEntityExtractor((memory) =>
+      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
+        .catch((err) => {
+          ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
+          return { ok: false, error: String(err) };
+        })
+    );
+  }
+
   const disposers = [];
 
   ctx.inject(["systemPrompt"], (promptCtx) => {

package/lib/service.js

@@ -3,7 +3,7 @@ import { TYPE_FILE } from "./mirror.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
-export function createService({ store, mirror, config, onWrite }) {
+export function createService({ store, mirror, config, onWrite, logger }) {
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
   // passed in the constructor). Fired on the same write events as onWrite.
@@ -13,6 +13,14 @@ export function createService({ store, mirror, config, onWrite }) {
   // any content write it fire-and-forgets a re-embed of the row so vector
   // search stays in sync; failures are swallowed inside the embedder.
   let embedder = null;
+
+  // Optional entity extractor, installed via setEntityExtractor after creation
+  // (index.js injects it so the service never depends on the LLM directly).
+  // After a new memory is saved it fire-and-forgets an extraction pass for the
+  // entity gene (v0.3.0); failures are swallowed so a broken extraction never
+  // surfaces as a write failure. Extraction only runs when
+  // config.entityExtractionEnabled is true.
+  let entityExtractor = null;
   let vectorIndex = null;
   let reranker = null;
 
@@ -36,6 +44,25 @@ export function createService({ store, mirror, config, onWrite }) {
     }
   }
 
+  /**
+   * Fire-and-forget entity extraction for a freshly saved memory (entity gene
+   * v0.3.0). Opt-in via config.entityExtractionEnabled; the extractor is
+   * injected as a hook so the service never needs a direct LLM reference.
+   * The hook itself is expected to resolve to { ok:boolean } and never throw;
+   * a thrown rejection is swallowed here as a final fail-safe.
+   */
+  function scheduleEntityExtraction(memory) {
+    if (txDepth > 0) return; // deferred to the transaction's commit
+    if (!config.entityExtractionEnabled || !entityExtractor) return;
+    try {
+      entityExtractor(memory).catch((err) => {
+        logger?.warn?.("entity extraction failed:", err);
+      });
+    } catch (err) {
+      logger?.warn?.("entity extraction failed:", err);
+    }
+  }
+
   /**
    * Cross-encoder rerank over a candidate list (best effort). Reranker
    * failures degrade to the original candidate order — reranking is an
@@ -58,6 +85,48 @@ export function createService({ store, mirror, config, onWrite }) {
     }
   }
 
+  /**
+   * Search for memories attached to a named entity (v0.3.0 Phase 3).
+   * 合并优先级（桉桉确认）：entity_attrs.memory_id 精确关联 = 1.0 > 关键词提及 = 0.7；
+   * attr 命中不覆盖，keyword 只补充召回，最后按 _score 降序取 topK。
+   * @param {string} entityName
+   * @param {object} [options]
+   * @param {number} [options.topK=20]
+   * @returns {any[]}
+   */
+  function searchByEntity(entityName, { topK = 20 } = {}) {
+    const entity = store.findEntityByName(entityName);
+    if (!entity) return [];
+    const attrs = store.getCurrentAttrs(entity.id);
+    const memoryIds = [...new Set(attrs.map((a) => a.memory_id).filter(Boolean))];
+    const attrHits = memoryIds.map((id) => store.getById(id)).filter(Boolean);
+    const keywordHits = store.search(entityName, { limit: topK });
+    const merged = new Map();
+    for (const mem of attrHits) merged.set(mem.id, { ...mem, _source: "entity_attr", _score: 1.0 });
+    for (const mem of keywordHits) {
+      if (!merged.has(mem.id)) merged.set(mem.id, { ...mem, _source: "keyword", _score: 0.7 });
+    }
+    return Array.from(merged.values()).sort((a, b) => b._score - a._score).slice(0, topK);
+  }
+
+  /**
+   * Search for memories by attribute key/value (v0.3.0 Phase 3).
+   * value 为空时由 store.findMemoriesByAttr 返回该 key 的全部有效记忆。
+   * @param {string} key
+   * @param {string | undefined} value
+   * @param {object} [options]
+   * @param {number} [options.topK=20]
+   * @returns {any[]}
+   */
+  function searchByAttr(key, value, { topK = 20 } = {}) {
+    if (!key) return [];
+    // value 可能为 undefined（attr:key 无 = 值）：归一为空串后交给
+    // store.findMemoriesByAttr —— 空 value 契约 = 返回该 attr_key 的全部
+    // 当前有效记忆（v0.3.0，store.js 已实现）。
+    const rows = store.findMemoriesByAttr(key, value ?? "");
+    return rows.slice(0, topK);
+  }
+
   /**
    * Semantic-aware memory search: keyword recall (store.search) plus optional
    * vector recall + rerank. mode:
@@ -85,9 +154,22 @@ export function createService({ store, mirror, config, onWrite }) {
     return base * (0.5 + (row.importance ?? 3) / 10);
   }
 
-  async function searchMemories(query, { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = {}) {
+  async function searchMemories(query, options = {}) {
+    const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = options;
     const q = String(query ?? "").trim();
     if (!q) return [];
+
+    // entity:/attr: 前缀路由（v0.3.0 Phase 3）。entitySearchEnabled 关闭时走原逻辑。
+    if (config?.entitySearchEnabled) {
+      if (q.startsWith("entity:")) {
+        return searchByEntity(q.slice(7).trim(), options);
+      }
+      if (q.startsWith("attr:")) {
+        const [key, value] = q.slice(5).split("=");
+        return searchByAttr(key, value, options);
+      }
+    }
+
     const lim = topK > 0 ? topK : 20;
 
     // Keyword results, decorated with a score so they can be weight-blended
@@ -224,7 +306,7 @@ export function createService({ store, mirror, config, onWrite }) {
       try {
         syncMirror();
       } catch (error) {
-        console.warn("syncMirror failed after transaction:", error);
+        logger?.warn?.("syncMirror failed after transaction:", error);
       }
       notifyWrite();
     }
@@ -261,6 +343,7 @@ export function createService({ store, mirror, config, onWrite }) {
     syncMirror();
     notifyWrite();
     scheduleEmbed(created);
+    scheduleEntityExtraction(created);
     return { action: "created", memory: created };
   }
 
@@ -405,7 +488,7 @@ export function createService({ store, mirror, config, onWrite }) {
     try {
       mirror.sync(reconcileHumanEdits(store.list({ limit: 500, includeForgotten: false })));
     } catch (error) {
-      console.warn("syncMirror failed:", error);
+      logger?.warn?.("syncMirror failed:", error);
     }
   }
 
@@ -417,6 +500,7 @@ export function createService({ store, mirror, config, onWrite }) {
     transaction,
     setDreamHook(fn) { dreamHook = fn; },
     setEmbedder(emb) { embedder = emb; },
+    setEntityExtractor(fn) { entityExtractor = fn; },
     setVectorIndex(vi) { vectorIndex = vi; },
     setReranker(rn) { reranker = rn; },
     setRecallRecorder(fn) { recallRecorder = fn; },
@@ -517,6 +601,13 @@ export function createService({ store, mirror, config, onWrite }) {
     saveConflictPending: (r) => store.saveConflictPending(r),
     listConflictPending: (opts) => store.listConflictPending(opts),
     resolveConflictPending: (id, o) => store.resolveConflictPending(id, o),
-    countConflictPending: () => store.countConflictPending()
+    countConflictPending: () => store.countConflictPending(),
+    // Entity gene (v0.3.0) passthroughs for the autoDream apply path
+    // (applyDecisions): records supersedes relations after an update and
+    // migrates entity_attrs on merge. Bookkeeping writes like the audit
+    // passthroughs above — never write-hook-triggering memory mutations.
+    saveRelation: (r) => store.saveRelation(r),
+    getAttrsByMemory: (id) => store.getAttrsByMemory(id),
+    migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };
 }