本地证据记忆库 tianhao8687/MemoryOS

MemoryOS

开发问题总复盘：开发中遇到的问题、失败实验、修复证据与遗留风险

V2.3 最小充分上下文：瘦响应、Token 分账、Context Atom、Delta、证据门禁与当前限制

V2.2 Hardening Report：H-001～H-008 修复、迁移、测试、基准与限制

DeepSeek Harness 实测总览：测试矩阵、失败根因、修复与证据边界

独立 DSH 插件：tianhao8687/dsh-memoryos

AI 校准就绪状态（自动生成）

单一事实源: benchmarks/ai_calibration_v1/readiness.json。请运行 python scripts/sync_project_status.py --write 更新本段; 不要手工修改。

- 状态: protocol_ready_evidence_pending
- 生产 profile: inactive; 生产权重冻结: yes
- 有效 real-agent 配对: 9
- AI Jury 有效覆盖: 1 个模型家族 / 1 个 provider
- Sealed promotion: 0 tasks / 0 repositories / 0 sequences; 批准: no

当前阻塞:

1. Need order-swapped pairwise votes from at least three genuinely distinct model families and providers.
2. Need usable train labels across at least three training repositories plus repository-held-out development observations; both the cross-repository and adaptive label-seeking pairs had unchanged outcomes and create no new labels.
3. Need a repository-held-out candidate profile trained without safety-gate leakage.
4. Need paired real-agent frozen-baseline/candidate shadow runs bound to that profile.
5. Need at least 50 sealed tasks across three repositories, ten sequences, and two unseen agent models with complete paired cost data.
6. Need a passing explicit promotion decision before any atomic activation can be considered.

MemoryOS V2.3 是面向编码 Agent 的本地优先 Reality Intelligence 层。它在 V2.2 的不可变证据、双时态 Current Truth、Git-aware freshness、检索硬化和真实工作负载协议之上，新增可回退的 Minimum Sufficient Context 编译层。MCP、HTTP、CLI 和 React Workbench 继续共享同一 SQLite 事实源。

DeepSeek Harness 实测快照

当前 dsh-memoryos 0.2.0 已拆分为独立的 DeepSeek Harness（DSH）Bundle。它不是“零成本提示词”：启用后会增加工具 Schema 和取回内容，价值必须由与 no_memory 同题、同模型、同预算的对照来判断。用户现在可以直接对 Agent 说“关闭 OS”“开启 OS”或询问状态；开关会真实装卸记忆工具并跨重启保存。

| 验证面 | 冻结结果 | 可以得出的结论 |
| 插件全功能验收 | 14/14 隐藏验收通过；13/14 严格协议通过 | 安装、开关、Full、Progressive、Explain、Delta、计量、缓存与隔离链路可用 |
| 自然语言持久开关 | 0.2.0 tarball 断网安装后契约与真实 Loader/HMR 27/27 通过 | 普通关闭只留控制工具；健康检查成功后恢复；严格 no_memory 保持零 Schema |
| 中等编程任务 | 单题中 A/C 均通过且 C 少 16.20% 输入；另有 held-out 任务 A/B/C 均失败 | 有效率与定向信号，但尚无跨题成功率提升证据 |
| 跨 Session 记忆 | 三案例严格门 2/3；12 个新会话的回忆/基线/错 scope 隔离均符合预期 | 写入、硬重启回忆和 scope 隔离成立；一个源写入门仍受跨语言词法评分影响 |
| 记忆更新 | PASS：PostgreSQL 17 被 18 正确 supersede | 新 Current Truth 不会与旧版本同时作为当前事实返回 |
| 上下文淘汰 A/B | PASS：无记忆回答“不知道”，MemoryOS 恢复 Glacier-47 | 原始对话确已被挤出活动上下文后，长期记忆仍可恢复 |

