@a9i5k4/dsh-auto-memory 2.2.2 → 2.2.4

package/docs/M7-EMBEDDING-BENCHMARK.md

@@ -0,0 +1,164 @@
+# M7-2 Embedding / Tokenizer / Chunking Benchmark 报告
+
+> 日期:2026-08-24 · 阶段:M7-2(tested,未 live)
+> 计划:docs/M7-BENCHMARK-PLAN.md · 决策:docs/M7-ALGORITHM-DECISION.md
+> 机器可读:artifacts/m7-benchmark-pre/results.{json,csv};全量明细 runs/<runId>/
+> 语料:python/bench/m7b_corpus.py(L1 合成 152 记录/88 查询)+
+> artifacts/m7-corpus-pre/(L2 真实 251 episodes/40 手写查询)
+> 结论先行:**BAAI/bge-m3 + para-512-noov(段落对齐 512 token)胜出;multilingual-e5-large 因 zh→en 跨语言失败淘汰;qwen3-0.6B 为 hard-negative 判别备选但延迟/内存劣势。**
+
+## 1. 环境与模型 pin
+
+| 项 | 值 |
+| --- | --- |
+| CPU | AMD Ryzen 7 9700X,8C/16T,torch 2.13.0+cpu,threads=16(interop=1) |
+| RAM | 31.1 GB(空闲约 10 GB 时跑测) |
+| GPU | RTX 4070 Ti SUPER 16GB 在机但**未使用**(生产 sidecar 形态=CPU;驱动未动) |
+| Python | 独立 venv 3.10.11(D:\dsh-auto-memory\python\bench\.venv,不污染系统/不进 git) |
+| transformers | 5.15.1(build_inputs_with_special_tokens 已移除→探针法定位 special 前后缀) |
+
+| 模型 | revision(40hex 前 12) | license | 大小 | 维度 | pooling(仓库 1_Pooling 权威) | 查询侧约定 |
+| --- | --- | --- | --- | --- | --- | --- |
+| BAAI/bge-m3 | 5617a9f61b02 | MIT | 2.29GB | 1024 | CLS | 无前缀(模型卡 FAQ) |
+| Qwen/Qwen3-Embedding-0.6B | 97b0c614be4d | Apache-2.0 | 1.21GB | 1024 | last-token | Instruct/Query 模板(仅查询;官方代码核验) |
+| intfloat/multilingual-e5-large | 3d7cfbdacd47 | MIT | 2.26GB | 1024 | mean | query:/passage: 前缀 |
+
+- 全部逐文件 sha256 入 model-manifest.json;bge-m3 走 huggingface.co 官方
+  snapshot(关代理前),qwen3/e5 走 hf-mirror 分段下载并与上游 LFS oid
+  逐字节核验一致(直连 huggingface.co 在本机间歇性不可达,已记录)。
+- e5 硬上限 512 token(含 <s></s>,内容 510);bge-m3 8192;qwen3 32k
+  (retrieval 建议 8192)。本 bench doc 侧统一 1024 上限、e5 自动截到 510。
+- 缓存:python/bench/.hf-cache 与 python/bench/models/(未跟踪目录)。
+
+## 2. 方法学
+
+- Dense 输入一律模型自带 tokenizer,id 空间切 chunk,**无 jieba/无 JS lexical
+  预切**;chunker(段落/窗口)与 dense tokenizer 严格分层。e5 的 "passage: "
+  前缀并入 chunk 文本流(首 chunk 携带)。
+- 检索:NumPy float32 + L2 归一 + 精确点积;tie-break=score 降序→memoryId
+  字典序→chunkOrdinal。无 ANN/FAISS/HNSW/图。
+- 查询前按 workspaceRef scope 过滤(跨 workspace 泄漏=0 为硬断言);另设无
+  scope 诊断组量化镜像文档入侵率(证明 scope 门必须在宿主侧)。
+- L1 七类覆盖:zh→en、en→zh、混写、代码/路径/错误码、同主题 hard-negative
+  20 条双子、supersede 新旧 7 对、跨 workspace 镜像 6 对、多 chunk 长文 8 篇、
+  60 distractors。L2 为真实分布验证(见 §5)。
+- 每 (model×policy) 一个 configHash;两次全量重跑逐字节同分(确定性)。
+
+## 3. Chunk 策略(5 种,tokenizer id 空间)
+
+fixed-256/512/1024-noov(硬窗口无重叠)· para-512-noov(段落贪心装包,超长段
+切窗)· para-512-ov64(段内续窗 64 token 重叠)。
+L1 语料长尾:152 记录中 8 篇>256 token、2 篇>512、0 篇>1024,与生产
+(176 记录以短笔记为主+少量 runbook)同构。
+
+## 4. L1 结果(合成可控层,88 查询)
+
+| 模型 | 策略 | R@1 | R@5 | R@10 | MRR | nDCG@10 | 跨语@5 | 代码@5 | hard-neg err | supersede | p50/p95(ms) | 峰值RSS | 索引/千chunk |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| bge-m3 | fixed-256 | **0.818** | **0.989** | 0.989 | **0.894** | **0.977** | 1.00 | 1.00 | 0.111 | 0.50 | 123/184 | 2.05GB | 4.2MB |
+| bge-m3 | para-512 | 0.818 | 0.966 | 0.966 | 0.889 | 0.920 | 1.00 | 1.00 | 0.111 | 0.50 | 122/189 | 2.21GB | 4.0MB |
+| bge-m3 | fixed-1024 | 0.807 | 0.955 | 0.966 | 0.879 | 0.900 | 1.00 | 1.00 | 0.111 | 0.50 | 124/216 | 2.21GB | 4.0MB |
+| qwen3-0.6B | fixed-256 | 0.761 | 0.966 | **0.989** | 0.852 | 0.936 | 1.00 | 1.00 | **0.074** | 0.50 | 308/501 | 3.35GB | 4.1MB |
+| qwen3-0.6B | para-512 | 0.773 | 0.955 | 0.966 | 0.854 | 0.880 | 1.00 | 1.00 | **0.074** | 0.50 | 282/414 | 4.70GB | 4.0MB |
+| e5-large | fixed-512 | 0.455 | 0.727 | 0.807 | 0.585 | 0.639 | 0.60 | 1.00 | 0.074 | 0.38 | 142/222 | 3.94GB | 4.0MB |
+
+(完整 15 行见 results.csv;load 时间 bge-m3 2.8s/qwen3 1.1s/e5 3.2s;
+corpus 编码吞吐 41-48 chunks/s@bge-m3,全量 163 chunk≈4s。)
+
+要点:
+
+1. **bge-m3 全面第一**:R@5=0.989(fixed-256)、MRR/nDCG 最高、跨语言 20/20
+   全中、p95<300ms(RAM 2.2GB 内),延迟预算(5s deadline 的 1/10=500ms)内
+   余量 2.7-40 倍。
+2. **qwen3-0.6B**:质量次之但 hard-negative 判别最优(0.074 vs 0.111,双子
+   对更少排错);代价是 p50≈300ms/p95≈500ms(压线 500ms 预算)、峰值 RSS
+   3.3-4.7GB。指令模板+last-token 实现与官方逐条核验一致。
+3. **e5-large 淘汰**:修正 doc 前缀 bug 后 R@5 仍 0.727、跨语言仅 0.60
+   (20 条 zh↔en 查询错 8 条),MRR 0.58。失败集中在 zh 查英文文档与混写
+   长文,非实现问题(前缀/池化均按仓库配置)。另受 512 硬上限约束。
+4. **chunk 策略**:小 chunk 稳定占优——fixed-256 在两个可用模型上都是 R@5/
+   nDCG 最优;1024 最差;段落对齐(para-512)与硬切(fixed-512)在本语料
+   无显著差(多 chunk 记录仅 2 篇>512);overlap 64 无收益。**256 窗的
+   代价是 chunk 数(163 vs 154)+索引体积 +5%,可忽略。**
+5. **supersede 0.5 的构成**(bge-m3 失败 4/8):失败对全部是"旧记录短、直接
+   命中查询措辞;correction 长、答案埋在中段"的模式(jieba/分页/epoch 三对);
+   成功对(q085-088)是 correction 开头即结论。→ 纯 cosine 无法可靠优先
+   correction,**必须由 M7-3 融合层(supersede 边/时效)与 M7-6 多特征阈值
+   补偿**;这正是架构把 evidence/时效放在 JS/Python 分层的原因。
+6. hard-negative 3 例失败中 1 例(q003)gold 标注单源而代码记录 r032 同样
+   正确回答了问题(标注保守);真实错误 2 例(双胞胎 breaker/分页对)。
+7. 跨 workspace:scope 过滤下 6 镜像查询泄漏=0(硬断言过);无 scope 诊断组
+   镜像入侵率见 results.json xws_mirror_top5_unscoped——证明**scope 门必须
+   留在宿主侧,向量相似度无法区分同文异库文档**。
+
+## 5. L2 结果(真实 episode 层,251 episodes/40 手写查询)
+
+| 模型 | 策略 | R@1 | R@5 | MRR | nDCG@10 | hard-neg err | p50/p95(ms) |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| bge-m3 | **para-512** | 0.675 | **0.925** | **0.793** | **0.837** | 0.074 | 129/241 |
+| bge-m3 | fixed-512 | 0.675 | 0.925 | 0.792 | 0.836 | 0.074 | 136/213 |
+| bge-m3 | fixed-1024 | 0.675 | 0.925 | 0.791 | 0.836 | **0.037** | 135/230 |
+| bge-m3 | fixed-256 | 0.650 | 0.875 | 0.765 | 0.830 | 0.111 | 131/219 |
+| qwen3-0.6B | fixed-256 | 0.600 | 0.825 | 0.693 | 0.746 | 0.037 | 317/508 |
+| qwen3-0.6B | para-512 | 0.575 | 0.800 | 0.682 | 0.721 | 0.111 | 311/479 |
+| e5-large | fixed-1024 | 0.600 | 0.825 | 0.700 | 0.758 | 0.111 | 158/288 |
+| e5-large | para-512 | 0.600 | 0.800 | 0.697 | 0.755 | 0.111 | 149/481 |
+
+(全 15 行见 results.csv layer=L2。方法同 §2;episodes 来自
+.workbuddy/.codebuddy/.claude/.codex/.dsh 真实存储,脱敏后 train190/dev32/
+test29,查询为人工撰写,含 10 对真实 hard-negative。)
+
+要点:
+
+1. **L2 反转了 chunk 尺寸偏好**:真实 episode 上 512/1024 优于 256
+   (bge-m3 0.925 vs 0.875),与 L1 相反——真实记录的答案依赖上下文
+   (里程碑记录的细节在段中后部;Q/A 结构被 256 窗切断),而合成 gold 多为
+   紧凑陈述。hard-negative 错误也随窗宽改善(0.111→0.037@1024):真实双子
+   (M4/M5/M6 里程碑流)靠细节区分,细节在更大窗内存活。
+2. **bge-m3 优势在真实数据上扩大**:R@5 领先 qwen3/e5 12.5pt(0.925 vs
+   0.80),MRR 领先 10pt。qwen3 p95 仍 ~480-508ms(压 500ms 预算线)。
+3. en→zh 跨语言子集(lq04/22/23/24)三模型 4/4 全中——e5 的失败集中在
+   zh→en 方向(L1 20 条压力集),与已知不对称性一致。
+4. para-512 与 fixed-512 数字完全相同(本语料多 chunk 记录少,对齐算法
+   未触发差异),段落对齐是"零成本保险";ov64 无收益(几乎不触发)。
+5. L2 的 R@1(0.675)低于 L1(0.818):真实双子更难 + gold 标注单源保守
+   (部分 top1 其实也是正确答案,如并列的里程碑记录)。这正是生产分布的
+   真实难度,也是 M7-3 融合/M7-4 rerank 的改进空间。
+
+## 5.1 双层综合裁决
+
+| 决策项 | 裁决 | 依据 |
+| --- | --- | --- |
+| embedding 模型 | bge-m3 | 双层 R@5/MRR/nDCG 全一;L2 领先 12.5pt;p95 241ms;RSS 2.2GB |
+| chunk 策略 | para-512-noov | L2 最优(MRR 0.793/nDCG 0.837/R@5 0.925);L1 次优(-2.3pt);段落对齐保持语义单元完整;硬切无收益 |
+| 备选模型 | qwen3-0.6B | hard-neg 判别最优(L1 0.074/L2 0.037@256),保留观察;延迟/内存劣势明显 |
+| 淘汰 | e5-large | zh→en 失败(L1 xlang 0.60);512 硬上限;L2 亦无优势 |
+
+## 6. 资源与部署
+
+- 内存:一次一模型;bge-m3 峰值 2.2GB(含 torch+tokenizer+向量矩阵);
+  1 万 chunk 索引≈40MB(float32×1024d),10 万 chunk≈400MB,NumPy 精扫
+  仍可行(Stage-2 再评估 FAISS FlatIP,契约 §11.2)。
+- 离线:模型缓存在未跟踪目录+manifest sha256;新机部署=按 manifest 下载
+  pinned revision 并核验(直连或 hf-mirror 双通道已验证);CI 只用 fixture
+  vectors(tests/m7-2-fixtures/embedding-fixture.json),零联网零模型。
+
+## 7. 失败与偏差披露
+
+1. 首轮 e5 结果(0.68/xlang0.55)含实现 bug(doc 前缀未入 chunk 流),已修
+   并复跑;本报告数字全部来自修复后 run(runId 见 results.json)。
+2. e5 fixed-512 首轮崩溃=512 上限越界(512 内容+2 special),已修(内容截
+   510);该截断影响仅 e5 的 2 篇长文,已披露。
+3. M7-BENCHMARK-PLAN.md 在模型下载后补写(进入自主模式前的既有顺序),
+   方法与执行一致,已记录于 AUTONOMOUS-STATE。
+4. 延迟测量含查询编码+全矩阵点积(CPU 16 线程);不含进程启动/模型加载
+   (sidecar 常驻后一次性)。
+5. 本 benchmark 只覆盖 dense 检索质量;sparse/RRF/rerank 属 M7-3/M7-4,
+   lexical_pre_v2 基线对照在 M7-3 补齐(本阶段 Python 侧未复刻)。
+
+## 8. CI fixture
+
+fixture 从胜出组合(bge-m3 × fixed-256-noov)导出:33 文档×8 查询真实向量
+(float64 JSON)+期望 top5(NumPy 计算时即做过 scope 过滤);
+smoke-test-m72-pre.mjs 纯 Node 重算 exact cosine 断言逐位一致(K1-K7),
+不联网、不下载模型、不调 Python。

