@modusensus/dsh-mneme 0.8.3 → 0.8.5

package/lib/entities/extractor.js

@@ -1,249 +1,249 @@
-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 systemPrompt = buildSystemPrompt(config);
-    const userText = buildUserMessage(memory.content);
-
-    const messages = [
-      { role: "system", content: [{ type: "text", text: systemPrompt }], source: { kind: "plugin", plugin: "dsh-mneme" } },
-      { role: "user", content: [{ type: "text", text: userText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
-    ];
-
-    // Issue #109: optional provider/model override + reasoning effort are
-    // passed through to callLLM's options; the index.js adapter maps them onto
-    // the route (or falls back to the caller's default model). Empty provider/
-    // model both mean "use the caller default".
-    const options = {};
-    if (config.entityExtractionProvider) options.provider = config.entityExtractionProvider;
-    if (config.entityExtractionModel) options.model = config.entityExtractionModel;
-    const reasoning = config.entityExtractionReasoning;
-    if (reasoning && reasoning !== "none") options.reasoningEffort = reasoning;
-    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: options.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) };
-  }
-}
+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 systemPrompt = buildSystemPrompt(config);
+    const userText = buildUserMessage(memory.content);
+
+    const messages = [
+      { role: "system", content: [{ type: "text", text: systemPrompt }], source: { kind: "plugin", plugin: "dsh-mneme" } },
+      { role: "user", content: [{ type: "text", text: userText }], source: { kind: "plugin", plugin: "dsh-mneme" } }
+    ];
+
+    // Issue #109: optional provider/model override + reasoning effort are
+    // passed through to callLLM's options; the index.js adapter maps them onto
+    // the route (or falls back to the caller's default model). Empty provider/
+    // model both mean "use the caller default".
+    const options = {};
+    if (config.entityExtractionProvider) options.provider = config.entityExtractionProvider;
+    if (config.entityExtractionModel) options.model = config.entityExtractionModel;
+    const reasoning = config.entityExtractionReasoning;
+    if (reasoning && reasoning !== "none") options.reasoningEffort = reasoning;
+    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: options.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/guide.js

@@ -0,0 +1,44 @@
+// #249（第一批）：能力说明——写给模型的「怎么用这套记忆」，不是给用户的文案。
+//
+// 为什么英文、且只留一份正本：注入指引的参照实现全部用英文（ACP 的
+// ACP_SYSTEM_PROMPT + HOW_TO_COMPRESS_RULES、mnemon 的 ROUTING_GUIDANCE、
+// 宿主压缩摘要规则），仓库既有先例也是 src/tools.js 的工具描述硬编码英文。
+// src/lang.js 的 memory.language 管的是「生成出来的记忆内容与块内标题」，与本
+// 模块是两件事，故不并入 STR、不做 zh/en 双写（双写只会让两份文本日后漂移）。
+//
+// 两个承载位（#249 §5）：①工具描述——常驻、零注入成本，放「何时用这个工具」
+// 这类单工具指引（TOOL_GUIDE）；②系统提示段 order 150——放工具描述装不下的
+// 总则（优先序、何时查 / 何时写 / 何时 no-op）。该段必须同会话内稳定，否则
+// 每轮变化会作废其后的前缀缓存，因此这里全是常量，不含任何运行时插值。
+//
+// 前缀 `[dsh-mneme memory]` 是机械校验用的：测试按它断言「只在开时出现、且不
+// 逐轮复读」，也让维护者能一眼认出这段文本的归属。
+
+const SECTION_LINES = [
+  "[dsh-mneme memory] Read once; it applies to every turn of this session.",
+  "1. Precedence: the current instruction and the repository's actual state outrank any stored memory. " +
+    "When a memory contradicts either, check the instruction or the repository itself before relying on it — memory_search " +
+    "searches stored memories only, so it finds earlier context, never the present state. Never treat an old memory as current fact.",
+  "2. Recall on demand: call memory_search when the task depends on earlier decisions, user preferences, or project history " +
+    "that is not already in context. Do not search for facts you can read directly from the repository.",
+  "3. Write back sparingly: use memory_save for durable, cross-session value — a preference, a decision with its rationale, " +
+    "an engineering constraint, a pitfall with its root cause. Trivial single-turn work is not worth a memory.",
+  "4. When unsure, do nothing. Not acting is a valid outcome: a useless memory is paid for by every future session.",
+  "5. Prefer the reversible tools. memory_archive hides an entry from lists, search, injection and consolidation, and " +
+    "memory_forget suppresses it from injection, search results and lists — both are recoverable. memory_delete is permanent, " +
+    "so reach for it only when an entry is wrong or unwanted, not merely stale."
+];
+
+/** 系统提示段（order 150）的总则文本。常量：同会话内稳定是硬约束。 */
+export const MEMORY_GUIDE_SECTION = SECTION_LINES.join("\n");
+
+/** 单工具判断指引，追加到对应工具描述尾部（`injectGuidanceEnabled` 开启时）。 */
+export const TOOL_GUIDE = {
+  memory_search:
+    " Use this when the task depends on earlier decisions, preferences, or project history that is not already in context, " +
+    "or to look for a newer memory behind one that seems stale. " +
+    "Skip it for facts you can read directly from the repository.",
+  memory_save:
+    " Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
+    "a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure, do not save."
+};