最后两项 live-r4 共 24 次 Provider 尝试、0 重试；输入 214,165、输出 3,743、推理 2,206 Token。三个写入会话分别记录 write_tool_schema_tokens / memory_write_visible_tokens / provider_input_tokens，总计 1,794 / 7,779 / 103,687。MemoryOS 两项是 unicode-heuristic-v1 组件估算，Provider 输入是供应商精确值。完整口径、事故记录和不可外推范围见实测总览。
当前源码版本：2.3.0。MSC 的语义、配置、证据和限制见 V2.3 最小充分上下文。当前 confirmatory real-agent 证据不足，所以默认 compiler 仍是 legacy、effect_claim=none；没有自动激活 MSC 或 learned retrieval profile 的路径。合并后应在干净 main 上重建发行包并运行：

.\.venv\Scripts\python.exe scripts\main_release_smoke.py --distribution .\release\MemoryOS

V2.1 的历史验收映射和不可变机器报告继续保留在 docs/ACCEPTANCE.md 与 docs/verification/v2.1/；V2.2 历史证据位于 docs/verification/v2.2/；V2.3 Golden 和 dry-run 工件位于 docs/verification/v2.3/。

V2.3 能力

- 三档 Context Compiler 模式：字节兼容 legacy、只存诊断的 msc_shadow 和瘦生产响应 msc；证据门禁通过前默认保持 legacy。
- budget 仍是旧字符预算；新增带 exact/estimated 来源的 Token Counter、384/768/1536/3072 Profile、AUTO 策略和完整 payload 预算。
- 确定性 INDEX/FACT Atom、按需 EVIDENCE/HISTORY，以及覆盖极性、限定词、Truth/Freshness、有效时间和证据指针的 Atom hash。
- Pinned Constraint 和 Contested Bundle 原子安全下限；精确去重只合并完全等价事实并保留所有证据，语义去重仍是 Shadow-only。
- 兼容扩展 memory_explain 的 expected hash/sections/Token 预算，以及会在变更时失效的一次证据展开。
- 显式 previous_context_id Delta、Scope/Policy/Tokenizer/TTL/完整性校验、低效 Delta 的 Full Rebase 和不进长期备份的可丢弃 Snapshot 缓存。
- 启动时固定的 all/core/context/governance/debug MCP Profile，工具顺序与 Schema hash 确定；context 仅暴露 memory_context，用于降低只读 Agent 每轮重复发送的工具 Schema；服务端 Schema 减少不被冒充为 Provider Token 节省。
- 独立 Context Efficiency Study 分开 Provider input/output、缓存、成本、延迟、记忆交付/证据/历史/Delta、Schema、安全和最差组，并固定 0.5/0.65/0.8/0.9 Delta 阈值敏感性；dry run 可复现但不授权默认激活。
- Context Efficiency 实执行器 可用同一入口运行五个冻结条件、本地 Qwen OpenAI-compatible Agent 或 DeepSeek Harness、cold/warm 配对、真实代码修改/测试与逐请求 usage；fixture 只验证执行契约，不作为模型收益证据。

