Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions docs/business_storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,106 @@ HY_MEMORY_TEST_POSTGRES_DSN='postgresql://localhost:5432/memory_test' \
```

测试创建随机前缀的 schema,并在结束时清理。应使用独立测试数据库;未提供测试 DSN 时只运行 SQLite 部分。


## 跨会话巩固发布与升级

SQLite / PostgreSQL 仓储显式声明 `supports_consolidation=True`,提供一致材料快照、
SQL-only 回执读取和单事务发布/重激活。旧自定义 `MemoryRepository` 不新增必需抽象方法,
普通读写契约保持兼容;默认不支持新能力,巩固在调用模型和写向量前抛 `NotImplementedError`,
不能降级为多个独立 upsert 的非事务发布。

`consolidation_receipt` 保存精确范围、稳定依据身份、原始决策、当前选择、依据有效性、
激活代次、权威产物清单及撤回 ID。`consolidation_read_set` 保存完整实际输入的类型、ID、
session、指纹和事件时间,不复制历史原文。`(group_key,basis_digest)` 唯一,部分唯一索引保证
每组最多一个当前回执,材料反向依赖索引用于事务内失效。经验表增加 `consolidation_id`
和 `evidence_refs`。这些 SQL 表和索引只管理业务状态,不生成语义、关键词、BM25、全文或
向量检索候选,检索仍由配置的 VDB 负责。

发布流程:短一致读事务冻结完整材料和 `(当前巩固 ID, activation_epoch)`;事务外模型归纳、
embedding、严格候选向量批写;短写事务锁源记录,重验冻结指纹,锁巩固组并检查激活代次,
一次性写回执、依赖和正文、切换当前决策。候选经验 ID 每次随机生成,未发布候选经业务库
可见性过滤。确认未提交的冲突或向量预写失败才清理本次独有节点;提交结果不确定时保留节点。
`no_result` 也参与换代。同依据并发仅有一个权威清单;A→B→A 旧请求不能绕过代次检查。

SQLite 使用 WAL;新列、新表和约束在 `BEGIN IMMEDIATE` 升级事务内完成,事务内不使用
隐式提交的 executescript。PostgreSQL 业务 schema 升至版本 2,显式从版本 1 增加两列与
回执/依赖表;升级沿用 namespace advisory lock。初始读取为 REPEATABLE READ 快照。
发布和来源编辑按源记录→巩固组→回执/产物顺序加锁,编辑取得源锁后才读取最新依赖,
因此等待发布结束的编辑也能使刚发布回执失效。PostgreSQL 按源 ID 使用事务级 advisory lock
覆盖删除/重插时缺失的源行,并对现有源行取 FOR UPDATE。直接撤回综合经验先锁组再删除正文,
提交后清向量;迟到向量和清理失败均不能恢复业务可见性。

正常经验读取、分页、计数和任务列表共用当前且依据有效的回执条件;普通经验保持可见。
依据语义投影统一定义于 `coding/evidence.py`,不把事实状态、演化摘要或互链计入指纹。
历史回执重激活仅保留未撤回的产物;依据失效后恢复原文仍需要重新归纳与发布。


### 2026-11-14 原 Qdrant 分支上的历史实施验收记录

以下是原实现提交携带的历史记录,对应 Qdrant 功能分支的依赖和基点,不是移植到上游
`7b85404be1b1` 后的验证结果。独立分支的实际版本与检查结果见
[经验巩固独立分支验证记录](plans/2026-11-14-cross-session-consolidation-validation.md)。

代码基点:`b591b4076c747f9b0310bce776251115e1ff4b8d` 加本地未提交改动。
Python 3.12.10(Windows),SQLite 3.49.1,PostgreSQL Server 17.7 / psycopg 3.3.6;
Chroma 1.5.9(嵌入式),Qdrant client 1.20.0(当时 Qdrant 分支的锁定版本)
/ Server 1.20.0(独立 Docker 实例),FAISS CPU 1.15.1(嵌入式)。
业务仓储与 VDB 分开配置,没有新增运行依赖或修改锁文件。模型和 embedding 合同测试使用
现有 MockLLMProvider / MockEmbedService;下面的模型质量抽样另行使用真实 provider。

依赖安装实际使用 `uv export --locked --extra dev --extra postgres --format requirements.txt
--no-hashes --no-emit-project` 导出锁定约束后,通过 PyPI 镜像安装;额外安装当前锁定的
`qdrant-client==1.20.0`、`faiss-cpu==1.15.1` 执行当时的可选后端合同。
原始 PyPI 文件下载在本机阻塞,未把中断的安装命令当作成功。

实际执行(`python` 指本仓库 `.venv/Scripts/python.exe`,外部服务均为本次独立测试实例):

```powershell
$env:HY_MEMORY_TEST_POSTGRES_DSN = 'postgresql://hy_memory:hy_memory_test@127.0.0.1:54541/hy_memory_test'
$env:HY_MEMORY_TEST_QDRANT_PORT = '53388'
python -m pytest tests/coding/test_consolidator.py tests/coding/test_consolidation_repository.py tests/coding/test_consolidation_client.py tests/test_prompt_registry.py -q -o log_cli=false --show-capture=no
# exit 0: 161 passed, 0 failed, 0 skipped
python -m pytest tests/coding/test_consolidation_repository.py -k postgres -q -rs -o log_cli=false --show-capture=no
# exit 0: 16 passed, 16 deselected, 0 skipped(全部为真实 PostgreSQL 参数)
```

原生向量合同为 SQLite/PostgreSQL × Chroma / Qdrant Local 经验集合 /
Qdrant Server / FAISS,共 8 个真实组合。Local 用例仅打开经验集合,验证已有通道的预写、
检索、完整 session 集合、复用和撤回;**不代表 Qdrant Local 完整双层 store 初始化已通过**。
当前基线的完整双层初始化会用两个独立 QdrantClient 打开同一目录,实测触发目录锁冲突;
本改动未修改 adapter 或该初始化行为。Qdrant Server 用例执行完整 store 初始化与两集合,
服务端版本通过真实实例查询确认。没有测试 Chroma HTTP、多 Python 版本或大数据量性能。
检索对隐藏历史向量按原生 ANN 自适应扩容,沿用每次最多 2,000 候选的安全上限。

真实模型抽样为当前配置网关的 `deepseek-flash`,五组输入均为固定人工材料:

| 材料组 | 人工检查结论 |
| --- | --- |
| 死锁三会话 | 保留 PostgreSQL/SQLite 的不同验证范围和源→组→产物顺序;默认 4,096 输出预算截断并被整批拒绝,8,192 重跑后结构及引用通过,验证标签偏保守 |
| 相反环境 | 按 Python 3.8 / 3.12 区分 executor 与 to_thread,不把新版本 API 推广到旧环境 |
| 未验证计划 | 明确 unverified,未把评审同意或计划写成已验证成功 |
| 相关与无关会话混合 | 只引用两条数据库材料;午餐会话仍在完整 read_set,未强行支撑结论 |
| 多个独立主题 | 分为 HTTP 429 重试和 SQLite 迁移两条经验,各自保留条件和引用 |

其余四组在 4,096 输出预算下通过;样例评审不等于对其他模型、提示注入或开放材料质量的普遍保证。
网关不支持默认 gpt-4.1-nano,最初调用收到 HTTP 400;质量评审临时选择网关声明支持的模型,
没有改动 SDK 默认模型配置。默认预算下的截断失败仍按真实结果记录,未计为有效产物。


全 SDK 回归实际命令 `python -m pytest tests/ -q -o log_cli=false --show-capture=no`
(不包含 integration 标记),最终 exit 1:2,048 passed / 72 failed / 33 skipped /
18 teardown errors,71 deselected。以 `git archive HEAD` 导出的完整、未修改基线在同一 Python、
依赖与 PostgreSQL 实例上运行同一命令,exit 1:1,965 passed / 73 failed / 33 skipped /
18 teardown errors,71 deselected。逐项比较 JUnit 失败用例集合,**没有仅出现在本改动的失败**;
基线另有一项 reembed 用例失败,本改动运行时该项通过,未将其视作修复成果。

方案指定的聚焦范围也执行过:`tests/coding tests/test_prompt_registry.py
tests/test_prompt_language_selection.py tests/test_client_loop_lifecycle.py`,该轮结果为
798 passed / 12 failed / 4 skipped / 15 teardown errors;其失败与错误集合与未修改基线一致。
此后补充的原子批回滚、第二产物向量失败及 Qdrant Server 用例已纳入最终 161 项和全 SDK 回归。
旧用例中的 Windows 文件占用、非 ASCII FAISS 持久化路径、SIGALRM 不可用、默认 GBK 读源码等
失败仍保留,未为了验收改动无关模块或隐藏错误。故本次没有宣称全量回归通过。

本次修改范围的 Ruff、Python 编译及 `git diff --check` 通过。双轴代码审查发现的提交取消、
隐藏产物公共撤回、历史向量遮蔽和无范围查询全量扫描问题均已修复,并补有回归用例。
11 changes: 11 additions & 0 deletions docs/env_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,3 +244,14 @@ client = HyMemoryClient.from_config({

历史配置不会生效;当前支持项以本页表格和 `.env.example` 为准。Cache backend 当前仅支持
`sqlite` 和 `mysql`。

### 跨会话经验巩固预算

| 环境变量 | 默认值 | 作用 |
| --- | --- | --- |
| `MEMORY_CODING_CONSOLIDATION_MAX_INPUT_TOKENS` | `16000` | 完整归纳 prompt 的输入 token 预算,超限整次拒绝,不裁材料 |
| `MEMORY_CODING_CONSOLIDATION_MAX_OUTPUT_TOKENS` | `4096` | 巩固模型输出 max_tokens;截断整批失败 |

对应 `CodingConfig.consolidation_max_input_tokens` / `consolidation_max_output_tokens`,必须为
正整数。Working / Coding 共用预算配置,各自在独立业务库 namespace 和原生经验向量集合中
发布。没有新增调度、任务队列、VDB adapter 或 HTTP/MemHub 入口。
120 changes: 120 additions & 0 deletions docs/plans/2026-11-14-cross-session-consolidation-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# 跨会话经验巩固独立分支验证记录

日期:2026-11-14(Asia/Shanghai)。专项测试通过,完整 SDK 在本分支和未修改的上游基线上
均未全绿;本贡献以 draft 提交,不声明已满足普通待审或合并条件。

## 提交与范围

- 上游基线:`7b85404be1b1fbe3c09a02a9409835128877a390`。
- 原实现提交:`00f6fca5a23ed1d4e66d18ae6cc9fd441884c0b3`,位于另一个 Qdrant 功能分支。
- 独立分支:`codex/cross-session-consolidation`;移植后的代码提交为
`ea99d854a3f5cd5edf82aab4fac728d5b17f706c`。
- 移植冲突仅涉及 `hy_memory/client.py` 和 `docs/env_reference.md`,保留经验巩固新增内容,
未带入 Qdrant native retrieval 的准备接口或文档段落。
- 新分支不依赖 PR #447,不修改 VDB adapter、依赖清单、锁文件、工作流或 MemHub。
后续提交仅补充本记录并区分历史验收材料,未再次改动被测代码。

原方案在实现前已有验收条目;未提供可独立核对的“新增测试首次失败早于实现”的执行记录,
因此不补写或倒填 test-first 历史。原实现附带的模型质量评审和回归结果保留在
[业务存储文档的历史记录](../business_storage.md#2026-11-14-原-qdrant-分支上的历史实施验收记录),
不作为本分支的当前检查结果。

## 本轮环境与隔离

| 项目 | 实际版本或运行模式 |
| --- | --- |
| 系统 / Python | Windows / CPython 3.12.10 |
| SQLite | 3.49.1,测试临时目录 |
| PostgreSQL | 17.7,`postgres:17` 一次性 Docker 容器;psycopg 3.3.6 |
| Chroma | 1.5.9,嵌入式 |
| Qdrant | client 1.19.1;Local 模式及 Server 1.20.0 一次性 Docker 容器 |
| FAISS | faiss-cpu 1.15.1 |
| pytest / pytest-asyncio / Ruff | 9.1.1 / 1.4.0 / 0.17.1 |
| 模型 / embedding | 现有 MockLLMProvider / MockEmbedService,无真实模型质量重测 |

数据库与 Qdrant 均使用本轮新建容器和随机映射到 loopback 的端口;PostgreSQL 用例使用随机
namespace,向量合同使用独立随机集合。未使用日常、共享或生产实例。镜像 ID:

- PostgreSQL:`sha256:f337b026cb1fb954a93f2e33a62bf9ea7fffc1dafc1586c53b93922a8d6ee018`。
- Qdrant:`sha256:9bfc89f9914fc14876a88c05270685921a55b8877b254a98bcc1cc2f0a424cd2`。

本轮复用现有虚拟环境,以 `uv pip install --python .venv/Scripts/python.exe --no-deps
qdrant-client==1.19.1` 将客户端恢复到上游锁文件对应版本;没有声称重新同步了整套锁定环境。
FastEmbed 未安装,本轮仅验证已有稠密经验向量通道,不验证稀疏/BM25 能力。

## 原生检索依赖声明

综合经验复用现有 Working/Coding 经验向量集合及 `upsert_batch()` / `search()` / `delete()`
接口;新增 SQL 表、约束和反向依赖索引仅管理发布、依据有效性、撤回、幂等及业务可见性,
不生成语义或词项检索候选,不新增 VDB 外检索索引、关键词、BM25、全文或混合检索通道。

| 后端 | 本轮使用的原生能力 | 固定版本官方接口依据 |
| --- | --- | --- |
| Chroma 1.5.9 | `Collection.upsert()`、`query(query_embeddings=...)` | [upsert](https://github.com/chroma-core/chroma/blob/1.5.9/chromadb/api/models/Collection.py#L497)、[query](https://github.com/chroma-core/chroma/blob/1.5.9/chromadb/api/models/Collection.py#L194) |
| Qdrant client 1.19.1 / Server 1.20.0 | `QdrantClient.upsert()`、`query_points(query=dense_vector)` | [upsert](https://github.com/qdrant/qdrant-client/blob/v1.19.1/qdrant_client/qdrant_client.py#L867)、[query_points](https://github.com/qdrant/qdrant-client/blob/v1.19.1/qdrant_client/qdrant_client.py#L269);本轮真实 Server 组合合同通过 |
| FAISS 1.15.1 | `IndexFlatIP`、`add()`、`search()` 及既有 selector | [IndexFlatIP](https://github.com/facebookresearch/faiss/blob/v1.15.1/faiss/IndexFlat.h#L76)、[add](https://github.com/facebookresearch/faiss/blob/v1.15.1/faiss/python/class_wrappers.py#L289)、[search](https://github.com/facebookresearch/faiss/blob/v1.15.1/faiss/python/class_wrappers.py#L421) |

这些材料说明依赖、声明边界和本次执行结果,不替代实现正确性、隔离效果或质量的代码审查。

## 实际执行结果

下列 `python` 指现有 `.venv/Scripts/python.exe`,工作目录为仓库根目录。
`HY_MEMORY_TEST_POSTGRES_DSN` 和 `HY_MEMORY_TEST_QDRANT_PORT` 仅指向上面的一次性实例。

| 检查 | 退出码 | 结果 |
| --- | --- | --- |
| 新增三个巩固测试文件 + prompt registry | 0 | 161 passed,0 failed,0 skipped |
| 方案指定聚焦回归 | 1 | 803 passed / 12 failed / 4 skipped / 15 teardown errors |
| 本分支完整 SDK | 1 | 2002 passed / 72 failed / 33 skipped / 18 errors;45 deselected |
| 未修改上游基线完整 SDK | 1 | 1919 passed / 73 failed / 33 skipped / 18 errors;45 deselected |
| 跨会话来源数量校验变异 | 1,预期红灯 | 1 failed / 15 passed / 18 deselected |
| 正常代码下的相同变异目标测试 | 0 | 16 passed / 18 deselected |
| 全部改动 Python 文件的 Ruff / compileall | 0 | 通过 |
| `git diff --check origin/main...HEAD` | 0 | 通过 |

主要命令:

```powershell
python -m pytest tests/coding/test_consolidator.py tests/coding/test_consolidation_repository.py tests/coding/test_consolidation_client.py tests/test_prompt_registry.py -q -o log_cli=false --show-capture=no
python -m pytest tests/coding tests/test_prompt_registry.py tests/test_prompt_language_selection.py tests/test_client_loop_lifecycle.py -q -o log_cli=false
python -m pytest tests/ -q -o log_cli=false --show-capture=no
python -m pytest tests/coding/test_consolidator.py -k bad_output -q -o log_cli=false --show-capture=no
```

161 项专项结果包含 34 项协调器测试、32 项仓储测试、16 项客户端/向量合同及 79 项 prompt
registry 测试。仓储测试中 16 项为真实 PostgreSQL 参数,全部通过,没有缺连接/驱动跳过。
向量合同包括 SQLite/PostgreSQL × Chroma / Qdrant Local / Qdrant Server / FAISS,共 8 个
真实组合。模型与 embedding 仍为替身;这不是对模型归纳语义质量的验证。

Qdrant Local 合同仅打开经验集合,不代表完整事实+经验双层 store 初始化已通过;
Qdrant Server 合同执行完整 store 初始化。没有测试 Chroma HTTP、多 Python 版本或规模性能。
客户端合同覆盖公共同步/异步入口及诊断;其他 VDB 的存储合同不等同于所有客户端组合 E2E。

## 基线对照与未解决项

以 `git archive origin/main` 导出完整未修改基线,在同一 Python、依赖和测试服务上执行相同
SDK 命令。已核对 import 路径来自导出目录,而不是当前分支。两次完整运行的 JUnit 按完整
用例 ID 比较,本分支没有独有的失败或错误 ID;双方共有 90 个失败/错误用例 ID。基线另有
`test_reembed_copies_everything_and_never_touches_source[1024-512-old-new]` 失败,本分支该项
通过;未把这一单轮差异宣称为修复成果或稳定性保证。

共有失败涉及 Windows 文件占用、FAISS 持久化相关用例、信号与编码相关测试等;本轮没有逐项
裁定全部根因,也没有修改无关测试或弱化断言。完整 SDK 仍未通过;同名失败对照不能证明
这些用例中绝无新问题。33 个 skip、45 个 deselect 均未计为通过,默认命令不执行 integration。

原始日志与 JUnit 保留在本地 `.git/codex-validation/consolidation-20261114/`,不将含本机路径的
原始日志直接提交。本记录仅发布结果摘要;CI 尚须在 draft 的实际 head 上运行并核对。

## 变异验证

在独立 Python 进程中读取 `_validate_output()`,仅在内存里将 `len(sessions) < 2` 改为
`len(sessions) < 1`,放宽单会话结论限制。现有 `test_bad_output_fails_the_entire_batch` 的
空 `conditions`、仅一个支持会话参数按预期报 `DID NOT RAISE CodingWriteError`。
正常代码在新进程中运行同组 16 项全部通过。没有修改工作树源文件,变异进程退出即消失。

## Draft 后续

保持 draft,等待当前 head 的 CI 结果及代码审查;失败、跳过和未执行项均保持如实记录。
本轮不重跑历史真实模型抽样,不声称完成所有后端/运行模式的全链路验收。
回滚时先停用新巩固调用;升级后的业务库不能假定可直接交给旧版本打开,需先备份并按经过
验证的迁移或恢复流程处理。本轮未演练数据库降级/恢复。
Loading
Loading