Skip to content

Commit 5ae1bd7

Browse files
committed
feat(scope): 检索加权与 occurred_at 时间过滤(A2,issue #17)
v0.8.0 批次 A 第 2 个 PR,接在 #153(A1 存储层)之后:检索侧软隔离。 scopeEnabled 关闭或调用方未提供会话 scope 时,检索行为与 A2 前逐字节一致。 - service.searchMemories:新增 options.scope(工具层从 exec.agent.session 解析 后传入)——当前会话 scope 两维命中的候选 ×1.25 加成,带他 scope 的候选 ×0.5 降权但保留可见(硬过滤是 A3 strictScope);未标注行(NULL)与无法比较的维度 恒中性,全局/存量记忆不因加权掉位。系数为模块常量,数值等线上反馈再调 - occurred_at 时间窗:store.list/count 新增 occurredFrom/occurredTo 闭区间 (与 updated_at 共用 updatedAtBounds 归一化,date-only 含当日);按 COALESCE(occurred_at, created_at) 比较——未标注行回退创建时间,过滤器对 存量库可用;搜索路径在融合池上先滤再 dedup/slice,rerank 只看窗内候选, list 与 count 同口径保证分页 total 与行一致 - tools:memory_search / memory_list 新增可选 occurred_from / occurred_to 参数;memory_search 接 exec 做会话 scope 加权;三个检索工具的输出 schema 与 render 透出 agent_scope/workspace_scope/sensitivity/occurred_at(provenance 附加段只在有标注时出现);toApiList 条件展开——未标注行 DTO 与 A2 前同形 - updatedAtBounds 从 store.js 导出复用(搜索后置过滤与 SQL 过滤共用边界归一) 测试 +13(store/service 透传、搜索窗、加权翻转/中性/flag 关、toApiList 形状、 memory_search/list/get 工具接线),全量 962 项 961 绿 / 1 既有 skip。 Refs #17(A2/4)
1 parent 0e5081b commit 5ae1bd7

7 files changed

Lines changed: 511 additions & 36 deletions

File tree

‎dsh-mneme/lib/service.js‎

Lines changed: 74 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { createHash, randomUUID } from "node:crypto";
22
import { TYPE_FILE } from "./mirror.js";
3+
import { updatedAtBounds } from "./store.js";
34
import { STR, langOf } from "./lang.js";
45
import { computeHeat } from "./heat.js";
56
import { evaluateMemoryQuality } from "./quality-filter.js";
@@ -45,6 +46,41 @@ function scopeKeyOf(v) {
4546
return typeof v === "string" && v.trim() ? v.trim() : null;
4647
}
4748

49+
// v0.8.0 A2(issue #17)scope 检索加权系数:当前会话 scope 两维都命中 → 加成;
50+
// 任一维度带着他 scope → 降权但保留可见(硬过滤是 A3 strictScope)。未标注行
51+
// (NULL)与无法比较的维度恒中性——全局/存量记忆不因加权掉位。系数是模块常量
52+
// 而非配置项:A2 只定性行为,数值要等线上检索质量反馈再调(加配置面=提前优化)。
53+
const SCOPE_MATCH_BOOST = 1.25;
54+
const SCOPE_FOREIGN_PENALTY = 0.5;
55+
56+
/**
57+
* 单条候选的 scope 乘数。匹配语义与去重键一致(scopeKeyOf):记忆侧未标注视同
58+
* 该维度命中(全局记忆对谁都可见);当前会话侧某维度解析不到则该维度不参与
59+
* 比较(无法比较 ≠ 不匹配)。
60+
*/
61+
function scopeMultiplier(m, current) {
62+
const agentForeign = scopeKeyOf(m.agent_scope) !== null
63+
&& current.agent_scope !== null
64+
&& scopeKeyOf(m.agent_scope) !== current.agent_scope;
65+
const workspaceForeign = scopeKeyOf(m.workspace_scope) !== null
66+
&& current.workspace_scope !== null
67+
&& scopeKeyOf(m.workspace_scope) !== current.workspace_scope;
68+
return (agentForeign || workspaceForeign) ? SCOPE_FOREIGN_PENALTY : SCOPE_MATCH_BOOST;
69+
}
70+
71+
/**
72+
* v0.8.0 A2:occurred_at 后置过滤谓词(搜索融合池用)。行侧取
73+
* COALESCE(occurred_at, created_at)——与 store.list 的 SQL 过滤同口径,未标注
74+
* 行回退创建时间;时间戳损坏的行保留(宁可放宽也不误杀,同 summarize inWindow)。
75+
*/
76+
function inOccurredBounds(m, bounds) {
77+
const t = Date.parse(String(m.occurred_at ?? m.created_at ?? ""));
78+
if (!Number.isFinite(t)) return true;
79+
if (bounds.from && t < Date.parse(bounds.from)) return false;
80+
if (bounds.to && t > Date.parse(bounds.to)) return false;
81+
return true;
82+
}
83+
4884
/** Prepend the previous content to a memory's content_history (FIFO capped). */
4985
function pushContentHistory(existing, source) {
5086
const history = Array.isArray(existing?.content_history) ? existing.content_history : [];
@@ -596,7 +632,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
596632
* a vector/rerank failure degrades to keyword results.
597633
*/
598634
async function searchMemories(query, options = {}) {
599-
const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true) } = options;
635+
const {
636+
mode = "auto",
637+
topK = 20,
638+
threshold,
639+
useRerank = true,
640+
// v0.8.0 A2(issue #17):当前会话 scope(工具层从 exec 解析后传入)与
641+
// occurred_at 时间窗。两者都只在显式传入时生效,既有调用方(注入/梦/评测)
642+
// 不传 → 行为与 A2 前一致。
643+
scope = null,
644+
occurredFrom = null,
645+
occurredTo = null,
646+
recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true)
647+
} = options;
600648
const q = String(query ?? "").trim();
601649
if (!q) return [];
602650