- 保留 V1 的五级 scope、六类 memory、candidate-first 生命周期、来源、审计、TTL、逻辑忘却、备份和 7 个 MCP 工具。
- 从 evidence span 生成标准化 Claim；实体别名只在同 scope/type 内解析，可审计合并与 redirect。
- Claim 关系支持 equivalent/supports/contradicts/supersedes 等；Current Truth 返回 resolved | contested | stale | unknown。
- ClaimIdentity 与只追加 ClaimVersion 分离；transaction_from/to 和 valid_from/to 支持按“当时已知”重建历史，不用当前行猜测过去。
- 明确冲突由规则处理；只有不确定 claim pair 可进入 bounded model judge。判断、弃权、失败、provider fingerprint、prompt version 与 evidence hash 都进入 Possible Conflict 审计队列。
- Source Anchor 使用 Tree-sitter 解析 Python、TypeScript、JavaScript、Rust 的相关 symbol；其他语言使用 bounded snippet/context hash。
- Git freshness 状态机识别 fresh / moved / suspect / stale / unknown，lazy + HEAD cache；refresh 只产生 replacement candidate，不改写原记忆。
- Retrieval 2.0 将 candidate retrieval、fusion、governance scoring、rerank 与 diversity 拆成显式阶段。生产继续使用冻结的 FTS/vector/graph/temporal 基线；显式 Shadow 可从 allowlist 选择查询配方，并为精确代码查询增加结构化 Source Anchor 通道。请求、实际执行、降级通道、阶段耗时及分数契约全部持久化。
- sqlite-vec 按 provider/model/dimension 建立持久化实时 namespace，支持 doctor、状态和重建；Exact NumPy 是明确降级路径，扩展缺失不会阻止启动。
- Context Compiler 按 task intent、coverage、truth/freshness、utility/cost 和预算选择最小证据集；未决冲突强制呈现双方。
- Grounded consolidation 校验 supporting/counter memory IDs 与独立来源；离线 extractive fallback 明确标注。所有抽象与 distillation 只生成 candidate，永不自动激活。
- Memory Health 用可解释分数管理 Hot/Warm/Cold/Archived；归档可逆，唯一 accepted current truth 不可归档，Cold/Archived 才能参与 distillation。
- helpful/unhelpful feedback 可审计，只影响 retrieval utility，不修改事实状态。
- 12 个 stdio MCP 工具的兼容 all Profile、V2.3 HTTP API/CLI，以及包含 Current Truth 版本、Possible Conflicts、Memory Health 与向量诊断的 Workbench。
- CodingMemoryBench Fixture Regression 分离 runtime input 与 gold scorer，包含 hard negatives、时间和冲突三模式对照，并对满分给出过拟合警告；另有独立 production-path integration suite，二者均不声明真实 Agent 效果。
- 实测 100,000 记录 FTS-first RetrievalPipeline + ContextCompiler P95；该 Tier 1 fixture 未执行 embedding、Claim/Relation 或模型通道，也不声明模型收益。

从源码运行（Windows PowerShell）

需要 Python 3.12、Node.js 20.19+ 和 pnpm 11。

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Set-Location web
pnpm install --frozen-lockfile
pnpm build
Set-Location ..

.\.venv\Scripts\python.exe -m memoryos --data-dir .\data serve --no-open

Tree-sitter language pack 是 V2 core dependency。若要启用可选 SQLite ANN：

.\.venv\Scripts\python.exe -m pip install -e ".[ann]"

未传 --data-dir 时，Windows 默认数据目录为 %LOCALAPPDATA%\MemoryOS，也可用 MEMORYOS_HOME 覆盖。HTTP 仅绑定 loopback；浏览器获得 HttpOnly 同源写 cookie，外部写客户端使用 \auth.token。

Windows 发行包

.\release\MemoryOS\MemoryOS.exe --data-dir .\memoryos-data serve

发行形式为 PyInstaller onedir，必须保留整个 release\MemoryOS 目录。V2.3 生产 smoke 会从真实 0001_initial 数据库启动，验证自动迁移到 0005_context_efficiency、旧数据与不可变 anchor 基线保留、all/core/context/governance/debug 五个确定性 MCP Profile、HTTP/UI/CLI、fixture benchmark 资源、sqlite-vec runtime 和重启持久化。当前已有的 V2.2 包是历史证据；合并后的 clean-main V2.3 包复验完成前不声称新二进制已发布。

CLI 示例

.\.venv\Scripts\python.exe -m memoryos --data-dir .\data status --json
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data propose --repo my-repo --title "Use FastAPI" --content "Use FastAPI for the local API."
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data current-truth --query "backend framework"
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data debug-context "current backend constraints" --repo my-repo
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data consolidate --scope-key my-repo
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data vector-rebuild
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data refresh --repository-path C:\path\to\repo
.\.venv\Scripts\python.exe -m memoryos --data-dir .\data backup --output .\backup.zip

运行 python -m memoryos --help 查看完整命令。

MemoryBench 与验收

Retrieval calibration dataset

benchmarks/calibration_v1 contains the first versioned, data-backed retrieval calibration input:
300 Git-derived silver queries across six query repositories and five languages, plus a dedicated
seventh repository for cross-scope guards. Train/dev/test are held out by query repository. Runtime
queries and scorer-only qrels are separate, every artifact is SHA-256 pinned, and every query has an
精确路径正向、未来历史防护和跨作用域防护。