package/docs/M7-INTERFACE-DIGEST.md

@@ -0,0 +1,144 @@
+# M7 接口契约摘要（上下文压缩恢复用速查）
+
+> 生成:2026-08-24,来源:主 Agent 派发的只读研究(精读 lib/*.js + M5/M6-CONTRACT
+> + python/worker_pre_v1.py)。恢复会话时读本文件即可获得接线所需全部接口事实,
+> 不必重读全部源文件。权威仍以源码为准,本文件是精确摘要不是替代。
+
+## A. ContextPushEnvelopePre(JS→Python context_push payload,原样透传)
+
+```
+schemaVersion:1 | namespace:'dsh-auto-memory-pre' | kind:'context_push'
+observationId:'obs_pre_'+32hex
+session{sessionId, agentId, workspaceKey(已canonicalize), scope:'Session'|'Workspace'|'User'}
+cursor{eventSeq≥0, nativeSeq?, contextVersion≥0}
+index{memoryIndexVersion:'idx_pre_'+32hex(空语料=32个0), sourceEpochs[]}
+trigger/window: ContextSegmentPre[](≤8, UTF-8总字节≤4096)
+memoryRefs: AuthorizedMemoryRefPre[](≤8)
+evidence: EvidenceAggregatePre[](≤16)
+policy{contextPolicyVersion:'context_bridge_pre_v1', gatePolicyVersion, lexicalPolicyVersion(默认'lexical_pre_v2'), evidencePolicyVersion:'evidence_pre_v1'}
+budget{maxSegments:8, maxInputBytes:4096, maxMemoryRefs:8, maxEvidenceItems:16}
+observedAt(ms) | deadlineAt=observedAt+5000
+```
+ContextSegmentPre: segmentId,digest(≥16ch),kind:'user'|'tool_call'|'tool_result'|'assistant',eventSeq,contextVersion,ts,text,toolName?,toolOk?,errorName?,errorCode?
+AuthorizedMemoryRefPre: memoryId='mem_'+32hex小写, anchorId, scope:'Workspace'|'User', sourceRef=^(user|workspace|workspace-log):[A-Za-z0-9._\u4e00-\u9fff-]+$, sourceEpoch, sourceVersion≥1, fileDigest/recordDigest=64hex小写, excerpt≤480B(UTF-8 字节)。
+帧>64KiB 时 JS 先裁 window 再整体不发。
+
+## B. EvidenceAggregatePre
+
+memoryId(mem_+32hex), scope, freshness:'fresh'|'stale'|'unknown',
+distinctSessions, seen, read, cite, reuse, success, correction(全 int≥0),
+lastEvidenceAt(ms), policyVersion:'evidence_pre_v1'。
+AccessKind 六种:seen/read/cite/reuse/success/correction。Python 只读。
+
+## C. validateActivationRequestPre 硬校验(按序,失败='invalid:字段,字段')
+
+1 schemaVersion==1; 2 namespace; 3 kind=='activation_request';
+4 activationId 非空str; 5 observationId 必须前缀'obs_pre_';
+6 workerEpoch 非空str; 7 sessionId/agentId/workspaceKey 非空str;
+8 scope∈三值; 9 contextVersion int≥0; 10 miv==^idx_pre_[0-9a-f]{32}$;
+11 threshold{policyVersion非空, score有限, threshold有限, reason非空≤160ch};
+12 level∈['index','hint','excerpt','checklist','resource','full'];
+13 candidates 数组 1..8 条; 14 ttlSteps int 1..10;
+15 createdAt 有限; 16 expiresAt≥createdAt。
+candidate: candidateId非空, memoryId=mem_+32hex, anchorId非空,
+scope∈'Workspace'|'User', sourceRef白名单正则, sourceEpoch非空,
+sourceVersion int≥1, fileDigest/recordDigest=64hex小写,
+score有限∈[0,1]; excerpt≤480 UTF-8字节(超=硬拒'excerpt-budget');
+checklist≤8项×≤120字符。
+
+## D. natural pre-step claim(激活全链路)
+
+worker 输出帧 type='activation_request', payload={activation:{...}}(嵌套一层!)。
+client: epoch 门→activationId 存在→256 环去重→activationHandlers。
+context-host 注册 onActivation→activation-host.offerExternalActivation(activation)。
+offer 门:assoc∧inbox(enabled) ∧ sourceMode=='python'(assoc∧inbox∧pythonBackend)
+→ inbox.offerActivation:validator→身份三元组逐字一致→duplicate→suppress 名单
+(命中=整单拒'suppressed-candidate')→cursor 门(cv<当前=stale-context)→
+index 门(miv≠当前=stale-index)→构建 pending ReferenceTailPacketPre。
+消费:下一次 agent/pre-step→stepFor 自增→setCursor→claim 四重门:
+①cooldown(nowStep≤cooldownUntilStep 拒,投递后 cooldown=2 步)
+②TTL(nowStep≥expiresAtStep=offer步+ttlSteps→expired 丢)
+③cv 精确不等→stale-context 丢 ④miv 不等→stale-index 丢。
+渲染 systemPrompt.context 组件 'dsh:m6-reference-tail-pre'→digest 复核→
+markDelivered→异步按 references 建 kind='seen' evidence。
+latest-wins:同 packetId=duplicate-packet;新 pending 顶旧(replaced)。
+offer reason 全集:pending,replaced,duplicate-packet,duplicate-activation,
+duplicate-observation,stale-context,stale-index,identity-mismatch,
+suppressed-candidate,invalid-request,disabled,source-not-python,no-activation-id,disposed。
+
+## E. SidecarClient API
+
+createPythonSidecarClientPre({command='python', scriptPath, dshHome='',
+requestTimeoutMs=5000, maxLineBytes=256KiB, breakerFailureThreshold=3,
+breakerCooldownMs=30000, maxPendingRequests=64})——值或()=>值惰性。
+request(type,payload,{timeoutMs,signal}): type∈health|context_push|
+index_sync_begin|index_sync_page|index_sync_commit。永不 reject:
+{ok:true,frame} | {ok:false,code,reason?,retryInMs?,timeoutMs?,detail?}。
+code 全集:disposed,unsupported-frame,circuit-open,unavailable,crashed,
+backpressure,protocol,timeout,aborted,worker-error。
+notify(type,payload)(cancel/close_session 无响应帧), health(), restart(),
+dispose(), ensureStarted(), isStarted(), currentEpoch()='wk_pre_'+32hex/次启动,
+onActivation(h)→unbind。帧七字段:protocolVersion='m7_wire_pre_v1',frameId,
+requestId,workerEpoch,type,payload,sentAt。
+
+## F. PythonContextSinkPre 映射
+
+deadlineAt 已过→ack{accepted:false,reason:'stale'};否则 timeoutMs=
+min(requestTimeoutMs, deadline-now)。ack 校验 validateContextAckPre+
+observationId 逐字回显;失败→'unsupported'。code→reason: timeout/aborted/
+backpressure→busy;其余→unsupported。close_session→notify。异常永不冒泡。
+
+## G. worker_pre_v1.py 关键事实(M7-3 扩展基础)
+
+- 纯标准库;JSONL;MAX_LINE_BYTES=256KiB(超限=fatal 'line-oversize' 后 break);
+  stderr 预算 64 条。
+- canonical():键排序+无空白+UTF-8,与 JS canonicalJson 逐字节一致;
+  pageDigest=sha256(canonical(records));finalDigest=sha256(canonical(
+  {kind:'index_sync_final_pre_v1',syncId,miv,workspaceRef,scope,
+  recordCount,pageCount,pageDigests}))。
+- 拒绝矩阵:no-active-sync/unknown-sync/page-duplicate/page-out-of-order/
+  count-mismatch/page-size/record-count-mismatch/record-scope-mismatch/
+  page-oversize/digest-mismatch/missing-page/final-digest-mismatch/
+  version-mismatch;任一终局失败→active_sync=None 整次作废。
+- derived[(workspaceRef,scope)]→entry{miv,recordCount,pageDigests,
+  finalDigest,records};persist_derived→<dsh-home>/memory/semantic-pre/
+  derived-corpus.json(tempfile+os.replace 原子,fsync)。policyVersion=
+  'semantic_derived_pre_v1'。
+- context_push:幂等(seen_obs→busy);ack 先行;activation 帧 ack 后同批输出;
+  obs 幂等键随 close_session 清。
+- 帧 frameId='res_'+sha(rid+':'+type)[:32];activation 帧 payload 嵌套
+  {activation:...},fid_prefix='act_'。error 帧 payload={code,reason}。
+- epoch 不符='epoch-mismatch' 错误帧;未知 type='unknown-type';
+  任何帧异常→'internal-error' 永不死循环。
+
+## H. Python 侧激活雷区(from validator 反推)
+
+1. observationId 只能来自收到的 envelope;同 inbox 重复=硬拒。
+2. miv 两时刻(offer+claim)都必须与 host 当前一致。
+3. claim 时 cv 精确相等;响应要快,cv 用最新 envelope 的。
+4. offer 本身耗一步;ttlSteps=1 下一步立即过期,实用值≥2。
+5. 投递成功后 cooldown 2 步,别每步连发。
+6. score∈[0,1] 有限;excerpt 480 UTF-8 字节(中文≈160字)。
+7. candidates 1..8;跨 memoryId 同 recordDigest JS 去重保最高分。
+8. digest 全小写 hex;sourceVersion≥1;sourceRef 正则严格(禁空格/斜杠/第二冒号)。
+9. 身份三元组逐字一致;workspaceKey 用 envelope 的 canonicalize 值。
+10. workerEpoch 逐帧回显;activationId client 侧 256 环去重(重发静默吞)。
+11. payload 必须嵌套 {activation:{...}}。
+12. 渲染预算 4096B;checklist 压成'; '单行;provenance 三行永不截断。
+13. suppressMemories(correction/revoked)命中任一候选=整单拒。
+14. Python 管语义分,JS 管身份/时序/预算;threshold 不能替代用户授权。
+
+## I. M7 阶段门(来自任务集 docs/M7-TASKSET-DISPATCH.md)
+
+M7-2 benchmark(本阶段)→M7-3 dense/sparse/hybrid(bm25s/FTS5/weighted/RRF,
+RRF k=60 研究初值需消融冻结)→M7-4 bounded rerank(bge-reranker-v2-m3/
+Qwen3-Reranker-0.6B/FlashRank;timeout 保序)→M7-5 graph 条件门(LongMemEval/
+LoCoMo/自有多跳集证明不足且 graph 显著改善才做;networkx/PPR;不过=记录
+skipped-by-benchmark 视为正确)→M7-6 双阈值激活(suppress/prefetch/activate,
+T_on>T_off 滞回,shadow calibration 先行)→M7-7 judgement shadow→M7-8 人工门
+(唯一:严禁自行重启 3080)。
+Clustering Shadow 是任务集第七节:M7-3 之后 M7-4 之前的独立 shadow 阶段
+(ARI/NMI/B-cubed/noise recall/跨语言同簇率/bootstrap stability)。
+纪律:每阶段 checkpoint 按 configHash 跳过已完成 run;一时刻一模型;
+有限重试;状态文件每阶段备份;不删不识别旧 artifact(标 orphaned);
+每阶段回写 5 份文档;全量回归串行。

package/docs/M7-LABEL-REVIEW-REPORT.md

@@ -0,0 +1,107 @@
+# M7 Activation Calibration 标签复核与定向扩充报告
+
+> runId:`label-review-cal20260824-1954` · 日期:2026-08-24
+> 上游:`artifacts/m7-live-pre/calibration-cal20260824-1855/`(Phase F 校准,verdict=`insufficient_gold_for_active`)
+> 本轮性质:**只做语义标注、边界样本与人工复核材料**——零代码改动、零阈值调整、零开关操作。
+> 状态:**active canary remains prohibited until human gold is imported.**
+
+## 1. 三类标签的严格区分
+
+| 类别 | 数量 | 说明 |
+| --- | --- | --- |
+| existing silver labels(已复核) | **73** | `existing-labels-reviewed.jsonl`:逐条附 proposedAction/recallIntent/dialogueAct/echoRisk/taskNeed/scopeStatus/freshnessStatus/rationale/disagreement |
+| new synthetic silver labels | **109**(56 组 counterfactual pairs) | `counterfactual-pairs.jsonl`:全部锚定真实 parent 记录,仅改变 query 表达与需求强度;`synthetic=true`,`isGold=false` |
+| user-confirmed gold labels | **26**（第一批已导入；见 §9） | `gold-confirmed.jsonl`：A11 / P11 / S4，含 7 条对 agent 提案的覆盖与 2 条暂缓挂起 |
+
+## 2. 既有 73 条复核结果
+
+- **维持原判 71 条;修正 2 条**(`disagreementWithPreviousLabel=true`):
+  - `cal-0036`(HarmonyOS 开发指引清单):prefetch → **suppress**。原判预设"外部项目知识可作背景 prefetch",但在 dsh-core 生产 scope 下目标(claude 来源)不可达也不应出现;expected 转入 forbidden(wrong-scope)。
+  - `cal-0037`(PsychoPy 技术栈):同上,prefetch → **suppress**。
+- **action 分布变化**:activate 31 / prefetch 16→14 / suppress 26→28。
+- **新增维度标注**(全部 73 条):echoRisk 高 2(面条/天气回声)/中 1/低 3;dialogueAct question 39·request 15·planning 10·error-report 4·statement 2·acknowledgement 1·other 2;taskNeed required 31·optional 14·none 28;scopeStatus invalid 9。
+- **remaining ambiguity**(3 项,需用户裁定):
+  1. `cal-0020`:envelope 预算查询检索第一名为 ep_11f4f11b6beeabb2 而 gold 标 ep_9695c53761cd879c——可能并列正确,可用选择栏 E 改写目标集合;
+  2. `cal-0029` 等 lq 继承样本:父记录属外部 codex 工作区,L2 无 scope IR 协议下标 activate 成立,生产 scoped 部署后应视为 wrong-scope;
+  3. `cal-0007/0008/0039`:概览型/演进型问题的 activate-vs-prefetch 归类依赖使用习惯,建议由用户定调。
+
+## 3. 边界人工复核队列(28 条,`boundary-review.md`)
+
+按任务书十项优先级选出,覆盖:
+
+| 优先级类别 | 样本 |
+| --- | --- |
+| 高分 suppress(回声陷阱本体) | cal-0009(0.651)、cal-0010(0.580) |
+| 最高/最低 activate | cal-0003/0001/0024 ↔ cal-0005/0016/0068 |
+| act/prefetch 边界 | cal-0007/0008/0039/0044 |
+| recall vs 陈述对照 | cal-0001↔cal-0009、cal-0015 |
+| correction/supersede | cal-0014、cal-0015、cal-0005 |
+| wrong-workspace/stale | cal-0036/0037/0055/0058 |
+| 中英跨语言召回 | cal-0002、cal-0031、cal-0035 |
+| 目标不唯一 | cal-0066、cal-0045、cal-0008、cal-0020 |
+| harmful 风险 | cal-0062、cal-0060、cal-0059、cal-0073 |
+
+每行给出 query / 候选摘要 / 观测分 / 建议 / expected / forbidden / harm / 简短理由 / 用户选择栏(A/P/S/H/E)。**用户只需审这 28 条,不必看全量语料**;确认后置 `labelSource=human`、`isGold=true`,交回校准流程重算阈值。
+
+## 4. Counterfactual pairs(56 组 / 109 条,`counterfactual-pairs.jsonl`)
+
+设计原则:同一真实记忆在不同对话意图下应得不同 action——**不发明新用户事实**,只改表达与需求程度。分组:
+
+| 类别 | 组数×条数 | 代表例(同一 parent) |
+| --- | --- | --- |
+| explicit recall vs semantic echo | 12 组 ×26 | 午饭:A"之前午饭吃了什么?"→activate ∥ B"今天这碗面挺好吃。"→suppress;BGE-M3:A"为什么选它?"→activate ∥ B"看起来不错。"→suppress ∥ C"准备评估新模型。"→prefetch |
+| task failure/repeat vs normal planning | 8 组 ×16 | stale-context 再现→activate ∥ "之后留意 contextVersion"→prefetch;"又失败,之前确认的方式是什么?"→activate |
+| old fact vs correction/supersede | 8 组 ×16 | jieba 勘误对(问现状→返回新权威=activate;坚持旧法→harmful suppress);发布策略新旧两版 |
+| 同主题不同 workspace | 8 组 ×16 | 同一 query 在 ws/dsh-core→suppress(forbidden=外部记录) vs 源工作区 scope→activate(workspaceScope 字段区分,可直接供未来 scoped harness 使用) |
+| zh/en/mixed 变体 | 8 组 ×17 | 琥珀协议 zh/en/mixed 三连;validator 双语对 |
+| 代码/路径/错误码/包名锚点 | 6 组 ×6 | ev_pre_ cov=0.035、finish_reason=network_error、pkt_pre_ a602f2aa、503 Endpoint、finalDigest、obs_pre_ 幂等 |
+| 低信息/闲聊/acknowledgement 对照 | 6 组 ×12 | "好的,继续。"→suppress ∥ "好的,继续说 inbox 门序。"→activate;"谢谢!"∥"谢谢。另外确认下 BM25 的 b 值。" |
+
+- action 分布:activate 65 / suppress 35 / prefetch 9(harmful 8);语言:zh 94 / mixed 9 / en 6。
+- split 按 pairId 哈希分组:train 92 / dev 10 / test 7,**同组绝不跨 split**。
+- 全部 expected/forbidden 指向经存在性校验的真实 `mem_*`/`ep_*` id;parentWorkspace/scopeCaveat 字段显式标明外部工作区归属。
+
+## 5. 质量检查(`validation-report.json`:problemCount=0)
+
+通过项:id 唯一性 · memoryId 格式与 corpus 存在性 · expected∩forbidden=∅ · pair 不跨 split · 敏感模式扫描(token/手机号/绝对路径/app_secret 零命中) · system/runtime 提示标记零泄漏 · 近重复查重(跨 workspace 对照组的同文异 scope 为设计意图,已按 workspaceScope 维度放行并记录)。
+
+## 6. 需要用户确认的最小集合
+
+1. **28 条边界样本**(`boundary-review.md` + `gold-import-template.jsonl`)——这是导入 gold 的唯一入口;其中第 1、2 行(面条/天气回声)与 2 条"(改)"行(cal-0036/0037 的 prefetch→suppress 修正)优先。
+2. **3 项 remaining ambiguity**(§2):cal-0020 并列 gold、外部工作区继承样本的 scope 口径、概览型问题归类偏好。
+
+## 7. 结论与停止声明
+
+- 语料判定:用于发现问题/设计激活特征**够用**;第一次人工校准在补入本轮成对场景后**基本够**;宣称生产阈值稳定**还不够**(需 gold 导入+特征层修正后的真实流量回归,见校准文档 §8)。
+- 本轮未做且不做:阈值/权重调整、threshold grid 生产决策、active 切换、Python worker/JS Host/M6 修改、3080 重启、真实 MEMORY.md/Anchor/AccessEvidence/Procedure 写入、AI 标签转 gold、按目标分布强行平衡、"模型觉得相关"替代 taskNeed 判断。
+- **active canary remains prohibited until human gold is imported.**
+
+## 8. 复核进展（2026-08-24 晚更新）
+
+**第一批人工裁决已导入**（`boundary-review.xlsx` → `apply_decisions.py` → `gold-confirmed.jsonl` + `user-decisions-applied.json`）：
+
+- **26 条翻转 human gold**：A11 / P11 / S4。回声双煞（cal-0009/0010）确认 suppress。
+- **对 agent 提案的 7 条覆盖**（全部忠实记录）：cal-0044 prefetch→**activate**；cal-0036/0037/0055/0058 suppress→**prefetch**（跨工作区内容按"建议性联想"处理，标签带 `requiresCrossWorkspaceRelay` 标记——其 gold 生效以议题③a 的联想设置落地为前提，当前 scoped 检索验证不到，重算时单列）；cal-0060/0059 harmful→**false**（用户口径：advisory 参考/AI 自行决定、用户明示时 procedure 照办——转化为议题②中"advisory-only 呈现面"的设计要求）。
+- **2 条挂起**（cal-0062 手机号 / cal-0073 API token）：不设字母、附理由"由用户设置决定直接提醒还是仅记忆库可查；不提醒会否丧失记忆系统意义"→ 并入主 Agent 议题③b 敏感度三档，档位定案前不设 gold。
+- cal-0008 批注"P(可考虑a)"按 P 落盘、备注保留。
+
+**配额状态**：距每类 ≥15 差 S×11 / A×4 / P×4。已生成第二批快速确认表 `cf-review.xlsx`（32 条 counterfactual 预筛样本：S15 / A11 / P6，同一真实记忆在不同意图下的最小对照），并已用生产 embedder 对全部 109 条 counterfactual 完成预打分（`cf-scored.jsonl`，向量缓存在 `vec-cache/`）——第二批填完后合并重算是即时的。
+
+**预期终点**：两批合计 gold ≈ A22 / P17 / S19，届时首次具备 gold 支撑的 precision/recall 与阈值网格（含真 gold 维度的 echo-trap 分离检验）。
+
+## 9. 真 Gold 阈值分析结果（2026-08-24 深夜，`metrics-gold.json` / `threshold-grid-gold.csv`）
+
+两批合计 human gold **58 条（A22 / P19 / S17），每类 ≥15 达标**；4 条跨工作区 relay 样本单列、2 条敏感度挂起。对 54 条可评估 gold 的首份真指标：
+
+- **当前阈值（0.62/0.52）下的 2 次 emit 全部是错误激活，且都来自面条回声家族**：cal-0009「中午那碗面条挺不错的。」(0.6507) 与 cf-002 同句变体 (0.6254)。回声陷阱从 silver 推断升级为 **human-gold 实证**。
+- 混淆矩阵（当前）：S→{emit 2, prefetch 2, suppress 13}；A→{prefetch 5, suppress 17}；P→{suppress 15}。actPrecision=0，actRecall=0，sViolations=4，harmfulEmit=0。
+- **分离度在用户精炼标签下依旧不成立**：maxSuppress 0.6507 > maxActivate 0.5914；高于最弱 activate-gold 的 suppress-gold 至少 8 条（两条面条回声 + jieba 复活 + 若干低信息组）。
+- 契约网格内最优格（argmin 有害→S 越界→正确量）仍为 0.55/0.50：8 emit 中 4 正确（precision 0.50 / recall 0.182）、S 越界仍 4——**没有任何格子同时满足 precision 优先与可用召回，维持 shadow 的结论现在有人工 gold 支撑**。
+- 检索层：gold 目标 Recall@5=@8=0.75。
+- 正式判定措辞更新：~~`insufficient_gold_for_active`~~ → **`gold_quota_met_but_score_not_separable`（gold 配额已满足；语义分不可分）**——进 active 的剩余条件收敛为校准文档 §8 的特征层修正（回声抑制/意图信号/margin-evidence 门）+ 修正后重标定。
+
+## 10. 交接状态
+
+- 主 Agent 三议题（自进化路径 / 审批工作流 / 个性化设置：跨工作区联想开关 + 敏感度三档）已入长期记忆，汇报时随附。
+- 待办归属：cf-008/014 等"P 化评价句"与 cal-0036/0037/0055/0058 的 relay gold 共同构成议题③a 的验收用例；cal-0062/0073 构成议题③b 的验收用例；cal-0059/0060 的 advisory 口径转化为议题②的 advisory-only 呈现面需求。
+- 本轮全程零生产改动、零开关操作、零 commit；active canary 在特征层修正并重标定通过前保持禁止。

package/docs/M7-LEXICAL-TUNING.md

@@ -0,0 +1,58 @@
+# JS 词法降级层（lexical_pre_v2）调优实验报告
+
+> 2026-08-25 · 动机：用户提议用 M7 模型经验调优 JS 词法降级链路，让"不开语义增强"
+> 的基础层尽量可用。方法：全部在 artifacts/m7-live-pre/lexical-tuning/ 用
+> **打补丁的副本变体**离线实验，生产代码零改动。评测：L2 真实语料
+> （251 episodes / 40 条手写查询，含 hard-negative 对），复用生产
+> `buildQueryPlan` + `lexicalSearch`，ep→mem id 双射映射仅重命名。
+
+## 基线
+
+| R@1 | R@5 | MRR | nDCG@10 | negHit@5 |
+| --- | --- | --- | --- | --- |
+| 0.050 | **0.200** | 0.129 | 0.140 | 0.075 |
+
+参照：dense bge-m3 同语料 R@5=0.925。差距主体是**词汇改述鸿沟**
+（见失败分析），不是参数问题。
+
+## 实验结果（全部变体）
+
+| 变体 | 改动 | R@5 | MRR | nDCG@10 | 判定 |
+| --- | --- | --- | --- | --- | --- |
+| **v03_b045 / v03b_b030 / g_k*_b*** | **BM25 长度归一 b: 0.75→0.45(或 0.30)，k1 不敏感** | **0.225** | **0.176–0.178** | 0.181–0.190 | ✅ **唯一正收益**：MRR +37%，nDCG +36%，R@1 翻倍 |
+| v01_notrunc | 取消 maxCjkGrams=64 截断 | 0.150↓ | 0.117↓ | 0.116↓ | ❌ 反直觉否决：全文 token 流抬高 avgdl 后长文被归一惩罚压得更狠，且 negHit@5 升到 0.10 |
+| v04_unigram | CJK run 补充单字 token | 0.150↓ | — | — | ❌ 稀释精度 |
+| v02_negstop | 停用词否定词豁免（不/别/没…开头） | 0.200 = | = | = | ⚪ 本集零收益零损害（当前查询无被误杀否定词）；作为防御性修正可随 v3 顺带 |
+| g_w_cov80 / g_w_head25 | 评分权重 0.72/0.15 重分配 | 0.200 = | ≈ | ≈ | ❌ 不敏感 |
+| g_below005 | below-score 门 0.10→0.05 | 0.200 = | = | = | ❌ 不敏感 |
+| 截断率诊断 | 32-term 查询预算 | — | — | — | 0/40 触发，非瓶颈 |
+
+## 失败案例分析（b=0.45 下）
+
+命中的查询（lq02 rank3、lq03 rank2）都与 episode 原文**共享术语**
+（"M7 contract freeze"、"tokenizer/chunking"）。miss 的（lq01 rank48、
+lq04/lq06 >64）全是**改述型问句**——查询用"调研比较/许可证"，episode 写的是
+具体模型名和结论。这个鸿沟是词法匹配的定义性局限，正是 dense 语义层存在的理由。
+
+## 结论与建议
+
+1. **值得进生产的一项**：BM25 `b: 0.75 → 0.45`（短笔记语料的长度归一过强是
+   实测失配；k1 维持 1.2）。收益：MRR +37% / nDCG +36% / R@1 ×2，零成本。
+2. 顺带项：否定词停用豁免（防御性，本集中性）。
+3. 其余直觉假设（取消截断/unigram/权重重分配）均被数据否决——保留现状。
+4. **版本纪律**：若采纳，须按流程走 `lexical_pre_v3`：JS 改
+   `SHADOW_GATE_POLICY_PRE_V1.dictionaries.bm25` 并升 policyVersion +
+   decision record；**Python worker `_lexical_scores` 的 BM25(k1,b) byte-twin
+   必须同步**（D6 融合两臂一致）；m70/m71/m73 smoke 断言更新；全量回归。
+5. 产品叙事的实证支撑：调优后基础层 R@5 仍只有 ~0.225 vs 语义层 0.925——
+   "基础层可用、语义层显著更强"的两级定位有了数字背书，RELEASE-SEMANTIC-OPTION.md
+   的可选安装决策不受影响、反而更站得住。
+
+## 复现
+
+```bash
+cd artifacts/m7-live-pre/lexical-tuning
+node eval_lexical.mjs                 # 基线（生产 lib）
+python make_variants.py               # 生成变体副本
+node eval_lexical.mjs v03_b045.js     # 任一变体
+```

package/docs/M7-LIVE-SHADOW-SCRIPT.md

@@ -0,0 +1,30 @@
+# M7 live 脚本化受控 shadow（第 1 门）—— 用户逐条发送，Agent 逐条对账
+
+> 环境：DSH **dsh-auto-memory 工作区**（当前工作区，候选库=8f3aa131b2a2 含全部项目记忆）
+> 发射档：**shadow**（本阶段只看决策行，不注入）
+> 发送方式：每条作为一条独立消息发给 DSH；可自然衔接（模拟真实对话流）。
+> 目标：18-24 条覆盖 中英回忆/生活 echo/correction/wrong-scope/stale/tool-failure，
+> 核对线上 fv2 决策 vs 离线预期一致性。
+
+## 预期决策表（Agent 逐条核对 shadow 行）
+
+| # | prompt（可直接复制） | 类别 | 预期 lane | 预期 decision | 预期 top 锚点 |
+|---|---|---|---|---|---|
+| 1 | 之前研究 DSH 推理参数的时候，sub.vankit.top 支持的推理档位是怎么划分的？我印象里是七档，从 off 到 max，是这样吗？ | 中回忆 | explicit | **emit** | mem_af41b67947（DSH 推理） |
+| 2 | What's the native pipeline of the memory plugin? I mean the event→inbox→claim chain. | 英回忆 | explicit | emit | mem_11aaf8cc9f（原生链路） |
+| 3 | 我们记忆模型第一阶段是隔离 working 和 short-term，按 sessionId 隔离工作记忆，对吧？ | 中回忆(weak) | explicit | prefetch/emit | mem_2181f50112（记忆模型） |
+| 4 | 技术选型那块，bge-m3 用的什么 embedding provider？ | 中回忆 | explicit | emit | mem_d6cf24d8a3（技术选型） |
+| 5 | 今天中午吃的面条挺不错的。 | 生活 echo | proactive | suppress | —（echo veto） |
+| 6 | 对了，上周那个抽卡演出的像素化要求是多少来着？ | 中回忆(跨ws) | explicit | suppress(跨工作区隔离) | —（当前工作区无此记忆） |
+| 7 | 之前 Host 架构里，记忆包注入点是 pre-step 和工具边界，对吧？ | 中回忆 | explicit | emit | mem_666765a7f2（Host 架构） |
+| 8 | This plugin listens to the model's chain-of-thought, right? | 英回忆 | explicit | emit | mem_666765a7f2/mem_11aaf8cc9f |
+| 9 | 我记错了，其实 DSH 推理不是七档，是五档。 | correction | explicit | suppress(hard_gate_correction) | — |
+| 10 | 说点别的，天气不错。 | chitchat | proactive | suppress(low_signal) | — |
+| 11 | Python sidecar 的 worker 脚本叫什么？ | 中回忆 | explicit | emit/prefetch | 相关日志锚点 |
+| 12 | 帮我总结一下今天的工作。 | 总结请求 | proactive | prefetch/emit | 今日日志锚点 |
+| 13 | 那个 vankit 七档参数，off 档是不是不发送推理参数？ | 中回忆 | explicit | emit | mem_af41b67947 |
+| 14 | What about the lexical fallback tier, how does it work? | 英回忆 | explicit | prefetch/emit | 相关锚点 |
+| 15 | （发一条工具调用，如 `read 文件`） | tool-failure | — | — | — |
+
+## 对账方式
+用户发完一轮后，Agent 读 `activation-shadow-v2.jsonl` 最新若干行，逐条核对 lane/decision/reasonCodes/candidateProvenance vs 上表预期；差异逐一归因（检索未中/阈值/echo 误判等）。

package/docs/M7-PYTHON-IMPLEMENTATION-REPORT.md

@@ -0,0 +1,92 @@
+# M7 Python Semantic Engine 实施研究报告
+
+> 日期：2026-08-23
+>
+> 项目：dsh-auto-memory
+>
+> 基线：M0-M6 全部 live verified；**M7-0/M7-1 已实现并 tested(2026-08-24,默认关闭零进程零 IO;未 live)**；M7-2 起待实施
+>
+> 用途：交给负责 Python 后端的外部 Agent
+>
+> 权威架构：docs/proactive-associative-memory-system-map.html
+>
+> 详细契约：docs/PYTHON-SIDECAR-CONTRACT.md
+
+## 1. 执行结论
+
+M7 是 Python Semantic Engine 阶段。Python 负责 embedding、精确 dense retrieval、hybrid fusion、可选 rerank、可选 graph expansion、每会话语义状态和主动 activation threshold。JS Host 继续负责身份、scope、MemoryId、Anchor/FileIndex、provenance、AccessEvidence、预算、TTL、风险和 Reference Tail 的最终投递。
+
+目标链路：
+
+~~~text
+JS M5 ContextPushEnvelopePre + EvidenceAggregatePre
+  -> JS 授权分页 index_sync
+  -> Python embedding / dense / hybrid / rerank / graph
+  -> Python semantic threshold + hysteresis
+  -> ActivationRequestPre
+  -> JS M6 validator + Activation Inbox
+  -> ReferenceTailPacketPre
+  -> 下一请求 Reference Tail
+  -> delivered ack -> JS M5 seen evidence
+~~~
+
+关键接口结论：live ContextPushEnvelopePre 的 memoryRefs 最多 8 条，来自 lexical_pre_v2 预取。它适合即时上下文和 rerank，但不足以支撑 Python 全库主召回。因此 M7 必须增加 JS 授权、分页、版本化的 index_sync；Python 永远不能自行打开 Markdown、sidecar 或 session 文件。
+
+## 2. M5/M6 live 基线
+
+- ContextPushEnvelopePre：8 segments、4096 input bytes、8 refs、16 evidence items、480-byte excerpt、64 KiB frame、5 秒 deadline；observationId 是确定性 obs_pre_ identity。
+- Evidence：JS 创建 seen/read/cite/reuse/success/correction，持久化使用 sesr_/wsr_ 隐私投影；Python 只读 aggregate。
+- ActivationRequestPre：M6 硬校验 workerEpoch、session identity、scope、contextVersion、idx_pre_ memoryIndexVersion、candidate provenance、level、TTL 和预算。
+- M6-4 活体验证证明 Reference Tail 进入 model-visible messages，delivery ack 后 seen 落盘；fake inject-and-pump 仅为演示，真实 Python 走自然 pre-step claim。
+
+## 3. index_sync
+
+Python 需要完整授权语料，不只是 context_push.memoryRefs top-8。JS 通过 index_sync begin/page/commit 分页发送带 memoryId、anchorId、scope、workspaceRef、sourceRef、sourceEpoch、sourceVersion、fileDigest、recordDigest、授权 text、chunk 元数据的 records。所有 page/final digest 和 memoryIndexVersion 通过后，Python 原子切换 derived index；Python 不发现文件。
+
+## 4. 算法路线
+
+Stage 1：176 records 到约 1 万 chunks，NumPy float32 exact cosine + bm25s/FTS5 或 BGE sparse + RRF(k=60) 研究初值 + optional bge-reranker-v2-m3 top50→top10，graph 默认关闭。
+
+Stage 2：1 万到 10 万 chunks，根据 latency/持久化 benchmark 选择 FAISS IndexFlatIP/HNSW、hnswlib、sqlite-vec 或 usearch。
+
+Stage 3：只有多跳 benchmark 证明收益后，才做 networkx/PPR 或 HippoRAG-style graph；Graphiti/LightRAG 不作为起步依赖。
+
+Embedding 候选：BGE-M3（MIT/1024d/长上下文/dense+sparse 多表示）、Qwen3-Embedding-0.6B（Apache-2.0/1024d/多语言与代码）、multilingual-e5-large（MIT）。模型、revision、license、dimension、normalization、configHash 和 source provenance 必须随 vector 绑定；不匹配即 stale。
+
+## 5. Memory judgement
+
+Python 可输出 noise、working_only、episodic_candidate、semantic_candidate、profile_candidate、procedure_candidate、resource_candidate、conflict_or_supersede_candidate 以及 keep/link/merge/supersede/discard/promote suggestion；每条必须带 source IDs、context/index version、support/counter evidence、confidence、policyVersion。仅 shadow audit，不写权威 memory。
+
+## 6. 评测
+
+比较 lexical_pre_v2、dense、sparse、weighted、RRF、rerank、graph、active threshold 和 stale/fallback arms。指标包括 Recall@K、MRR、nDCG、activation precision/recall、helpful/harmful tail、stale/drop/fallback、p50/p95 latency、memory/cost、delivery funnel 和 cross-session/workspace leakage=0。使用 M5 replay、M6 fixtures、LongMemEval、LoCoMo；CI 不联网调用模型，使用 fixture vectors。
+
+## 7. 必须复用的参考
+
+- BGE-M3：https://huggingface.co/BAAI/bge-m3
+- Qwen3 Embedding：https://huggingface.co/Qwen/Qwen3-Embedding-0.6B
+- BGE reranker：https://huggingface.co/BAAI/bge-reranker-v2-m3
+- Sentence Transformers：https://github.com/UKPLab/sentence-transformers
+- FlagEmbedding：https://github.com/FlagOpen/FlagEmbedding
+- FAISS：https://github.com/facebookresearch/faiss
+- hnswlib：https://github.com/nmslib/hnswlib
+- bm25s：https://github.com/bm777/bm25s
+- ranx：https://github.com/AmenRa/ranx
+- HippoRAG：https://github.com/OSU-NLP-Group/HippoRAG
+- A-MEM：https://github.com/agiresearch/A-mem
+- Graphiti：https://github.com/getzep/graphiti
+- LongMemEval：https://github.com/xiaowu0162/LongMemEval
+- LoCoMo：https://github.com/snap-research/locomo
+
+安装前必须按 pinned revision 重新核验 license、依赖、模型元数据和复现方式。
+
+## 8. 实施进度(2026-08-24 更新)
+
+- **M7-0 完成(tested)**:m7_wire_pre_v1 协议冻结并实现——lib/m7-wire-pre.js(纯核心)+python/worker_pre_v1.py(纯标准库确定性 fake worker)+lib/python-sidecar-client-pre.js(no-shell spawn/epoch/JSONL framing/timeout/AbortSignal/crash recovery/circuit breaker,结构化失败永不抛出)+lib/context-sink-python-pre.js(消费 ContextPushEnvelopePre 原样字段,deadline 内回 ContextAckPre)。smoke-test-m70-pre.mjs G1-G9 共 90 断言 exit 0。
+- **M7-1 完成(tested)**:JS 授权分页 index_sync——lib/index-sync-pre.js(snapshot→scope 分组 begin/pages/commit,≤64 条·≤256KiB,page/final digest=canonical SHA-256);worker 原子切换 derived corpus 到 `<DSH_HOME>/memory/semantic-pre/`(可完全重建);缺页/重复/乱序/digest/版本不一致整次拒绝。smoke-test-m71-pre.mjs H1-H9 共 90 断言 exit 0。
+- **解锁面**:contextSinkMode='python' 与 activationSource='python' 仅在三重门(assoc∧对应开关∧pythonBackendEnabled)下生效;默认 false/null/fake 时零 Python process、零协议 IO、零 semantic-pre 目录。fake 激活逐字段过现有 validateActivationRequestPre;Python 不构建 ReferenceTailPacketPre。
+- **未做(明确)**:真实 embedding、向量检索、BM25/RRF、reranker、聚类、图算法;未标 live(无 3080 活体验证)。
+- **M7-2 完成(tested,2026-08-24)**:Embedding/Tokenizer/Chunking 双层 benchmark(合成 L1 152 记录/88 查询 + 真实 L2 251 episodes/40 查询)→ **冻结 BAAI/bge-m3(pinned revision,MIT)+ m7_chunk_pre_v1=para-512-noov + NumPy exact cosine**;qwen3-0.6B 条件备选,multilingual-e5-large 淘汰(zh→en 失败)。产物:docs/M7-EMBEDDING-BENCHMARK.md、docs/M7-ALGORITHM-DECISION.md、artifacts/m7-benchmark-pre/results.{json,csv}、CI fixture(42 docs×8 queries 真实向量,smoke-test-m72-pre.mjs 21 断言零联网)。外部真实语料只读脱敏入 artifacts/m7-corpus-pre/。未接生产 activation,未标 live。三处偏差与 m70 harness 顺手修复见 PYTHON-SIDECAR-CONTRACT §19.6。
+- **M7-3 完成(tested,2026-08-24)**:python/m7_embedding_pre_v1.py(冻结 policy 生产实现,可插拔 provider)+python/worker_semantic_pre_v1.py(继承 worker_pre_v1 零协议回退;commit 建向量+identity stale/重建;context_push 影子候选不发新帧)+smoke-test-m73-pre.mjs 55 断言+hybrid 对照(lexical 复刻/bm25s/dense/weighted/RRF 消融)→**冻结 hybrid_fusion_pre_v1=weighted dense0.7+lexical0.3**(L2 R@5 0.950>MRR 0.866 全面胜 dense-only;bm25s 交叉验证=自研复刻,生产零新依赖);全量回归 24 项全绿。未接生产 activation,未标 live。详见 PYTHON-SIDECAR-CONTRACT §19.7。
+- **M7-4..M7-7 完成(tested,2026-08-24,未 live)**:Clustering Shadow(agglomerative NMI 0.916/稳定性 0.995,HDBSCAN 不适用,零 M6 接线);M7-4 rerank(双 reranker 质量显著——L1 R@5→1.0——但 CPU p50 26-33s 超 500ms 预算 50-90 倍→D9 deferred-optional 不接生产);M7-5 graph 门(6/8 多跳双端点已覆盖→**skipped-by-benchmark**,任务集视为正确完成);M7-6 双阈值激活(worker_semantic:shadow 校准默认;active 帧**逐字段过 M6 validator**,m76 33 断言);M7-7 judgement shadow(m77 15 断言,零权威写入);model-sparse 补测(L2 单独胜 dense,dense+ms 融合 R@5=0.975 全研究最高→D6 修正案记录不改默认)。**全量回归 26 项全绿;M7-2..M7-7 全部默认关闭/shadow;已停在 M7-8 人工门,用户操作步骤见 PYTHON-SIDECAR-CONTRACT §19.8。****M7-7.5 Hardening 完成(审阅 P0/P1/P2 全部闭环:真 BGE 建库修复/D6 hybrid 进生产/三重过滤/correction 硬抑制/gitignore 隔离),回归 26/26 复跑全绿;二轮自查补 specials 预算与 chunkId 差异说明。详见 §19.9。**
+- 完整证据/偏差/进程生命周期/M7-2 输入:见 docs/PYTHON-SIDECAR-CONTRACT.md §19。