@@ -663,6 +711,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
663711

664712
const { merged: fusedMerged, signals } = fuseRecall({ keyword, vector, bm25, lim, mode, wv, wk, wb });
665713
let merged = fusedMerged;
714+
// v0.8.0 A2:occurred_at 时间过滤——在融合池上先滤再 dedup/slice,rerank
715+
// 只看窗内候选,topK 槽位不被窗外行占用。
716+
const occurredBounds = updatedAtBounds(occurredFrom, occurredTo);
717+
if (occurredBounds.from || occurredBounds.to) {
718+
merged = merged.filter((m) => inOccurredBounds(m, occurredBounds));
719+
}
666720
// Signal transparency (#2): decorate each returned row with its per-source
667721
// scores and the final fused score. Purely additive — never changes rank.
668722
if (config?.signalTransparency === true) {
@@ -692,6 +746,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
692746
.slice(0, lim);
693747
}
694748

749+
// v0.8.0 A2(issue #17):scope 检索加权——当前会话 scope 两维命中的候选
750+
// 加成、带他 scope 的候选降权但保留可见(硬过滤是 A3 strictScope)。未标注
751+
// 行与无法比较的维度恒中性;flag 关或调用方未传 scope 时不动分,排序与
752+
// A2 前逐字节一致。与 epistemic 加权同款收尾:乘分 → 降序 → 截 topK。
753+
if (config.scopeEnabled === true && scope && (scope.agent_scope || scope.workspace_scope)) {
754+
result = result
755+
.map((m) => ({ ...m, score: (m.score ?? 0) * scopeMultiplier(m, scope) }))
756+
.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
757+
.slice(0, lim);
758+
}
759+
695760
// Recall layer receipt: with recordRecall on, hand the actual merged
696761
// candidate list (id/title/content/score/source) to the injected recorder
697762
// before returning, making the retrieval scene replayable — the sibling of
@@ -1252,7 +1317,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
12521317
importance: m.importance,
12531318
source: m.source,
12541319
created_at: m.created_at,
1255-
updated_at: m.updated_at
1320+
updated_at: m.updated_at,
1321+
// v0.8.0 A2:scope 标注与事件发生时间透出——条件展开(未标注行不带键,
1322+
// DTO 与 A2 前逐字节同形;带 undefined 键会被 in-process schema 校验
1323+
// 判违规,JSON 序列化虽会丢弃但形状不稳定)。
1324+
...(m.agent_scope !== undefined ? { agent_scope: m.agent_scope } : {}),
1325+
...(m.workspace_scope !== undefined ? { workspace_scope: m.workspace_scope } : {}),
1326+
...(m.sensitivity !== undefined ? { sensitivity: m.sensitivity } : {}),
1327+
...(m.occurred_at !== undefined ? { occurred_at: m.occurred_at } : {})
12561328
}));
12571329
}
12581330