.\.venv\Scripts\python.exe scripts\build_calibration_dataset.py
.\.venv\Scripts\python.exe scripts\validate_calibration_dataset.py

该数据集仅用于校准检索。其 Git 路径重叠标签明确为 silver，而非人工金标准，并且不能用于证明真值冲突置信度或记忆健康阈值的合理性。协议、来源、限制和离线重建说明见 benchmarks/calibration_v1/README.md。

盲审人工评审试点（可选诊断）

benchmarks/human_review_v1 在不制造标签的情况下增加了下一层防过拟合机制。它包含 61 个盲审案例，每位评审者有 1,922 个候选决策：60 个按时间分层的训练/开发查询，覆盖五个非测试仓库，外加一个公共真实工作负载诊断。现有测试仓库保持封存。两个任务分配包含相同案例，但候选顺序不同，并省略了 silver qrels、目标提交、工作负载预期、置信度和重要性。

.\.venv\Scripts\python.exe scripts\build_human_review_pack.py
.\.venv\Scripts\python.exe scripts\validate_human_review_pack.py

该包被有意设为 pending_human_adjudication，而非金标准。将这个特定包转为人工金标准仍需要两份已完成的人工评审和一名单独的人工裁决者，但人工标注不再是生产校准的前置条件。其机器可读耦合审计还报告称，初始真实任务与 Git 来源集共享 MarkupSafe 仓库。见 benchmarks/human_review_v1/README.md。

一项单独的、已检入的纯模型演练现在覆盖两个盲审任务分配以及全部 1,922 对。
第三个模型角色裁决了 527 个核心分歧；相关性一致率为 75.70%，但 Cohen's kappa 仅为 0.203，而安全性一致率为 97.66%（kappa 0.834）。这些是临时性的评分标准诊断，不是人工标签，也不是生产权重批准。完整的事件日志、哈希、决策、事后 silver 比较和验证命令见 benchmarks/human_review_v1/model_review/README.md。

仅 AI 的可执行校准

benchmarks/ai_calibration_v1 定义了用于替换启发式检索权重的当前无人工路线。来自三个提供方的至少三个不同模型家族进行顺序交换的成对判断；运行时/模型/提示/响应身份均以哈希绑定，并且这些投票是不确定性加权的弱监督，绝非真值。随后，选中的记忆会接受真实编码代理的完整/减去消融。一个受约束的成对学习器只能创建候选画像，而一个单独的封存门控要求至少 50 个任务、三个仓库、十个序列、两个未见 agent 模型、正向成功下置信界、无安全性或最差仓库回退、有界延迟/成本，以及完整的配对成本核算。任何阶段都不会自动激活 profile。候选 profile 仅通过显式的配对影子运行器运行；正常服务保持冻结的生产评分器。训练会拒绝封存的测试/晋升观测，而不是在模型选择期间打印其指标。它还会拒绝重复的观测 ID，要求训练分区内同时具备 AI 评审团和真实可执行证据，并将精确的规范训练/开发输入 SHA-256 绑定到候选 profile 中。

.\.venv\Scripts\python.exe scripts\validate_ai_calibration.py
.\.venv\Scripts\python.exe scripts\run_executable_ablation.py --help
.\.venv\Scripts\python.exe scripts\run_weight_shadow.py --help
.\.venv\Scripts\python.exe scripts\build_retrieval_routing_shadow.py --help
.\.venv\Scripts\python.exe scripts\run_routing_shadow.py --help
.\.venv\Scripts\python.exe scripts\analyze_routing_shadow.py --help
.\.venv\Scripts\python.exe scripts\ai_calibration.py --help

