dsh-memu-memory 1.2.0 → 1.2.2

package/lib/graph.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
-import { indexDir, readJsonStrict, writeJson, withFileLock, stamp } from './paths.js'
-import { loadPrivateIndex, updatePrivateIndex, newMemoryId } from './state.js'
+import { indexDir, readJsonStrict, writeJson, withFileLock, stamp, warn } from './paths.js'
+import { loadPrivateIndex, updatePrivateIndex, newMemoryId, listLibraries } from './state.js'
 import { resolveLibrary, sessionIdOf, visibleToSession, isMemoryEligible, decayStrength } from './memory.js'
 
 export const LINK_KINDS = ['relation', 'commitment', 'event', 'person', 'conflict']
@@ -22,13 +22,42 @@ function allowed(entry, exec) {
   return !sessionIdOf(exec) || (isMemoryEligible(entry, { automatic: true }) && visibleToSession(entry, sessionIdOf(exec)))
 }
 
+/**
+ * Entity listing with the derived `linked` flag (§6.4 包 D). The visibility rule
+ * is unchanged: without a session every entity comes back (GraphPanel calls it
+ * exactly that way), with a session only entities reachable from visible memory
+ * links are listed. What is new is the classification:
+ *   * `linked` = referenced by an entry's links[] OR by a relationship snapshot.
+ *     A snapshot counts — an entity with only a relationship and no memory link
+ *     is history, not an orphan, and must not be misjudged as one.
+ *   * With a session, a snapshot only counts when its evidenceIds include a
+ *     memory visible in this conversation; without a session every snapshot
+ *     counts (there is nobody to hide it from).
+ * `linked` is derived on the fly and never written back to the entities file —
+ * the startup prune (pruneOrphanEntitiesAll) stays the sole collector.
+ */
 export function listEntities(args) {
   const scope = scopeFor(args)
   const store = readEntities(scope.libraryId)
   const index = loadPrivateIndex(scope.libraryId)
-  const visible = new Set(Object.values(index.entries)
-    .filter(entry => allowed(entry, args.exec)).flatMap(entry => (entry.links || []).map(link => link.to)))
-  const items = Object.values(store.entities).filter(entity => !sessionIdOf(args.exec) || visible.has(entity.id))
+  const sessionId = sessionIdOf(args.exec)
+  const linked = new Set()
+  for (const entry of Object.values(index.entries)) {
+    if (!allowed(entry, args.exec)) continue
+    for (const link of entry.links || []) linked.add(link.to)
+  }
+  for (const rel of Object.values(store.relationships || {})) {
+    if (sessionId) {
+      const evidenceVisible = (Array.isArray(rel?.evidenceIds) ? rel.evidenceIds : [])
+        .some(id => { const entry = index.entries[id]; return Boolean(entry) && allowed(entry, args.exec) })
+      if (!evidenceVisible) continue
+    }
+    if (rel?.fromId) linked.add(rel.fromId)
+    if (rel?.toId) linked.add(rel.toId)
+  }
+  const items = Object.values(store.entities)
+    .filter(entity => !sessionId || linked.has(entity.id))
+    .map(entity => ({ ...entity, linked: linked.has(entity.id) }))
   return { items, total: items.length }
 }
 
@@ -60,6 +89,16 @@ export function restoreGraphData(libraryId, data, memoryIdMap) {
     if (!evidenceIds.length) continue
     updateRelationship({ libraryId, fromId: entityMap[relationship.fromId], toId: entityMap[relationship.toId], state: relationship.state, evidenceIds, reason: relationship.reason || 'Imported relationship with explicit evidence.' })
   }
+  // A backup carries the whole entity store, but only the memories that made it
+  // through the export/import mapping come back, so entities nothing points at
+  // any more would sit in the file forever as invisible weight. Collect them
+  // once the remap is done; a prune failure must not fail a restore that
+  // already succeeded, and the startup sweep would catch it on the next launch.
+  try {
+    pruneOrphanEntities(scope.libraryId)
+  } catch (error) {
+    warn(`orphan entity prune after graph restore skipped: ${error?.message || error}`)
+  }
 }
 
 export function createEntity({ exec, libraryId, name, kind = 'person', aliases = [] }) {
@@ -102,30 +141,154 @@ export function renameEntity({ libraryId, entityId, name, aliases = [] }) {
   })
 }
 