‎dsh-mneme/lib/store.js‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -310,7 +310,9 @@ function escapeLike(q) {
310310
// 法值一律返回 undefined → 不进 WHERE(忽略而非报错:面板传坏参数时宁可放宽
311311
// 过滤也不要白屏)。updated_at 列是 toISOString 产生的 UTC "Z" 字符串,字典
312312
// 序与时间序一致,SQL 里可直接比较。
313-
function updatedAtBounds(updatedFrom, updatedTo) {
313+
// v0.8.0 A2:导出复用——occurred_at 时间过滤(service 的搜索后置过滤)与
314+
// updated_at 过滤共用同一套边界归一化,坏参数口径一致。
315+
export function updatedAtBounds(updatedFrom, updatedTo) {
314316
const norm = (raw, endOfDay) => {
315317
if (typeof raw !== "string" || !raw.trim()) return undefined;
316318
const s = raw.trim();
@@ -675,7 +677,7 @@ export function createStore(path) {
675677
return ts;
676678
}
677679

678-
function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null } = {}) {
680+
function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null } = {}) {
679681
const clauses = [];
680682
const params = [];
681683
if (type !== undefined) {
@@ -702,6 +704,17 @@ export function createStore(path) {
702704
clauses.push("updated_at <= ?");
703705
params.push(bounds.to);
704706
}
707+
// occurred_at 闭区间:与 list() 同口径(COALESCE 回退 created_at),
708+
// memory_list 的 total 才能和过滤后的行保持一致。
709+
const occurred = updatedAtBounds(occurredFrom, occurredTo);
710+
if (occurred.from) {
711+
clauses.push("COALESCE(occurred_at, created_at) >= ?");
712+
params.push(occurred.from);
713+
}
714+
if (occurred.to) {
715+
clauses.push("COALESCE(occurred_at, created_at) <= ?");
716+
params.push(occurred.to);
717+
}
705718
if (!includeForgotten) {
706719
clauses.push("forgotten = 0");
707720
}
@@ -972,7 +985,7 @@ export function createStore(path) {
972985
return rows.map(toRow);
973986
}
974987

975-
function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null } = {}) {
988+
function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null } = {}) {
976989
const clauses = [];
977990
const params = [];
978991
if (type) {
@@ -1000,6 +1013,18 @@ export function createStore(path) {
10001013
clauses.push("updated_at <= ?");
10011014
params.push(bounds.to);
10021015
}
1016+
// v0.8.0 A2(issue #17):occurred_at 闭区间过滤——按「事件发生时间」检索。
1017+
// 未标注 occurred_at 的行(含全部存量)回退 created_at 比较(COALESCE),
1018+
// 否则过滤器对旧库近乎不可用;边界归一化与 updated_at 共用 updatedAtBounds。
1019+
const occurred = updatedAtBounds(occurredFrom, occurredTo);
1020+
if (occurred.from) {
1021+
clauses.push("COALESCE(occurred_at, created_at) >= ?");
1022+
params.push(occurred.from);
1023+
}
1024+
if (occurred.to) {
1025+
clauses.push("COALESCE(occurred_at, created_at) <= ?");
1026+
params.push(occurred.to);
1027+
}
10031028
if (!includeForgotten) {
10041029
clauses.push("forgotten = 0");
10051030
}

‎dsh-mneme/lib/tools.js‎

Lines changed: 55 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -26,21 +26,46 @@ const MEMORY_ITEM_SCHEMA = {
2626
tags: { type: "array", items: { type: "string" } },
2727
importance: { type: "integer", required: true },
2828
source: { type: "string" },
29+
// v0.8.0 A2:scope 标注与事件发生时间随行透出(未标注时缺省,可选属性)。
30+
agent_scope: { type: "string" },
31+
workspace_scope: { type: "string" },
32+
sensitivity: { type: "string" },
33+
occurred_at: { type: "string" },
2934
created_at: { type: "string", required: true },
3035
updated_at: { type: "string", required: true }
3136
}
3237
};
3338

39+
// v0.8.0 A2:occurred 时间窗参数 → store 过滤选项(list/count 同口径);
40+
// 未传参返回空对象,既有调用方不受影响。
41+
function occurredWindow(args) {
42+
const from = args?.occurred_from ?? null;
43+
const to = args?.occurred_to ?? null;
44+
return from !== null || to !== null ? { occurredFrom: from, occurredTo: to } : {};
45+
}
46+
47+
// v0.8.0 A2:检索结果的 provenance 附加段——只在有标注时出现,未标注行渲染
48+
// 与 A2 前逐字节一致。
49+
const MEMORY_PROVENANCE = (m) => {
50+
const parts = [];
51+
if (m.occurred_at) parts.push(`occurred: ${m.occurred_at}`);
52+
if (m.agent_scope || m.workspace_scope) {
53+
parts.push(`scope: ${m.agent_scope ?? "global"} / ${m.workspace_scope ?? "global"}`);
54+
}
55+
if (m.sensitivity) parts.push(`sensitivity: ${m.sensitivity}`);
56+
return parts.length ? ` | ${parts.join(" | ")}` : "";
57+
};
58+
3459
export function createTools(ctx, service, config, embedder) {
3560
const toolsRegistry = ctx.tools;
3661
let registeredTools = REGISTERED_TOOLS.get(toolsRegistry);
3762
if (!registeredTools) {
3863
registeredTools = new Set();
3964
REGISTERED_TOOLS.set(toolsRegistry, registeredTools);
4065
}
41-
// v0.8.0 A1(issue #17):写入端 scope 解析(agentPreset + workspace 反查)。
42-
// flag 关闭时 resolveWriteScope 恒返回 null,写入路径与 A1 前完全一致。
43-
const resolveWriteScope = createScopeResolver({ ctx, config });
66+
// v0.8.0 A1/A2(issue #17):会话 scope 解析(agentPreset + workspace 反查)。
67+
// flag 关闭时恒返回 null——写入不标注,检索不加权,行为与 A1 前完全一致。
68+
const resolveSessionScope = createScopeResolver({ ctx, config });
4469
const tools = [
4570
defineTool({
4671
name: "memory_save",
@@ -73,7 +98,7 @@ export function createTools(ctx, service, config, embedder) {
7398
// scope 标注:agent_scope/workspace_scope 由会话身份解析(不作为模型
7499
// 参数),sensitivity/occurred_at 来自显式参数。解析绝不抛错、取不到
75100
// 落 NULL;flag 关闭时 scope 为 null,一个字段都不标注。
76-
const scope = resolveWriteScope(exec);
101+
const scope = resolveSessionScope(exec);
77102
const { action, memory } = service.saveWithDedupe({
78103
type: args.type,
79104
title: args.title,
@@ -92,12 +117,15 @@ export function createTools(ctx, service, config, embedder) {
92117
defineTool({
93118
name: "memory_search",
94119
description: "Search the cross-session memory store. Use when you need past context: how a problem was solved, user preferences, project decisions. Substring-matches title/content/tags, and augments results with semantic (vector) recall + optional rerank when an embeddings provider is configured. Returns matching entries with source and timestamps.",
120+
// A2 检索接线:occurred 时间窗 + 会话 scope 加成(见 execute)。
95121
parameters: {
96122
query: { type: "string", required: true, description: "Search text; substring match over title/content/tags" },
97123
limit: { type: "integer", description: "Max results (default 20)" },
98124
mode: { type: "string", enum: ["auto", "keyword", "vector", "hybrid"], description: "auto (default) = keyword hits first + vector fill when enabled; keyword = text only; vector = semantic recall first (falls back to keyword); hybrid = vector leads, keyword fills remaining slots" },
99125
semantic: { type: "boolean", description: "Shorthand: enable semantic (vector) recall (same as mode=vector when true)" },
100-
rerank: { type: "boolean", description: "Run cross-encoder rerank over candidates when a local reranker is configured (default true)" }
126+
rerank: { type: "boolean", description: "Run cross-encoder rerank over candidates when a local reranker is configured (default true)" },
127+
occurred_from: { type: "string", description: "Optional ISO date/timestamp lower bound on when the remembered event happened (occurred_at, falling back to created_at). Date-only values are inclusive from that day's 00:00Z." },
128+
occurred_to: { type: "string", description: "Optional ISO date/timestamp upper bound on occurred_at. Date-only values are inclusive through that day's 23:59:59.999Z." }
101129
},
102130
output: {
103131
schema: {
@@ -117,19 +145,26 @@ export function createTools(ctx, service, config, embedder) {
117145
.map((m, i) => {
118146
const preview = (m.content ?? "").replace(/\s+/g, " ").trim();
119147
const cut = preview.length > 200 ? `${preview.slice(0, 200)}…` : preview;
120-
return `[${i + 1}] ${m.title}\n ID: ${m.id} | type: ${m.type} | importance: ${m.importance} | updated: ${m.updated_at}\n ${cut}`;
148+
return `[${i + 1}] ${m.title}\n ID: ${m.id} | type: ${m.type} | importance: ${m.importance} | updated: ${m.updated_at}${MEMORY_PROVENANCE(m)}\n ${cut}`;
121149
})
122150
.join("\n\n");
123151
return TEXT_OUTPUT(`Found ${items.length} memory entr${items.length === 1 ? "y" : "ies"}:\n\n${body}`);
124152
}
125153
},
126-
async execute(args) {
154+
async execute(args, exec) {
127155
const limit = args.limit ?? 20;
128156
const mode = args.semantic === true && !args.mode ? "vector" : args.mode ?? "auto";
157+
// v0.8.0 A2(issue #17):scope 检索加权 + occurred 时间窗的检索接线。
158+
// flag 关闭或解析不出 scope 时为 null,检索行为与 A2 前一致。
159+
const scope = resolveSessionScope(exec);
160+
const occurredFrom = args.occurred_from ?? null;
161+
const occurredTo = args.occurred_to ?? null;
129162
const rows = await service.searchMemories(args.query, {
130163
mode,
131164
topK: limit,
132-
useRerank: args.rerank !== false
165+
useRerank: args.rerank !== false,
166+
...(scope ? { scope } : {}),
167+
...(occurredFrom !== null || occurredTo !== null ? { occurredFrom, occurredTo } : {})
133168
});
134169
return { items: service.toApiList(rows) };
135170
}
@@ -142,7 +177,9 @@ export function createTools(ctx, service, config, embedder) {
142177
type: { type: "string", enum: ["preference", "project", "decision", "history", "rejected_solution", "pitfall", "constraint"], description: "Filter by type; omit for all" },
143178
limit: { type: "integer", description: "Page size (default 50)" },
144179
offset: { type: "integer", description: "Page offset (default 0)" },
145-
include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" }
180+
include_archived: { type: "boolean", description: "Include archived (hidden) entries so they can be found and restored (default false)" },
181+
occurred_from: { type: "string", description: "Optional ISO date/timestamp lower bound on when the remembered event happened (occurred_at, falling back to created_at). Date-only values are inclusive from that day's 00:00Z." },
182+
occurred_to: { type: "string", description: "Optional ISO date/timestamp upper bound on occurred_at. Date-only values are inclusive through that day's 23:59:59.999Z." }
146183
},
147184
output: {
148185
schema: {
@@ -160,7 +197,7 @@ export function createTools(ctx, service, config, embedder) {
160197
const items = value.items ?? [];
161198
if (items.length === 0) return TEXT_OUTPUT(`0 memory entries (of ${value.total}).`);
162199
const body = items
163-
.map((m, i) => `[${i + 1}] ${m.title} (type=${m.type}, importance=${m.importance})\n ID: ${m.id} | updated: ${m.updated_at}`)
200+
.map((m, i) => `[${i + 1}] ${m.title} (type=${m.type}, importance=${m.importance})\n ID: ${m.id} | updated: ${m.updated_at}${MEMORY_PROVENANCE(m)}`)
164201
.join("\n\n");
165202
return TEXT_OUTPUT(`${items.length} memory entries (of ${value.total}):\n\n${body}`);
166203
}
@@ -171,9 +208,10 @@ export function createTools(ctx, service, config, embedder) {
171208
type: args.type,
172209
limit: args.limit ?? 50,
173210
offset: args.offset ?? 0,
174-
includeArchived
211+
includeArchived,
212+
...occurredWindow(args)
175213
}));
176-
return { items: rows, total: service.count(args.type, { includeArchived }) };
214+
return { items: rows, total: service.count(args.type, { includeArchived, ...occurredWindow(args) }) };
177215
}
178216
}),
179217

@@ -199,6 +237,10 @@ export function createTools(ctx, service, config, embedder) {
199237
tags: { type: "array", items: { type: "string" } },
200238
content: { type: "string", required: true },
201239
source: { type: "string" },
240+
agent_scope: { type: "string" },
241+
workspace_scope: { type: "string" },
242+
sensitivity: { type: "string" },
243+
occurred_at: { type: "string" },
202244
created_at: { type: "string" },
203245
updated_at: { type: "string" }
204246
}
@@ -207,7 +249,7 @@ export function createTools(ctx, service, config, embedder) {
207249
},
208250
render: (_args, value) => {
209251
const m = value.memory;
210-
return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}\n\n${m.content}`);
252+
return TEXT_OUTPUT(`${m.title}\nID: ${m.id} | type: ${m.type} | importance: ${m.importance}${MEMORY_PROVENANCE(m)}\n\n${m.content}`);
211253
}
212254
},
213255
async execute(args) {

0 commit comments

Comments
 (0)