已检入的就绪注册表当前显示 protocol_ready_evidence_pending：九个有效的真实 agent 完整/减去配对现在覆盖六个 SWE-bench Verified 任务，涉及 Requests、Pylint、pytest 和 Seaborn。只有一个 Requests 配对不一致，并产生一个真实的 TRAIN 标签；其他 Requests 重复、三个跨仓库配对，以及四个后续寻找标签的配对都保持结果不变，而不是只选择有利的示例。模型审查仍然只代表一个有效的模型家族/提供商，训练仍然缺乏跨三个训练仓库的可用标签以及所需的仓库留出开发观测，并且没有封存的晋升任务。
因此生产权重保持冻结。协议、证据哈希、命令和阻塞项见 benchmarks/ai_calibration_v1/README.md。

单独运行 V2 回归与 V2.1 盲测：

.\.venv\Scripts\python.exe scripts\memorybench_v2.py
.\.venv\Scripts\python.exe scripts\coding_memory_bench.py
.\.venv\Scripts\python.exe scripts\benchmark_v21_pipeline.py
.\.venv\Scripts\python.exe scripts\agent_ab_v21.py --tasks 50

输出：

- docs/verification/v2/memorybench-report.json
- docs/verification/v2/memorybench-report.html
- docs/verification/v2/acceptance-summary.json
- docs/verification/v2/verify-summary.json
- docs/verification/v2.1/coding-memory-bench.{json,html}
- docs/verification/v2.1/full-pipeline-performance.json
- docs/verification/v2.1/agent-ab.json
- docs/verification/v2.1/acceptance-summary.json
- docs/verification/v2.1/main-release-smoke.json

真实模型与 fixture 严格分开：50-task fixture 只验证 paired harness、指标和 bootstrap 95% CI。由于当前环境未配置真实 coding-agent endpoint，real-model Agent A/B 被如实记录为 external_blocker、effect_claim=none；项目不声称真实模型准确率或效果提升。

V2.2 真实仓库回放框架开发分支新增仓库级三组回放：no_memory / flat_memory / memoryos 使用相同历史提交、相同提示和相同代理镜像；MemoryOS 组必须产生真实 MCP 审计与 RetrievalRunRow。代理只看到 base 及祖先，记忆数据库位于独立 sidecar，隐藏测试在 --network none 的固定镜像中运行。公开 smoke 使用 MarkupSafe 的固定历史提交、任务发布时间和许可证来源，但内置代理明确标为 deterministic_fixture；只有 real_coding_agent 才可能通过确认性门禁，因此该报告始终 effect_claim=none。

协议、威胁模型、确认性门槛和运行命令见 V2.2 real-workload evaluation。

首次运行浏览器测试前安装 Chromium：

Set-Location web
pnpm exec playwright install chromium
Set-Location ..

scripts/verify_v21.py 依次执行 19 个 fail-fast 门禁：后端质量/测试、V2 回归、V2.1 盲测、50 对 agent 协议或 blocker、100K FTS-first Core Pipeline 性能、前端质量/E2E、wheel、Windows package、V1→V2.1 production smoke、干净 main release smoke 和 A33–A52 manifest。任何一步失败即非零退出。

数据和隐私边界

- memoryos.db：SQLite WAL/FTS5 主事实库。
- auth.token：本地写操作及会记录检索/到期状态的 API token。
- runtime.json：最近一次服务地址。
- logs/memoryos.log：脱敏轮转日志。
- backups/：格式 3 版本化备份，包含 claim versions、possible conflicts 与 health；V2.1 可导入旧格式，导入前校验 entry/哈希/大小/记录数/完整 schema，隔离迁移通过后才原子替换；恢复与导入后 ANN 缓存会安全重建。

MemoryOS 不做全仓源码收藏或云同步。Source Anchor 只读取被明确引用的相关文件，保存 bounded excerpt/hash/symbol metadata；Git compare 只检查 anchor commit 到 HEAD 的相关路径。默认 provider 关闭，不记录完整 prompt。

文档

- 架构
- V2.3 最小充分上下文
- 安全模型
- MCP 接入
- 验收证据
- 项目状态
- 开发问题总复盘
- 实施决策
- 变更日志
- MemoryBench
- V2.1 Reality Intelligence
- V2.2 real-workload evaluation
- V2.2 performance tiers