-export function linkEntries({ exec, libraryId, fromId, toId, kind, note, confidence = 0.7 }) {
+// What keeps an entity alive. Edges only live in one direction: an entry's
+// links[] names the entity, the entity stores nothing back. On top of that,
+// relationship snapshots (same file, keyed by the endpoint pair) describe the
+// pair with history and evidence that outlive the individual entries — deleting
+// an endpoint would leave a snapshot whose endpoints no longer resolve, so a
+// snapshot counts as a reference too. An entity referenced by neither is an
+// *orphan*: unreachable except as a graph placeholder, and safe to collect.
+// Orphans come from old builds whose permanent delete dropped the memory row
+// without cascading, and from partial backups.
+
+/**
+ * Remove every entity in one library that no entry links to and no relationship
+ * snapshot references. Idempotent: on healthy data it writes nothing. Returns
+ * `{ removed, total }` with the removed entity ids.
+ */
+export function pruneOrphanEntities(libraryId) {
+  const scope = scopeFor({ libraryId })
+  const file = entitiesPath(scope.libraryId)
+  return withFileLock(file, () => {
+    const store = readEntities(scope.libraryId)
+    const ids = Object.keys(store.entities)
+    if (!ids.length) return { removed: [], total: 0 }
+    const referenced = new Set()
+    for (const entry of Object.values(loadPrivateIndex(scope.libraryId).entries || {})) {
+      for (const link of entry.links || []) referenced.add(link.to)
+    }
+    for (const relationship of Object.values(store.relationships || {})) {
+      referenced.add(relationship.fromId)
+      referenced.add(relationship.toId)
+    }
+    const removed = ids.filter(id => !referenced.has(id))
+    // Write only when something actually goes, so the common case never touches
+    // the file (mtime-based caches, backups and concurrent readers all benefit).
+    if (removed.length) {
+      for (const id of removed) delete store.entities[id]
+      writeJson(file, store)
+    }
+    return { removed, total: ids.length }
+  })
+}
+
+/**
+ * The startup sweep: run pruneOrphanEntities over every active library. One
+ * corrupt store must not stop the rest, so per-library failures are collected
+ * instead of thrown; the caller decides how to log them. Archived libraries are
+ * deliberately left alone (frozen user data — restoring one runs the prune via
+ * restoreGraphData anyway). Returns `{ scanned, removed, failed }`.
+ */
+export function pruneOrphanEntitiesAll() {
+  const libraries = listLibraries()
+  const result = { scanned: libraries.length, removed: 0, failed: [] }
+  for (const library of libraries) {
+    try {
+      result.removed += pruneOrphanEntities(library.id).removed.length
+    } catch (error) {
+      result.failed.push({ libraryId: library.id, error: String(error?.message || error) })
+    }
+  }
+  return result
+}
+
+/**
+ * Delete an entity. This is graph bookkeeping, not a memory write: the entity
+ * row goes, no memory text is touched. An entity still referenced by links or
+ * relationship snapshots is refused by default — silently deleting it would
+ * turn every one of those edges into a `[deleted]` placeholder and rewrite what
+ * those memories are *about*. `force` deletes through that: inbound links are
+ * removed from every entry (not session-filtered — a link left behind in an
+ * entry this conversation cannot see would dangle exactly the way this guard
+ * exists to prevent, and the entry text itself is untouched) and relationship
+ * snapshots on the endpoints are dropped with their history, which is the loss
+ * `force` is asking for. Index links are cleaned before the entity row so a
+ * crash between the two writes leaves at worst a collectable orphan, never a
+ * link to an entity that is already gone.
+ */
+export function deleteEntity({ exec, libraryId, entityId, force = false }) {
+  const scope = scopeFor({ exec, libraryId })
+  if (!entityId || typeof entityId !== 'string') throw new Error('entityId is required')
+  const file = entitiesPath(scope.libraryId)
+  return withFileLock(file, () => {
+    const store = readEntities(scope.libraryId)
+    if (!store.entities[entityId]) throw new Error('unknown entity')
+    const index = loadPrivateIndex(scope.libraryId)
+    let inbound = 0
+    for (const entry of Object.values(index.entries || {})) {
+      for (const link of entry.links || []) if (link.to === entityId) inbound += 1
+    }
+    const relationshipKeys = Object.keys(store.relationships || {})
+      .filter(key => { const [from, to] = JSON.parse(key); return from === entityId || to === entityId })
+    if ((inbound || relationshipKeys.length) && !force) {
+      const parts = []
+      if (inbound) parts.push(`${inbound} link(s) point at it`)
+      if (relationshipKeys.length) parts.push(`${relationshipKeys.length} relationship snapshot(s) reference it`)
+      throw new Error(`entity is still referenced: ${parts.join(' and ')}; remove the links first or pass force to delete the entity with them`)
+    }
+    let removedLinks = 0
+    if (inbound) {
+      updatePrivateIndex(scope.libraryId, fresh => {
+        for (const entry of Object.values(fresh.entries)) {
+          if (!Array.isArray(entry.links) || !entry.links.some(link => link.to === entityId)) continue
+          const kept = entry.links.filter(link => link.to !== entityId)
+          removedLinks += entry.links.length - kept.length
+          entry.links = kept
+        }
+      })
+    }
+    for (const key of relationshipKeys) delete store.relationships[key]
+    delete store.entities[entityId]
+    writeJson(file, store)
+    return { entityId, deleted: true, removedLinks, removedRelationships: relationshipKeys.length }
+  })
+}
+
+/**
+ * Write one directed link from a memory to a memory or entity.
+ *
+ * `source` records who made the edge: 'auto' (private auto-association / entity
+ * hub, §5.3–5.5) or 'user'. Anything else is omitted rather than stored, so the
+ * field never turns into a free-form label and an old link without it keeps
+ * reading as a model/user link. Replacement stays idempotent: the same
+ * (to, kind) pair is overwritten in place instead of appended.
+ */
+export function linkEntries({ exec, libraryId, fromId, toId, kind, note, confidence = 0.7, source }) {
   const scope = scopeFor({ exec, libraryId })
   if (!LINK_KINDS.includes(kind)) throw new Error(`link kind must be ${LINK_KINDS.join(', ')}`)
   const reason = String(note || '').trim()
   if (reason.replace(/\s/g, '').length < 8 || reason.length > 500) throw new Error('link note must contain 8-500 characters explaining the evidence')
   if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error('link confidence must be between 0 and 1')
   if (fromId === toId) throw new Error('a memory cannot link to itself')
+  const linkSource = source === 'auto' || source === 'user' ? source : null
   const entities = readEntities(scope.libraryId).entities
   let result
   updatePrivateIndex(scope.libraryId, index => {
-    const source = index.entries[fromId]
+    const origin = index.entries[fromId]
     const target = index.entries[toId]
-    if (!source || !allowed(source, exec) || target && !allowed(target, exec)) throw new Error('unknown or inaccessible memory')
+    if (!origin || !allowed(origin, exec) || target && !allowed(target, exec)) throw new Error('unknown or inaccessible memory')
     if (!target && !entities[toId]) throw new Error('link target must be an existing memory or entity')
     if (kind === 'person' && entities[toId]?.kind !== 'person') throw new Error('person links must target a person entity')
-    const links = Array.isArray(source.links) ? source.links : []
+    const links = Array.isArray(origin.links) ? origin.links : []
     result = { to: toId, kind, note: reason, confidence, createdAt: stamp() }
+    if (linkSource) result.source = linkSource
     const found = links.findIndex(link => link.to === toId && link.kind === kind)
     if (found >= 0) links[found] = result
     else {
       if (links.length >= 100) throw new Error('memory already has 100 links; review the existing connections first')
       links.push(result)
     }
-    source.links = links
+    origin.links = links
   })
   return { from: fromId, ...result }
 }
@@ -145,7 +308,7 @@ export function unlinkEntry({ libraryId, fromId, toId, kind }) {
   return { removed }
 }
 
-export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 200 }) {
+export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 200, includeOrphans = false }) {
   const scope = scopeFor({ exec, libraryId })
   const index = loadPrivateIndex(scope.libraryId)
   const entities = readEntities(scope.libraryId).entities
@@ -159,7 +322,9 @@ export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 2
       if (!LINK_KINDS.includes(link.kind)) continue
       // A deleted target gets a placeholder; an inaccessible target gets no hint.
       if (index.entries[link.to] && !visible.has(link.to)) continue
-      const edge = { from, to: link.to, kind: link.kind, note: link.note, confidence: link.confidence ?? 0.7 }
+      // source is display metadata only ('auto' edges get a badge in the graph
+      // view); an older link without the field reports null instead of undefined.
+      const edge = { from, to: link.to, kind: link.kind, note: link.note, confidence: link.confidence ?? 0.7, source: link.source || null }
       edges.push(edge)
       for (const [a, b] of [[from, link.to], [link.to, from]]) {
         if (!adjacency.has(a)) adjacency.set(a, new Set())
@@ -181,9 +346,16 @@ export function getGraph({ exec, libraryId, focusId = null, depth = 1, limit = 2
       frontier = next
     }
   } else {
+    // Orphan entities — no edge from any visible entry — are hidden by default.
+    // After the permanent-delete cascade and pruneOrphanEntities they should not
+    // exist on disk at all; a leftover from old data is invisible weight, and a
+    // session-scoped viewer already never saw them (the check below). Pass
+    // includeOrphans to see what an old entities.json still holds. An explicit
+    // focusId always wins: asking for a node by id is intent, not browsing.
     for (const id of [...visible, ...Object.keys(entities), ...adjacency.keys()]) {
       if (selected.size >= cap) break
       if (sessionIdOf(exec) && !visible.has(id) && !adjacency.has(id)) continue
+      if (!includeOrphans && entities[id] && !adjacency.has(id)) continue
       selected.add(id)
     }
   }
@@ -207,8 +379,12 @@ export function recallRelations(libraryId, index, id, sessionId) {
       const to = from === id ? link.to : from
       const target = index.entries[to]
       if (target && (!isMemoryEligible(target, { automatic: true }) || !visibleToSession(target, sessionId))) continue
-      if (!target && !entities[to]) continue
-      out.push({ id: to, title: target?.title || entities[to]?.name, kind: link.kind, note: String(link.note || '').slice(0, 80), confidence: link.confidence ?? 0.7 })
+      // A dangling edge (entry and entity both gone) used to be dropped here
+      // while getGraph rendered the same disk state as a [deleted] placeholder —
+      // the two views disagreed. Both now report the edge and mark it `missing`;
+      // the caller filters if it wants the old silence back.
+      const missing = !target && !entities[to]
+      out.push({ id: to, title: target?.title || entities[to]?.name || '[deleted]', kind: link.kind, note: String(link.note || '').slice(0, 80), confidence: link.confidence ?? 0.7, missing })
     }
   }
   return out.sort((a, b) => b.confidence - a.confidence).slice(0, 2)

package/lib/inbound.js

@@ -155,6 +155,25 @@ export function hasPendingInbound(sessionId) {
   return Boolean(inbound?.pending?.length) && !(Date.parse(inbound.retryAt || '') > Date.now())
 }
 
+/**
+ * 本轮真实用户消息的纯文本，直接取自持久化的 inbound journal（pending 队列）。
+ *
+ * 词典命中的唯一文本源（docs/memory-semantics.md §8.13）：队列里的每一条都是
+ * ingestInboundBatch 校验过的显式人类消息，所以插件通知、工具结果、assistant
+ * 自言自语结构上进不来。调用方要在 noteNativeUserMessages 把原生消息从 pending
+ * 摘走**之前**取（inject.js 的顺序就是这样的）。
+ */
+export function inboundUserTexts(binding) {
+  const pending = Array.isArray(binding?.inbound?.pending) ? binding.inbound.pending : []
+  return pending
+    .map(item => (Array.isArray(item?.content) ? item.content : [])
+      .filter(block => block?.type === 'text' && typeof block.text === 'string')
+      .map(block => block.text.trim())
+      .filter(Boolean)
+      .join(' '))
+    .filter(Boolean)
+}
+
 export async function pendingInbound(sessionId, ctx, session) {
   const first = journal(getSessionBinding(sessionId)).pending
   // Persisted queues can recover media collection after a restart.

package/lib/index.js

@@ -5,7 +5,8 @@ import { registerRpc } from './rpc.js'
 import { registerCycle } from './cycle.js'
 import { syncPromptDefaults } from './prompts.js'
 import { ensureEngine, engineStatus, ENGINE_VERSION } from './engine.js'
-import { getSettings, getMemoryBackend, backupDatabases, flushState } from './state.js'
+import { getSettings, getMemoryBackend, backupDatabases, flushState, listLibraries } from './state.js'
+import { pruneOrphanEntitiesAll } from './graph.js'
 import { closeEmbeddingWorkers } from './local-embedding-manager.js'
 import { bootstrapLocalVector } from './local-vector-service.js'
 import { vectorStatus } from './vector-profile.js'
@@ -62,6 +63,35 @@ function startEngineBootstrap(ctx) {
   }
 }
 
+// 兜底扫描（老数据升级）：旧版本的永久删除只删条目本身，别的条目 links 里指向它的
+// 入边和 entities.json 里的实体节点会留下来，restoreGraphData 的部分恢复也会。这里在
+// 启动后延迟跑一次全库 pruneOrphanEntitiesAll。选「每次启动延迟扫」而不是「首次
+// getGraph + 持久化已清理标记」：扫描只是对小 JSON 文件的读 + 偶尔一次原子写，健康
+// 数据零写入（no-op），幂等且能在任何一次删除路径将来回归时自愈；持久化标记省不下
+// 多少成本，反而多一个「标记存在但数据又坏了」的状态要维护。延迟 4 秒（在 1.5s 引擎
+// 引导与 2.5s 向量引导之后）让激活路径零阻塞；新安装没有库、没有实体，扫描直接 no-op。
+// 单库失败只收集不抛出，整段失败只 warn —— 加载绝不能被一次清理绊倒。
+function startOrphanEntitySweep(ctx) {
+  try {
+    const timer = setTimeout(() => {
+      try {
+        const result = pruneOrphanEntitiesAll()
+        for (const failure of result.failed) {
+          try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep skipped ${failure.libraryId}: ${failure.error}`) } catch {}
+        }
+        if (result.removed > 0) {
+          try { ctx.logger?.info?.(`dsh-memu-memory: orphan entity sweep collected ${result.removed} node(s) across ${result.scanned} library(ies)`) } catch {}
+        }
+      } catch (error) {
+        try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep failed: ${error?.message || error}`) } catch {}
+      }
+    }, 4000)
+    timer.unref?.()
+  } catch (error) {
+    try { ctx.logger?.warn?.(`dsh-memu-memory: orphan entity sweep skipped: ${error?.message || error}`) } catch {}
+  }
+}
+
 export function apply(ctx, config) {
   // A conversation that names an agent preset composes its model-facing plugin set from
   // that preset's cordis.yml alone, and that subtree never delivers `agent/pre-step` to
@@ -121,6 +151,8 @@ export function apply(ctx, config) {
     registerRpc(ctx)
     startEngineBootstrap(ctx)
     startLocalVectorBootstrap(ctx)
+    // 进程级清理：preset 挂载共享同一个数据目录，只由拥有全局表面的实例扫一次。
+    startOrphanEntitySweep(ctx)
   }
 
   // The embedding worker is a process-global singleton, so it outlives any single