@modusensus/dsh-mneme 0.2.11 → 0.3.1

package/lib/store.js

@@ -118,6 +118,52 @@ CREATE TABLE IF NOT EXISTS conflict_pending (
   resolved_winner TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_conflict_pending_unresolved ON conflict_pending(resolved_at);
+
+-- entity gene (v0.3.0): named entities mentioned across memories, with
+-- time-boxed attributes (valid_from → valid_until) and typed relations.
+-- Attributes follow the snapshot style: saveAttr invalidates the previous
+-- value for the same entity+key before inserting a new row, so the current
+-- value is always the row with valid_until IS NULL.
+CREATE TABLE IF NOT EXISTS entities (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  type TEXT,
+  first_seen TEXT NOT NULL,
+  last_seen TEXT NOT NULL,
+  mention_count INTEGER DEFAULT 1,
+  canonical_memory_id TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+
+CREATE TABLE IF NOT EXISTS entity_attrs (
+  id TEXT PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  attr_key TEXT NOT NULL,
+  attr_value TEXT NOT NULL,
+  memory_id TEXT,
+  valid_from TEXT NOT NULL,
+  valid_until TEXT,
+  confidence REAL DEFAULT 1.0,
+  source TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_attrs_entity ON entity_attrs(entity_id);
+CREATE INDEX IF NOT EXISTS idx_attrs_key ON entity_attrs(attr_key);
+CREATE INDEX IF NOT EXISTS idx_attrs_valid ON entity_attrs(valid_from, valid_until);
+CREATE INDEX IF NOT EXISTS idx_attrs_memory ON entity_attrs(memory_id);
+
+CREATE TABLE IF NOT EXISTS entity_relations (
+  id TEXT PRIMARY KEY,
+  from_entity TEXT NOT NULL,
+  to_entity TEXT NOT NULL,
+  relation_type TEXT NOT NULL,
+  memory_id TEXT,
+  created_at TEXT NOT NULL,
+  metadata TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_relations_from ON entity_relations(from_entity);
+CREATE INDEX IF NOT EXISTS idx_relations_to ON entity_relations(to_entity);
+CREATE INDEX IF NOT EXISTS idx_relations_type ON entity_relations(relation_type);
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
@@ -228,6 +274,55 @@ function toRecallRun(row) {
   };
 }
 
+function toEntity(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    name: row.name,
+    type: row.type ?? undefined,
+    first_seen: row.first_seen,
+    last_seen: row.last_seen,
+    mention_count: row.mention_count,
+    canonical_memory_id: row.canonical_memory_id ?? undefined
+  };
+}
+
+function toAttr(row) {
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    entity_id: row.entity_id,
+    attr_key: row.attr_key,
+    attr_value: row.attr_value,
+    memory_id: row.memory_id ?? undefined,
+    valid_from: row.valid_from,
+    valid_until: row.valid_until ?? undefined,
+    confidence: row.confidence,
+    source: row.source ?? undefined
+  };
+}
+
+function toRelation(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,
+    from_entity: row.from_entity,
+    to_entity: row.to_entity,
+    relation_type: row.relation_type,
+    memory_id: row.memory_id ?? undefined,
+    created_at: row.created_at,
+    metadata
+  };
+}
+
 function parseJsonArray(raw) {
   try {
     const arr = JSON.parse(raw);
@@ -805,6 +900,190 @@ export function createStore(path) {
     return stats;
   }
 
+  // --- entity gene: named entities + time-boxed attrs + relations (v0.3.0) --
+
+  /**
+   * Create a named entity. A fresh mention always records first_seen = now;
+   * repeated sightings should call updateEntity (which bumps mention_count and
+   * refreshes last_seen) rather than creating duplicate rows.
+   */
+  function createEntity({ name, type }) {
+    const id = randomUUID();
+    const now = nowIso();
+    db.prepare(
+      `INSERT INTO entities (id, name, type, first_seen, last_seen, mention_count, canonical_memory_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, name, type ?? null, now, now, 1, null);
+    return toEntity(db.prepare("SELECT * FROM entities WHERE id = ?").get(id));
+  }
+
+  function findEntityByName(name) {
+    return toEntity(db.prepare("SELECT * FROM entities WHERE name = ?").get(name));
+  }
+
+  function findEntityById(id) {
+    return toEntity(db.prepare("SELECT * FROM entities WHERE id = ?").get(id));
+  }
+
+  /**
+   * Apply a partial update to an entity, always refreshing last_seen. The
+   * mention counter increments on every sighting unless the caller overrides
+   * it explicitly via patch.mention_count (e.g. to correct a count).
+   */
+  function updateEntity(id, patch) {
+    const old = findEntityById(id);
+    if (!old) return undefined;
+    const has = (k) => Object.prototype.hasOwnProperty.call(patch, k);
+    const name = has("name") ? patch.name : old.name;
+    const type = has("type") ? patch.type : old.type;
+    const canonical_memory_id = has("canonical_memory_id")
+      ? patch.canonical_memory_id
+      : old.canonical_memory_id;
+    const mention_count = has("mention_count")
+      ? patch.mention_count
+      : (old.mention_count ?? 1) + 1;
+    const now = nowIso();
+    db.prepare(
+      `UPDATE entities SET name = ?, type = ?, last_seen = ?, mention_count = ?, canonical_memory_id = ? WHERE id = ?`
+    ).run(name, type ?? null, now, mention_count, canonical_memory_id ?? null, id);
+    return findEntityById(id);
+  }
+
+  /**
+   * Record an attribute value for an entity. The previous value for the same
+   * entity+key is invalidated (valid_until = now) before the new row is
+   * inserted, so exactly one row per entity+key is current (valid_until IS NULL).
+   */
+  function saveAttr({ entity_id, attr_key, attr_value, memory_id, confidence, source }) {
+    const now = nowIso();
+    invalidateOldAttr(entity_id, attr_key, now);
+    const id = randomUUID();
+    db.prepare(
+      `INSERT INTO entity_attrs (id, entity_id, attr_key, attr_value, memory_id, valid_from, valid_until, confidence, source)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, entity_id, attr_key, attr_value, memory_id ?? null, now, null, confidence ?? 1.0, source ?? null);
+    return toAttr(db.prepare("SELECT * FROM entity_attrs WHERE id = ?").get(id));
+  }
+
+  /** Mark every currently-valid attr row for entityId+attrKey as expired. Returns rows changed. */
+  function invalidateOldAttr(entityId, attrKey, now) {
+    return db.prepare(
+      `UPDATE entity_attrs SET valid_until = ? WHERE entity_id = ? AND attr_key = ? AND valid_until IS NULL`
+    ).run(now, entityId, attrKey).changes;
+  }
+
+  /** Only the live value per attr_key (valid_until IS NULL). */
+  function getCurrentAttrs(entityId) {
+    return db.prepare(
+      "SELECT * FROM entity_attrs WHERE entity_id = ? AND valid_until IS NULL"
+    ).all(entityId).map(toAttr);
+  }
+
+  /** Full history per attr_key, oldest first. */
+  function getAttrHistory(entityId) {
+    return db.prepare(
+      "SELECT * FROM entity_attrs WHERE entity_id = ? ORDER BY valid_from"
+    ).all(entityId).map(toAttr);
+  }
+
+  /**
+   * All attr rows carrying a reference to the given memory (any valid state),
+   * oldest first. Used by autoDream's update path to record what an update
+   * superseded (v0.3.0 Phase 4 / 4.3.1).
+   */
+  function getAttrsByMemory(memoryId) {
+    return db.prepare(
+      "SELECT * FROM entity_attrs WHERE memory_id = ? ORDER BY valid_from ASC"
+    ).all(memoryId).map(toAttr);
+  }
+
+  /**
+   * Memories carrying a currently-valid attr matching key=value (deduped).
+   * When value is empty/undefined, the attr_value filter is dropped and every
+   * currently-valid memory for that attr_key is returned — the "attr:key"
+   * (no =value) contract, v0.3.0. Only live rows (valid_until IS NULL) with a
+   * memory reference participate, and each memory appears at most once.
+   */
+  function findMemoriesByAttr(key, value) {
+    const empty = value === undefined || value === null || value === "";
+    const sql = empty
+      ? `SELECT DISTINCT memory_id FROM entity_attrs
+         WHERE attr_key = ? AND valid_until IS NULL
+           AND memory_id IS NOT NULL AND memory_id != ''`
+      : `SELECT DISTINCT memory_id FROM entity_attrs
+         WHERE attr_key = ? AND attr_value = ? AND valid_until IS NULL
+           AND memory_id IS NOT NULL AND memory_id != ''`;
+    const params = empty ? [key] : [key, value];
+    const rows = db.prepare(sql).all(...params);
+    const memories = [];
+    const stmt = db.prepare("SELECT * FROM memories WHERE id = ?");
+    for (const { memory_id } of rows) {
+      const row = stmt.get(memory_id);
+      if (row) memories.push(toRow(row));
+    }
+    return memories;
+  }
+
+  /**
+   * Record a typed relation between two entities. metadata (optional) is a
+   * free-form JSON blob describing the relation. Relations are append-only.
+   */
+  function saveRelation({ from_entity, to_entity, relation_type, memory_id, metadata }) {
+    const id = randomUUID();
+    const now = nowIso();
+    const metaStr = metadata === undefined
+      ? null
+      : typeof metadata === "string"
+        ? metadata
+        : JSON.stringify(metadata);
+    db.prepare(
+      `INSERT INTO entity_relations (id, from_entity, to_entity, relation_type, memory_id, created_at, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, from_entity, to_entity, relation_type, memory_id ?? null, now, metaStr);
+    return toRelation(db.prepare("SELECT * FROM entity_relations WHERE id = ?").get(id));
+  }
+
+  /**
+   * Re-point every attr row whose memory_id is fromMemoryId to toMemoryId
+   * (autoDream merge migration, v0.3.0 Phase 4 / 4.3.2). When the keeper
+   * already carries a live attr for the same entity+key, the source row is
+   * superseded and invalidated instead (the keeper's value wins). Returns
+   * { migrated, invalidated }.
+   */
+  function migrateAttrsToMemory(fromMemoryId, toMemoryId, now) {
+    let migrated = 0;
+    let invalidated = 0;
+    const attrs = db.prepare(
+      "SELECT * FROM entity_attrs WHERE memory_id = ?"
+    ).all(fromMemoryId);
+    for (const attr of attrs) {
+      // 仅当 keeper 已有同 entity+key 的当前有效属性才视为被替代（限定 memory_id，
+      // 避免把 loser 自身的 live 行误判为 keeper 行）。
+      const keeperLive = db.prepare(
+        "SELECT id FROM entity_attrs WHERE entity_id = ? AND attr_key = ? AND valid_until IS NULL AND memory_id = ?"
+      ).get(attr.entity_id, attr.attr_key, toMemoryId);
+      if (keeperLive) {
+        db.prepare(
+          "UPDATE entity_attrs SET valid_until = ? WHERE id = ?"
+        ).run(now, attr.id);
+        invalidated++;
+      } else {
+        db.prepare(
+          "UPDATE entity_attrs SET memory_id = ? WHERE id = ?"
+        ).run(toMemoryId, attr.id);
+        migrated++;
+      }
+    }
+    return { migrated, invalidated };
+  }
+
+  /** Relations where the entity appears on either side (from or to). */
+  function getRelations(entityId) {
+    return db.prepare(
+      "SELECT * FROM entity_relations WHERE from_entity = ? OR to_entity = ?"
+    ).all(entityId, entityId).map(toRelation);
+  }
+
   return {
     db,
     count,
@@ -840,6 +1119,19 @@ export function createStore(path) {
     listConflictPending,
     resolveConflictPending,
     countConflictPending,
+    createEntity,
+    findEntityByName,
+    findEntityById,
+    updateEntity,
+    saveAttr,
+    invalidateOldAttr,
+    getCurrentAttrs,
+    getAttrHistory,
+    getAttrsByMemory,
+    findMemoriesByAttr,
+    saveRelation,
+    migrateAttrsToMemory,
+    getRelations,
     close() {
       db.close();
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 6 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.2.11",
+  "version": "0.3.1",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/src/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/src/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/src/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/src/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) };
+  }
+}