Skip to content

Commit 21a4a4c

Browse files
committed
feat(graph): 图谱锚定层 Activation Anchoring(issue #24 块1)
在 #219 图召回轴之上加级联扩散:查询命中的实体作为锚定种子,沿 entity_relations 走 BFS(默认深度 2),邻居挂联的记忆以 hop 配额 (1:2:3 = 0.5/0.3/0.2)加权补位。种子直达记忆保持满分(attr 1.0 / relation 0.9,与 #219 逐字节一致),仅填种子里没有的槽。 - src/graph/anchoring.js:纯函数锚定层(离散/连续通路归一化二分法、 anchorSeeds 种子合并 + graphSeedCap、cascadeDepths BFS、pickByHopQuota) - store.getEntityNeighbors:批量邻接查询(IN 一次取全族邻居) - entityRecall 升级:graphAnchoringEnabled 开启级联,默认关 = 行为不变 - config:graphAnchoringEnabled / graphSeedCap(12) / graphCascadeDepth(2) - 设计输入来自 heptaspirit serendipity-engine (#24 评论):跳数配额、 min-max 只用于连续通路、种子集设上界防模糊通路撑爆 测试:6 组 graph-anchoring 新增全过;1437 全绿
1 parent 8519f57 commit 21a4a4c

9 files changed

Lines changed: 704 additions & 34 deletions

File tree

‎dsh-mneme/lib/config.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -464,6 +464,16 @@ export const Config = z.object({
464464
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
465465
entityRecallEnabled: z.boolean().default(false),
466466

467+
// --- 图谱锚定层(issue #24 · 块1 Activation Anchoring)-------------------
468+
// entityRecallEnabled 之上再开一层:以查询命中的实体为种子,沿实体关系表
469+
// 级联扩散(默认深度 2),把「邻居实体挂联的记忆」也带进融合池。种子集
470+
// 上限 graphSeedCap、级联深度 graphCascadeDepth 一并下发到 anchorSeeds /
471+
// cascadeDepths(见 src/graph/anchoring.js)。默认关=行为与 #219 单跳轴
472+
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
473+
graphAnchoringEnabled: z.boolean().default(false),
474+
graphSeedCap: z.natural().min(1).max(30).default(12),
475+
graphCascadeDepth: z.natural().min(1).max(3).default(2),
476+
467477
// --- sleep mode: idle-triggered deep maintenance (v0.4.0) ---------------
468478
// Opt-in, off by default. Unlike autoDream (threshold-triggered, lightweight)
469479
// sleep fires when the store has been quiet for sleepIdleMinutes and deep-
@@ -712,6 +722,8 @@ const LIGHT_MODE_OFF = [
712722
"bm25SearchEnabled",
713723
// 轻量模式不开图召回轴(#219,依赖实体抽取产出;抽取本身已被关掉)。
714724
"entityRecallEnabled",
725+
// 轻量模式不开图谱锚定层级联(#24,依赖实体抽取 + 关系表,抽取已关则无边可扩)。
726+
"graphAnchoringEnabled",
715727
// 轻量模式不开叙述条(额外 LLM 调用;#164 对齐,opt-in)。
716728
"dreamNarrativeEnabled",
717729
// 轻量模式不开 document 指针行(#230,opt-in:注册/注入/检索增强全随闸)。

‎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: 61 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,73 @@ 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+
// 锚定种子(精确名布尔通路——命名实体逻辑上是离散匹配,不参与 min-max)。
472+
const exact = normalizePath(entities.map((e) => e.id), { path: "exact" });
473+
const seeds = anchorSeeds({ paths: [exact], cap: config?.graphSeedCap ?? 12 });
474+
if (!seeds.length) return [];
475+
// 0-hop 直达:挂联记忆按 tier 定分(attr 1.0 / relation 0.9)——与 #219
476+
// 单跳轴逐字节一致。MAX 语义:同一条记忆被多实体挂联时保留最高分。
477+
const scored = new Map();
478+
const push = (memId, score) => {
479+
if (scored.has(memId) && scored.get(memId) >= score) return;
480+
const row = store.getById(memId);
481+
if (!row || row.archived || row.forgotten) return;
482+
scored.set(memId, score);
483+
};
484+
const seedLinked = store.getLinkedMemoryIds(seeds.map((s) => s.id));
485+
for (const [memId, tier] of seedLinked) {
486+
push(memId, tier === "attr" ? 1.0 : 0.9);
487+
}
488+
// 级联:默认关(graphAnchoringEnabled 未开)时直接收尾,行为与 #219 逐字节一致;
489+
// 开启后才沿 entity_relations 走 BFS,邻居挂联的记忆以 hop 配额权重补位——
490+
// 不覆盖种子直达分(MAX 语义保证),只填「种子里没有但邻居可达」的槽。
491+
if (config?.graphAnchoringEnabled === true) {
492+
const seedIds = seeds.map((s) => s.id);
493+
const adjacency = store.getEntityNeighbors(seedIds);
494+
const depths = cascadeDepths({
495+
seeds,
496+
adjacencyOf: (id) => adjacency.get(id) ?? [],
497+
maxDepth: config?.graphCascadeDepth ?? 2
498+
});
499+
let neighborsSeen = 0;
500+
const neighborCap = (config?.graphSeedCap ?? 12) * HOP_QUOTA[1]; // 1-hop 配额即为邻居总量上界
501+
for (const [nid, hop] of depths) {
502+
if (hop < 1) continue;
503+
if (neighborsSeen >= Math.max(1, Math.floor(neighborCap))) break;
504+
neighborsSeen++;
505+
const neighborLinked = store.getLinkedMemoryIds([nid]);
506+
for (const [memId, tier] of neighborLinked) {
507+
const tierW = tier === "attr" ? 1.0 : 0.9;
508+
push(memId, HOP_QUOTA[Math.min(hop, 3)] * tierW);
509+
}
510+
}
473511
}
474-
return hits;
512+
const hits = [...scored.entries()]
513+
.map(([id, score]) => {
514+
const row = store.getById(id);
515+
return { ...row, score, source: "entity" };
516+
})
517+
.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
518+
return hits.slice(0, limit * 2);
475519
} catch {
476520
return [];
477521
}

‎dsh-mneme/lib/store.js‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2459,6 +2459,38 @@ export function createStore(path) {
24592459
).all(entityId, entityId).map(toRelation);
24602460
}
24612461

2462+
/**
2463+
* 批量邻接(issue #24 · 块1 锚定层级联):给定多条实体 id,一并取全部关系行
2464+
* 并归并成「每个实体 → 相邻实体 id 去重列表」的邻接表。供 anchoring.js 的
2465+
* cascadeDepths 使用——多实体一族只需要一次 SQL(IN 查询),比逐实体调
2466+
* getRelations 的 N 次往返省。邻接是无向的(from/to 双向),往返不重复。
2467+
* 返回 Map<entityId, Array<entityId>>;未命中的实体缺省为 absent(级联视为
2468+
* 无邻居,Map 里不放键同行,null 同等对待)。
2469+
*/
2470+
function getEntityNeighbors(entityIds) {
2471+
const out = new Map();
2472+
const ids = Array.isArray(entityIds) ? entityIds.filter(Boolean) : [];
2473+
if (!ids.length) return out;
2474+
const placeholders = ids.map(() => "?").join(",");
2475+
const rows = db.prepare(
2476+
`SELECT from_entity, to_entity FROM entity_relations
2477+
WHERE from_entity IN (${placeholders}) OR to_entity IN (${placeholders})`
2478+
).all(...ids);
2479+
for (const r of rows) {
2480+
addNeighbor(out, r.from_entity, r.to_entity, ids);
2481+
addNeighbor(out, r.to_entity, r.from_entity, ids);
2482+
}
2483+
return out;
2484+
}
2485+
2486+
function addNeighbor(out, anchor, neighbor, queryIds) {
2487+
if (!queryIds.includes(anchor)) return; // 只以查询过的实体为锚
2488+
if (neighbor === anchor) return; // 自环不构成扩散边
2489+
if (!out.has(anchor)) out.set(anchor, []);
2490+
const list = out.get(anchor);
2491+
if (!list.includes(neighbor)) list.push(neighbor);
2492+
}
2493+
24622494
/** All entities (optionally name-filtered, newest first). Used by sleep phase 4
24632495
* orphan detection: an entity with zero relations is a candidate for relation
24642496
* completion. */
@@ -2842,6 +2874,7 @@ export function createStore(path) {
28422874
saveRelation,
28432875
migrateAttrsToMemory,
28442876
getRelations,
2877+
getEntityNeighbors,
28452878
setMirrorState,
28462879
getMirrorState,
28472880
markMirrorDirty,

‎dsh-mneme/src/config.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -464,6 +464,16 @@ export const Config = z.object({
464464
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
465465
entityRecallEnabled: z.boolean().default(false),
466466

467+
// --- 图谱锚定层(issue #24 · 块1 Activation Anchoring)-------------------
468+
// entityRecallEnabled 之上再开一层:以查询命中的实体为种子,沿实体关系表
469+
// 级联扩散(默认深度 2),把「邻居实体挂联的记忆」也带进融合池。种子集
470+
// 上限 graphSeedCap、级联深度 graphCascadeDepth 一并下发到 anchorSeeds /
471+
// cascadeDepths(见 src/graph/anchoring.js)。默认关=行为与 #219 单跳轴
472+
// 逐字节一致;走 feature_flags 面板可启停,lightMode 强制关闭。
473+
graphAnchoringEnabled: z.boolean().default(false),
474+
graphSeedCap: z.natural().min(1).max(30).default(12),
475+
graphCascadeDepth: z.natural().min(1).max(3).default(2),
476+
467477
// --- sleep mode: idle-triggered deep maintenance (v0.4.0) ---------------
468478
// Opt-in, off by default. Unlike autoDream (threshold-triggered, lightweight)
469479
// sleep fires when the store has been quiet for sleepIdleMinutes and deep-
@@ -712,6 +722,8 @@ const LIGHT_MODE_OFF = [
712722
"bm25SearchEnabled",
713723
// 轻量模式不开图召回轴(#219,依赖实体抽取产出;抽取本身已被关掉)。
714724
"entityRecallEnabled",
725+
// 轻量模式不开图谱锚定层级联(#24,依赖实体抽取 + 关系表,抽取已关则无边可扩)。
726+
"graphAnchoringEnabled",
715727
// 轻量模式不开叙述条(额外 LLM 调用;#164 对齐,opt-in)。
716728
"dreamNarrativeEnabled",
717729
// 轻量模式不开 document 指针行(#230,opt-in:注册/注入/检索增强全随闸)。

0 commit comments

Comments
 (0)