Skip to content

Commit 1723d67

Browse files
committed
Merge remote-tracking branch 'origin/main' into feat/graph-inject-budget
# Conflicts: # dsh-mneme/CHANGELOG.md # dsh-mneme/lib/config.js # dsh-mneme/lib/settings.js # dsh-mneme/src/config.js # dsh-mneme/src/settings.js # dsh-mneme/test/api.test.js
2 parents 1fbd695 + e172d01 commit 1723d67

16 files changed

Lines changed: 1063 additions & 50 deletions

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
## 🆕 新增
1010

11+
- **图谱锚定层 Activation Anchoring(issue #24 块1)**:在 `entityRecallEnabled` 的「查询命中实体 → 挂联记忆进融合池」之上再加一层级联——命中实体作锚定种子(`graphSeedCap` 封顶,默认 12),沿 `entity_relations` 按 `graphCascadeDepth`(默认 2)向邻居扩散,邻居挂联的记忆以跳数配额权重(1:2:3-hop = 0.5/0.3/0.2)补位进池,恒低于种子直达分(attr 1.0 / relation 0.9)。级联 BFS 逐层懒取邻居(>1 跳真正可达),邻接查询双向绑定(方向写反的关系行不丢)。默认关=检索行为与 #219 单跳轴逐字节一致(关档连种子裁剪都不生效)。新增三键 `graphAnchoringEnabled`/`graphSeedCap`/`graphCascadeDepth` 注册进 feature_flags 白名单,面板可启停;lightMode 强制关。
12+
- **边权重演化 Weight Evolution(issue #24 块2)**:`entity_relations` 加 `weight`/`source` 两列(幂等迁移,存量行按 manual 1.0 认账)——建边来源决定初值(manual/confirmed 1.0、llm 0.4、tag 0.3),LLM 抽取自动建的边标 `source='llm'`;演化走 `bumpRelationWeight`(只加不减、封顶 1.0,单条 `UPDATE ... MIN(1.0, weight + ?)` 原子抬升,负/非有限增量在存储边界拒绝)。新增两键 `graphWeightEnabled`/`graphWeightDelta` 注册进 feature_flags 白名单,面板可启停;lightMode 强制关。触达侧接线见块4(被动确认)。
1113
- **关联提示防幻觉 Injection Budget(issue #24 块3)**:图召回候选进注入时默认只参与排序、不改变注入块构成(`graphInjectHint` 关,保守档);开启后以固定句式「[检索线索]」标注、并在首个线索行前加引导语(链路信息非事实断言),条数由独立预算 `graphInjectBudget` 约束——既不受 document 预算约束、也不挤占 `maxItems` 槽位。线索行不进 pin 池(pin 会在保守档下把它放回块内,绕过开关)。新增两键注册进 feature_flags 白名单;lightMode 强制关。
1214

1315
## 🧹 工程

‎dsh-mneme/lib/config.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -463,6 +463,23 @@ export const Config = z.object({
463463
// 检索融合池(与 BM25 同级的确认/回填信号)。默认关=检索行为与 #219 前
464464
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
465465
entityRecallEnabled: z.boolean().default(false),
466+
// 边权重演化(issue #24 块2):touch 门控是否把被寻回路径的边权重抬升。
467+
// 默认关=边初值纯由建边来源决定(store.RELATION_SOURCE_DEFAULTS),演化
468+
// 不生效;开=被激活的边经 bumpRelationWeight 上涨(只加不减、封顶 1.0)。
469+
graphWeightEnabled: z.boolean().default(false),
470+
// 单次有效触达的抬升幅度。
471+
graphWeightDelta: z.number().min(0).max(1).default(0.1),
472+
473+
// --- 图谱锚定层(issue #24 · 块1 Activation Anchoring)-------------------
474+
// entityRecallEnabled 之上再开一层:以查询命中的实体为种子,沿实体关系表
475+
// 级联扩散(默认深度 2),把「邻居实体挂联的记忆」也带进融合池。种子集
476+
// 上限 graphSeedCap、级联深度 graphCascadeDepth 一并下发到 anchorSeeds /
477+
// cascadeDepths(见 src/graph/anchoring.js)。默认关=行为与 #219 单跳轴
478+
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
479+
graphAnchoringEnabled: z.boolean().default(false),
480+
graphSeedCap: z.natural().min(1).max(30).default(12),
481+
graphCascadeDepth: z.natural().min(1).max(3).default(2),
482+
466483
// 关联提示防幻觉(issue #24 块3):图召回的候选(查询命中实体的挂联记忆)
467484
// 进注入时默认只参与排序、不改变注入块构成(graphInjectHint=false 保守档);
468485
// 开启后注入文本里以固定句式「[检索线索] …」标出,引导语说明这是链路信息
@@ -720,6 +737,10 @@ const LIGHT_MODE_OFF = [
720737
"bm25SearchEnabled",
721738
// 轻量模式不开图召回轴(#219,依赖实体抽取产出;抽取本身已被关掉)。
722739
"entityRecallEnabled",
740+
// 轻量模式不开图谱锚定层级联(#24 块1,依赖实体抽取 + 关系表,抽取已关则无边可扩)。
741+
"graphAnchoringEnabled",
742+
// 轻量模式不开边权重演化(#24 块2,依赖实体抽取产出;抽取关则无 v08 边可抬升)。
743+
"graphWeightEnabled",
723744
// 轻量模式不开关联提示标注(#24 块3,常驻注入文本多一段提示成本)。
724745
"graphInjectHint",
725746
// 轻量模式不开叙述条(额外 LLM 调用;#164 对齐,opt-in)。

‎dsh-mneme/lib/entities/extractor.js‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,10 @@ export async function extractEntities(memory, { store, config, callLLM, logger }
226226
to_entity: toId,
227227
relation_type: rel.type,
228228
memory_id: memory.id,
229-
metadata: { model: options.model || "default" }
229+
metadata: { model: options.model || "default" },
230+
// issue #24 块2:LLM 抽取自动建边 → llm 来源(初值 0.4),区别于
231+
// 人工/确认的满权边。来源进 metadata 之上的独立列,演化与审计可辨。
232+
source: "llm"
230233
});
231234
savedRelations.push(saved);
232235
} catch (err) {

‎dsh-mneme/lib/graph/anchoring.js‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
// dsh-mneme/src/graph/anchoring.js
2+
// 图谱锚定层(issue #24 · 块1 Activation Anchoring)。
3+
import assert from "node:assert/strict";
4+
// 纯函数模块:把「查询命中实体的多路激活信号」归一化、合并成种子集、再沿
5+
// entity_relations 级联扩散。零数据库依赖——store 侧查询由调用方注入,
6+
// 本模块只做信号处理,便于单测与与其他召回通路(BM25/向量)同等对待。
7+
//
8+
// 设计输入来自 #24 合议 + heptaspirit serendipity-engine 实战(#24 评论):
9+
// - 归一化二分法:连续分(cos/PPR)走 min-max;匹配通路(精确/tag/别名)
10+
// 走离散级别,不用 min-max——布尔通路用 min-max 会把「中 1 个」和「中
11+
// 20 个」都拉平到 1.0,级别信息被压平。
12+
// - 级联扩散加「跳数配额」:λ/θ 只管可及性,可见性由配额决定——直接按 hop
13+
// 深度打 0.5/0.3/0.2 权重,配桶内 round-robin,防深跳被 1-hop 完全压住。
14+
// - graphSeedCap:防「多锚点命中 + 模糊通路」把种子集撑爆成整库。
15+
// - 排序稳定:并列按实体 ID 破序(同输入两次结果不同会让 A/B 调参白做)。
16+
17+
/** 匹配通路的离散级别(heptaspirit 建议:布尔/计数通路不用 min-max)。 */
18+
export const DISCRETE_LEVELS = Object.freeze({
19+
exact: 1.0, // 名称精确含于查询(布尔 1.0)
20+
title: 0.8, // 实体名匹配记忆标题(tag/别名层)
21+
alias: 0.6,
22+
tag: 0.4, // tag 共现
23+
substring: 0.2, // 子串命中(最弱,纯计数不级联)
24+
});
25+
26+
/** 级联每跳的权重(跳数配额:1:2:3-hop = 0.5/0.3/0.2)。 */
27+
export const HOP_QUOTA = Object.freeze({ 1: 0.5, 2: 0.3, 3: 0.2 });
28+
29+
/**
30+
* 连续分 min-max 归一化(向量 cos 相似度、PPR 激活分等)。
31+
* 输入 [] 或全同值时返回原样(无尺度可压平,防除零)。
32+
*/
33+
export function minMax(scores) {
34+
const arr = Array.isArray(scores) ? scores : [];
35+
if (arr.length === 0) return [];
36+
let min = Infinity;
37+
let max = -Infinity;
38+
for (const v of arr) {
39+
if (v < min) min = v;
40+
if (v > max) max = v;
41+
}
42+
if (max - min < 1e-12) return arr.map(() => 1); // 平局视为满权
43+
return arr.map((v) => (v - min) / (max - min));
44+
}
45+
46+
/**
47+
* 把一条检测通路的结果归一化成 0..1 的打分表。
48+
* path 是离散通路名(exact/tag/...)→ 查 DISCRETE_LEVELS;是连续通路
49+
* (continuous=true)→ min-max。返回 { byId: Map<id, score>, order: [id...] }。
50+
*/
51+
export function normalizePath(hits, { path = "exact", continuous = false } = {}) {
52+
const ids = Array.isArray(hits) ? hits : [];
53+
const byId = new Map();
54+
if (continuous) {
55+
const raw = ids.map((h) => (typeof h === "number" ? h : h?.score ?? 0));
56+
const norm = minMax(raw);
57+
ids.forEach((h, i) => {
58+
const id = typeof h === "object" ? h.id : h;
59+
byId.set(id, norm[i]);
60+
});
61+
} else {
62+
const level = DISCRETE_LEVELS[path] ?? DISCRETE_LEVELS.substring;
63+
for (const id of ids) byId.set(id, level);
64+
}
65+
return { byId, order: [...byId.keys()] };
66+
}
67+
68+
/**
69+
* 合并多路激活成种子集:每路先归一化(调用方负责通路分类),再累加。
70+
* seedsCap 上限(graphSeedCap,默认 12);封顶前按总分排序取前 N——保证
71+
* 扩散的是活跃子图而非冷启动点爆整库。
72+
* 返回 { id, name, score, paths: Set } 列表,按 score 降序、name 升序(稳定)。
73+
*/
74+
export function anchorSeeds({ paths = [], cap = 12 } = {}) {
75+
const score = new Map();
76+
const nameOf = new Map();
77+
const pathSet = new Map();
78+
for (const p of paths) {
79+
for (const [id, s] of p.byId ?? []) {
80+
score.set(id, (score.get(id) ?? 0) + s);
81+
if (!pathSet.has(id)) pathSet.set(id, new Set());
82+
pathSet.get(id).add(p.path ?? "?");
83+
if (p.nameOf?.has?.(id)) nameOf.set(id, p.nameOf.get(id));
84+
}
85+
}
86+
let seeds = [...score.entries()].map(([id, s]) => ({
87+
id,
88+
name: nameOf.get(id) ?? id,
89+
score: s,
90+
paths: pathSet.get(id) ?? new Set()
91+
}));
92+
seeds.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
93+
if (cap > 0 && seeds.length > cap) seeds = seeds.slice(0, cap);
94+
return seeds;
95+
}
96+
97+
/**
98+
* 级联扩散:从种子实体出发沿 adjacency 走 BFS,为每个可达实体贴最短深度。
99+
* depth 上界默认 2([1,3] 配置范围)。返回 Map<entityId, minDepth>——
100+
* 调用方据此取 HOP_QUOTA[minDepth] 权重 + 桶内 round-robin(见 pickByHopQuota)。
101+
* adjacency 由调用方提供(store.getEntityNeighbors(id) 或全量邻接矩阵),
102+
* 本模块不感知存储。
103+
*/
104+
export function cascadeDepths({ seeds, adjacencyOf, maxDepth = 2 } = {}) {
105+
const depths = new Map();
106+
const idOfSeeds = (seeds ?? []).map((s) => (typeof s === "object" ? s.id : s));
107+
const queue = [];
108+
for (const id of idOfSeeds) {
109+
if (!depths.has(id)) {
110+
depths.set(id, 0);
111+
queue.push([id, 0]);
112+
}
113+
}
114+
for (let i = 0; i < queue.length; i++) {
115+
const [id, d] = queue[i];
116+
if (d >= maxDepth) continue;
117+
let neighbors = [];
118+
try {
119+
neighbors = typeof adjacencyOf === "function" ? adjacencyOf(id) : (adjacencyOf?.get?.(id) ?? []);
120+
} catch { /* single neighbor fetch failure: keep spreading from the rest */ }
121+
for (const nb of neighbors) {
122+
const nid = typeof nb === "object" ? nb.id : nb;
123+
if (!nid || depths.has(nid)) continue;
124+
depths.set(nid, d + 1);
125+
queue.push([nid, d + 1]);
126+
}
127+
}
128+
return depths;
129+
}
130+
131+
/**
132+
* 跳数配额选取:候选实体按深度分层,层内按(分,ID)稳定排序后取额度。
133+
* quota 形如 { 1: 0.5, 2: 0.3, 3: 0.2 }——每层最多取 ceil(depthCap * quota[d]) 个,
134+
* 桶内按 score 降序(并列按 ID)。返回 { ids, scoreOf, depthOf }。
135+
* 这一步把「级联可及性」与「最终可见性」解耦(heptaspirit:λ/θ 只管前者)。
136+
*/
137+
export function pickByHopQuota({
138+
depths = new Map(),
139+
scoreOf = () => 0,
140+
maxDepth = 2,
141+
depthCap = 12
142+
} = {}) {
143+
const buckets = new Map(); // depth -> [{id, score}]
144+
for (const [id, d] of depths) {
145+
if (d === 0 || d > maxDepth) continue;
146+
const key = Math.min(d, 3);
147+
if (!buckets.has(key)) buckets.set(key, []);
148+
buckets.get(key).push({ id, score: scoreOf(id) ?? 0 });
149+
}
150+
const picked = [];
151+
for (const [d, items] of buckets) {
152+
items.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
153+
const quota = HOP_QUOTA[d] ?? 0.2;
154+
const n = Math.max(1, Math.floor(depthCap * quota));
155+
picked.push(...items.slice(0, n).map((x) => x.id));
156+
}
157+
// 队内稳定序:按深度升序(1-hop 优先),保证可感知的扩散次序。
158+
picked.sort((a, b) => (depths.get(a) - depths.get(b)) || (a < b ? -1 : a > b ? 1 : 0));
159+
return { ids: picked, scoreOf, depthOf: depths };
160+
}
161+
162+
// Lightweight self-check (ponytail: 非平凡逻辑留一个可运行断言)。
163+
export function _selfCheck() {
164+
const exact = normalizePath(["e1", "e2"], { path: "exact" });
165+
const tag = normalizePath(["e2", "e3"], { path: "tag" });
166+
assert(exact.byId.get("e1") === 1.0 && exact.byId.get("e2") === 1.0, "exact level");
167+
assert(tag.byId.get("e2") === 0.4 && tag.byId.get("e3") === 0.4, "tag level");
168+
const seeds = anchorSeeds({ paths: [exact, tag], cap: 10 });
169+
assert(seeds[0].id === "e2", "merged highest first"); // e2: 精确+tag = 1.4
170+
assert(seeds[0].score >= 1.4 - 1e-9, "score accumulates");
171+
const adj = new Map([
172+
["e2", ["n1", "n2"]],
173+
["n1", ["n2", "deep3"]],
174+
]);
175+
const depths = cascadeDepths({ seeds, adjacencyOf: (id) => adj.get(id) ?? [], maxDepth: 2 });
176+
assert(depths.get("n1") === 1 && depths.get("n2") === 1 && depths.get("deep3") === 2, "bfs depth");
177+
const { ids } = pickByHopQuota({ depths, maxDepth: 2, depthCap: 12 });
178+
assert(ids.includes("n1") && ids.includes("n2") && ids.includes("deep3"), "quota picks all");
179+
return "anchoring self-check ok";
180+
}

‎dsh-mneme/lib/service.js‎

Lines changed: 80 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import { createDocumentRegistrar } from "./document.js";
1111
import { createOrganizer } from "./organize.js";
1212
import { createBM25Index } from "./search/bm25.js";
1313
import { adaptiveThreshold } from "./search/adaptive.js";
14+
import { anchorSeeds, normalizePath, cascadeDepths, HOP_QUOTA } from "./graph/anchoring.js";
1415

1516
const INJECT_TYPES = new Set(["preference", "project", "decision", "summary", "rejected_solution", "pitfall", "constraint"]);
1617

@@ -448,30 +449,92 @@ export function createService({ store, mirror, config, onWrite, logger, document
448449
}
449450

450451
/**
451-
* Graph fourth recall path (issue #219). When the query text mentions a
452-
* known entity name, memories linked to that entity (attrs + relations)
453-
* join the fusion pool as a confirm/backfill signal — same standing as
454-
* BM25, never dominating the semantic ranking. Tier scores: attr-linked
455-
* 1.0 (direct evidence, same source searchByEntity trusts) > relation
456-
* edge 0.9. Archived/forgotten rows never participate. Failures degrade
457-
* to [] — a recall booster, never a correctness gate (same contract as
458-
* bm25Recall).
452+
* Graph fourth recall path (issue #219 → #24 块1 锚定层). When the query text
453+
* mentions a known entity name, memories linked to that entity (attrs +
454+
* relations) join the fusion pool as a confirm/backfill signal — same standing
455+
* as BM25, never dominating the semantic ranking. Tier scores: attr-linked
456+
* 1.0 (direct evidence, same source searchByEntity trusts) > relation edge
457+
* 0.9. Archived/forgotten rows never participate. Failures degrade to [] —
458+
* a recall booster, never a correctness gate (same contract as bm25Recall).
459+
*
460+
* #24 升级(graphAnchoringEnabled):命中实体作为锚定种子,沿 entity_relations
461+
* 级联扩散邻居(默认深度 2),邻居挂联的记忆以 hop 配额权重参与——把「关系是
462+
* 用出来的」延伸成检索信号:查询命中的不只有直接挂联,还有跳跃可达的活跃子图。
463+
* 邻居权重 = HOP_QUOTA[hop] × linked tier(attr 1.0 / relation 0.9),仍低于
464+
* 直达种子的满权,绝不喧宾夺主。
459465
*/
460466
function entityRecall(q, limit) {
461467
if (config?.entityRecallEnabled !== true) return [];
462468
try {
463469
const entities = store.findEntitiesMentionedIn(q);
464470
if (!entities.length) return [];
465-
const linked = store.getLinkedMemoryIds(entities.map((e) => e.id));
466-
if (!linked.size) return [];
467-
const hits = [];
468-
for (const [id, tier] of linked) {
469-
const row = store.getById(id);
470-
if (!row || row.archived || row.forgotten) continue;
471-
hits.push({ ...row, score: tier === "attr" ? 1.0 : 0.9, source: "entity" });
472-
if (hits.length >= limit * 2) break;
471+
// 关闭锚定级联=逐字节复用 #219 单跳轴:种子裁剪/重排/截断全是 #24 新增的
472+
// 行为,默认关时一条都不许漏进旧路径(graphSeedCap 也只在开启后生效——
473+
// 无论 cap 调多小,关档时命中实体仍全量挂联)。
474+
if (config?.graphAnchoringEnabled !== true) {
475+
const linked = store.getLinkedMemoryIds(entities.map((e) => e.id));
476+
if (!linked.size) return [];
477+
const hits = [];
478+
for (const [id, tier] of linked) {
479+
const row = store.getById(id);
480+
if (!row || row.archived || row.forgotten) continue;
481+
hits.push({ ...row, score: tier === "attr" ? 1.0 : 0.9, source: "entity" });
482+
if (hits.length >= limit * 2) break;
483+
}
484+
return hits;
485+
}
486+
// 锚定种子(精确名布尔通路——命名实体逻辑上是离散匹配,不参与 min-max)。
487+
const exact = normalizePath(entities.map((e) => e.id), { path: "exact" });
488+
const seeds = anchorSeeds({ paths: [exact], cap: config?.graphSeedCap ?? 12 });
489+
if (!seeds.length) return [];
490+
// 0-hop 直达:挂联记忆按 tier 定分(attr 1.0 / relation 0.9)——与 #219
491+
// 单跳轴同分。MAX 语义:同一条记忆被多实体挂联时保留最高分。
492+
const scored = new Map();
493+
const push = (memId, score) => {
494+
if (scored.has(memId) && scored.get(memId) >= score) return;
495+
const row = store.getById(memId);
496+
if (!row || row.archived || row.forgotten) return;
497+
scored.set(memId, score);
498+
};
499+
const seedLinked = store.getLinkedMemoryIds(seeds.map((s) => s.id));
500+
for (const [memId, tier] of seedLinked) {
501+
push(memId, tier === "attr" ? 1.0 : 0.9);
502+
}
503+
// 级联:沿 entity_relations 走 BFS,邻居挂联的记忆以 hop 配额权重补位——
504+
// 不覆盖种子直达分(MAX 语义保证),只填「种子里没有但邻居可达」的槽。
505+
const seedIds = seeds.map((s) => s.id);
506+
const adjacency = store.getEntityNeighbors(seedIds);
507+
const depths = cascadeDepths({
508+
seeds,
509+
// 逐节点懒取邻居:初次查询只带种子那一层的邻接,BFS 走到 1-hop 节点时
510+
// 必须按需再拉一层,否则 >1 跳永远拿到空邻居、graphCascadeDepth≥2 形同
511+
// 虚设。节点数随图度数增长,热路径上以 graphCascadeDepth≤3 为天然上界,
512+
// 真遇到大图再考虑查询配额。
513+
adjacencyOf: (id) => {
514+
if (!adjacency.has(id)) adjacency.set(id, store.getEntityNeighbors([id]).get(id) ?? []);
515+
return adjacency.get(id);
516+
},
517+
maxDepth: config?.graphCascadeDepth ?? 2
518+
});
519+
let neighborsSeen = 0;
520+
const neighborCap = (config?.graphSeedCap ?? 12) * HOP_QUOTA[1]; // 1-hop 配额即为邻居总量上界
521+
for (const [nid, hop] of depths) {
522+
if (hop < 1) continue;
523+
if (neighborsSeen >= Math.max(1, Math.floor(neighborCap))) break;
524+
neighborsSeen++;
525+
const neighborLinked = store.getLinkedMemoryIds([nid]);
526+
for (const [memId, tier] of neighborLinked) {
527+
const tierW = tier === "attr" ? 1.0 : 0.9;
528+
push(memId, HOP_QUOTA[Math.min(hop, 3)] * tierW);
529+
}
473530
}
474-
return hits;
531+
const hits = [...scored.entries()]
532+
.map(([id, score]) => {
533+
const row = store.getById(id);
534+
return { ...row, score, source: "entity" };
535+
})
536+
.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
537+
return hits.slice(0, limit * 2);
475538
} catch {
476539
return [];
477540
}

0 commit comments

Comments
 (0)