MemRelay/docs/implementation-plan.md

MemRelay 完整实施计划

2026-08-19 Git 来源增量收集与无变化任务短路（已实施）

背景：_collect_git 每次对仓库 HEAD 全量 ls-tree 提取全部文件，与游标增量（memory/file）不对称；Git-only 项目（无 agent 活动，auto 策略每次兜底收集 git）即使一个字未改，每次任务也全仓重提取、重压缩、重写全部文档（实测 274 文件 → 40 次调用、约 115 万 Token）。定时任务每日空转消耗。

契约：

1. _collect_git 接受 base_commit（上次成功整理写入 CurationSource 的 git 来源 revision）：与当前 HEAD 相同 → 零收集（git_coverage.mode=unchanged）；不同 → git diff --name-status 只提取变更文件并为删除文件生成 SOURCE_REMOVED 声明（mode=diff）；基线不可用（首次、浅克隆丢失）→ 回退全量（mode=full）。full 模式任务不传基线，始终全量。
2. 任务级短路：可用来源只剩 curated_baseline/全局指导（无任何主来源）且现有文档的 prompt_version 均为当前版本时，任务记录 no_primary_changes 事件并零调用完成（stats 带 skip_reason）；提示词版本升级时放行重建。
3. 未变文件的信息由 curated_baseline 文档承载，与既有"基线 + 新证据重写"语义一致；diff 空集不再误标 GIT_SOURCE_EMPTY。
4. 验收：_collect_git 全量/unchanged/diff（含删除声明）/无效基线回退四态回归；端到端"第二次无变化任务零调用短路"回归；完整后端套件 + 前端门禁通过后发布 ARM，生产实测同一项目从"40 次调用/115 万 Token"降为"零调用完成"。

2026-08-19 调用预算自适应工作量（已实施）

背景：BDYG18Pro 积压 293 个来源产生 27 个证据批次，任务约需 43 次模型调用，配置上限 task_max_calls=30 使每天 18:30 定时任务连续 7 天在第 31 次调用（合并 4/7）处失败，每次白烧 31 次调用；失败导致增量游标不推进、积压继续膨胀，形成每日必败循环。

契约：

1. 批次准备完成后按工作量估算所需调用上界：证据每批 1 次（单批不计）+ 合并树每层 ceil(n/4) 收敛至单份 + 文档每 4 份 1 批 × 2（含 repair 预留）。
2. 估算超过配置上限时，本任务内自动放宽调用上限至估算值，并记录 budget_calls_auto_raised 事件（configured/required）供审计；Token 预算保持硬顶不放宽，真实成本仍受控。
3. CURATION_BUDGET_EXCEEDED 错误信息附带用量与上限明细（调用 X/Y，Token A/B）。
4. 验收：估算函数数学回归（27 批 10 文档=43）、调用上限 1 + 五文档两批的端到端放宽回归（事件唯一、任务完成）、Token 硬顶既有回归不变；完整后端套件 + 前端门禁通过后发布 ARM，生产实测放宽事件触发且任务越过 30 次调用关口。

2026-08-13 时间字段统一 UTC-aware 序列化（已实施）

背景：SQLite 存储 datetime 丢弃时区，ORM 读回 naive UTC，isoformat 序列化不带偏移，Web 前端与 MCP 客户端把它误当本地时间，全站时间显示偏差 8 小时；散落各服务的 _ensure_utc 补丁未覆盖序列化路径。该偏差还让静默期去抖中的整理任务（next_retry_at 为未来时刻）看起来像"卡死数小时不执行"。

契约：

1. models.UTCDateTime（TypeDecorator）在读取时为 naive 值补回 UTC tzinfo；全部模型时间列使用该类型，存储格式不变、无需迁移。
2. REST（FastAPI）输出 +00:00 偏移、MCP（pydantic）输出 Z 后缀；前端 new Date().toLocaleString() 自动转本地时区，前端零改动。
3. 任务调度语义不变：source_change 任务的 next_retry_at 仍是静默期去抖到期时刻，"计划执行"列语义正确。
4. 验收：REST 往返断言时间带 UTC 偏移；修正依赖"读回 naive"旧行为的存量断言；完整后端套件通过后发布 ARM，容器内 ORM 读回 aware、公网 MCP 时间带 Z 实测确认。

2026-08-13 MCP GET /mcp 返回 405 兼容新版客户端（已实施）

背景：无状态 Streamable HTTP 下 fastmcp 只注册 POST/DELETE，GET /mcp 落入 SPA 兜底返回 404；新版 Cursor 在 initialize 后主动 GET 打开服务端通知 SSE 流，把 404 视为会话失效，连续重试后墓碑化整个连接导致 MCP 不可用。

契约：

1. /mcp 显式注册 GET（含自动 HEAD）返回 405 + Allow: POST, DELETE，符合 MCP Streamable HTTP 规范"不支持服务端主动 SSE 流必须回 405"；客户端（官方 TS SDK 及 Cursor）对 405 静默容忍。
2. 该处理不做鉴权（405 优先于 401，无信息泄露）；POST/DELETE 行为不变。
3. 验收：回归覆盖 GET /mcp 为 405 且带 Allow 头；完整后端套件通过后发布 ARM，内外网实测 405/200。

2026-08-12 操作列收纳与生命周期筛选默认全部（已实施）

背景：全局记忆操作列在 132px 内排 3 个图标按钮导致换行错乱；用户希望各生命周期筛选组默认即显示"全部"。

契约：

1. 全局记忆操作列改为"编辑直达 + 更多下拉"：标记待整理/移入回收站/永久删除收入 el-dropdown，永久删除以危险色标识（下拉挂载于 body，样式入全局 styles.css），列宽收窄为 104px 单行。新增 common.moreActions 文案。
2. 生命周期筛选默认值统一为 all：全局记忆、项目记忆（原 pending）、搜索页（原 current）；项目记忆"全部"视图混入检查点与回收站记录，与手动选择"全部"语义一致。历史契约中"默认显示待整理内容"自本节起由本契约取代。
3. 验收：Vitest 覆盖搜索默认 lifecycle=all 请求；ESLint、Prettier、vue-tsc 构建通过；发布 ARM 后确认站点提供新构建资源。

2026-08-12 整理输出语言设置（已实施）

背景：文档生成提示词未指定输出语言，整理文档语言隐式跟随来源主导语言，混合语言来源下可能漂移甚至 revision 间不一致；英文习惯的使用者需要确定性保证。

契约：

1. CurationSettings 新增实例级 output_language：auto（默认，跟随来源主导语言且单份文档内保持一致）、zh-CN、en-US；迁移 20260812_0015 为存量行回填 auto。不做工作区级覆盖（auto 已天然按项目来源自适应）。
2. 文档生成提示词按设置注入确定性语言指令；显式语言时无论来源语言一律按目标语言书写标题与正文。PROMPT_VERSION 升级触发下轮全量重生成。
3. REST/MCP 设置读写自动携带该字段；Web 整理设置页新增下拉（自动/中文/English）。
4. 验收：提示词三种模式的指令注入回归、设置读写回归；完整门禁后发布 ARM。

2026-08-12 提示词页多场景形态（已实施）

背景：提示词页目前只展示一段通用工作流，用户需要自行摸索"规则文件放哪、如何让 AI 遵守、已有项目如何迁移到 MemRelay 记忆"。

契约：

1. 提示词页改为三个场景：通用工作流（现状保留）、新项目接入、已有项目迁移；语言切换对全部场景生效。
2. 新项目接入：提供各客户端规则文件位置表（Cursor：项目根 AGENTS.md 或 .cursor/rules/*.mdc；Codex CLI：项目根 AGENTS.md，全局 ~/.codex/AGENTS.md；Claude Code：项目根 CLAUDE.md，全局 ~/.claude/CLAUDE.md；VS Code Copilot：.github/copilot-instructions.md；其他客户端：项目根 AGENTS.md 事实标准），每行附路径复制按钮；三步流程文案——创建规则文件并粘贴工作流提示词（复制按钮）、说明客户端会自动注入每次会话、新会话验证 AI 已解析 MemRelay 项目。
3. 已有项目迁移：后端新增 build_migration_prompt（中英文，随密码库/AI 整理启用状态裁剪），指导 AI 完成——解析或创建项目 → 通读 README/docs/脚本/既有 AI 规则文件 → 按 rule/fact/decision/experience 分类精炼写入（凭证只入密码库、记忆只存条目名）→ 建立迁移基线检查点 → 搜索与上下文抽查校验 → 转入标准工作流；明确只迁移确定的长期知识、原文档保留。/api/v1/system/prompt 增加 variant 参数（workflow/migration）。
4. 验收：后端覆盖 variant 参数与迁移提示词中英文关键内容、功能开关裁剪；前端覆盖场景切换、位置表渲染与迁移变体请求；完整门禁后发布 ARM。

2026-08-12 模型分配的双模式交互重做（已实施）

背景：模型页的"候选模型链"编辑器（自由列表 + 任务类别多选 + 顺序语义）对人不直观；用户期望配置完连接后，模型选择支持两种心智模型：全部任务统一使用一个模型（区分文本与视觉），或按任务类型分别指定。

契约：

1. 连接表单保留"文本模型 + 视觉模型"两个字段不变；其下新增"模型分配"分段开关：统一模型 与 按任务分配。
2. 统一模型：不显示任何链配置，保存时提交空候选链（后端链自动回落文本模型）；提示文案说明所有任务用文本模型、涉图内容用视觉模型。
3. 按任务分配：三个带标签的单选下拉——全局整理、开发项目、高频增量，均可留空表示"跟随文本模型"；一个"通用兜底"有序多选（任一模型失败冷却后按顺序尝试）；一个冷却秒数输入。视觉模型保持连接级单字段，不按任务拆分。
4. 保存映射：任务专属模型各生成一条对应类别候选，文本模型生成一条通配候选，兜底列表按顺序生成通配候选；该结构与既有后端候选链语义完全兼容，无后端改动。加载时按同样结构反解；无法精确表示的历史高级链（同类别多候选、default 标签等）折叠为"任务槽 + 兜底"，提示文案说明保存将按简化结构重写。
5. 候选健康（冷却中标签、最近错误）继续展示在对应的任务槽上。
6. 验收：Vitest 覆盖两种模式的保存载荷映射与历史链反解；ESLint、Prettier、TypeScript/Vite 构建通过；发布 ARM 后浏览器确认两种模式交互与现有生产配置的正确回显。

2026-08-09 模型连接测试的可见性与抗中断改造（已实施）

背景：保存/测试模型连接会同步执行完整能力探测（模型列表、双协议文本生成、结构化输出、流式、视觉），受超时与重试影响可达数分钟。现状按钮无加载状态、过程无反馈、结果仅一次性 toast，用户离开页面即错过结果；HTTP 请求被反向代理超时或客户端断开时探测协程可能被取消，依赖状态停留在 checking（生产已出现，靠探测循环 5 分钟后自愈）。

契约：

1. 探测单飞与抗中断：CurationManager 持有单个探测任务，保存/测试/自动探测统一入口；测试与自动探测复用运行中的任务，保存新配置则取消旧任务后重启。请求侧以 asyncio.shield 等待，客户端断开或代理超时不再取消探测，依赖状态必定被写入终态。
2. 启动自愈：服务启动时若依赖状态遗留 checking，将 next_probe_at 置为当前时间，由探测循环在 30 秒内重新探测，不再依赖旧的探测计划时间。
3. model_status 增加 probe 字段（running、started_at、trigger），Web 轮询可见探测进行中状态。
4. Web 模型页：保存与测试按钮增加加载状态；探测进行中显示驻留面板——本次将依次验证的项目清单（模型列表、Responses/Chat Completions 文本生成、结构化输出、流式输出、视觉模型）、已耗时秒数、"可离开页面，结果会保留"提示，期间每 2 秒轮询模型状态；完成后面板转为驻留的结果横幅（成功/失败 + 错误码文案 + 检查时间），不再依赖一次性 toast。测试按钮旁增加帮助图标说明测试内容。
5. 探测语义不变：仍使用连接配置的协议、流式与超时设置端到端验证；不改动模型网关。
6. 验收：后端覆盖探测单飞复用、保存替换旧探测、请求取消后状态仍到终态、启动 checking 自愈；前端覆盖加载状态、探测面板轮询与结果驻留；完整门禁后发布 ARM。

2026-08-08 输出截断显式检测与预算默认值提升（已实施）

背景：生产首个全局 full 整理失败于 MODEL_OUTPUT_INVALID。三批文档（4+4+2）的最后一批被旧公式 max(4096, 2048*n) 压到 4096 输出上限，推理模型的思考 Token 计入输出导致 JSON 截断，repair 调用同上限再次截断后任务失败；实例配置的 80000 输出上限对小批次不生效，属代码缺陷。已先行以 62fa810 将下限提高到 max(8192, 4096*n) 并发布。标准 OpenAI 兼容协议无法可靠读取模型最大输出值（/v1/models 不含该字段），因此不做"自动读取模型上限"，改用协议内的确定性截断信号。

契约：

1. 网关显式检测输出截断：Chat Completions finish_reason=length，或 Responses status=incomplete 且 incomplete_details.reason=max_output_tokens，抛出确定性 MODEL_OUTPUT_TRUNCATED（非 transient），不再把截断文本交给 JSON 解析产生误导性的 MODEL_OUTPUT_INVALID；配置候选链时按既有语义顺延下一候选。
2. Responses 流式 response.incomplete 是正常终止事件：计入流完成标记并作为终态响应参与截断判定，不再被误判为 MODEL_STREAM_INCOMPLETE 而按临时故障重试；Chat 流式装配保留 finish_reason。
3. 能力探测使用 16/32 Token 微预算，推理模型可能带 length 标记仍返回可用文本；全部探测调用豁免截断检测（fail_on_truncation=False），不因该标记把依赖判成配置错误。
4. 文档生成输出预算下限提升为 max(32768, 4096*文档数)；实例默认 context_output_tokens 从 8000 提升为 32000（SQLAlchemy 客户端默认，仅影响新实例，存量配置值不变）。
5. 暂不实施、观察真实运行后再定：截断后自动折半文档批次重试；对"max_tokens 过大"的 400 自适应钳制并按模型记忆实际上限（可存 curation_model_candidate_states）；机会式读取 /models 非标上限字段。
6. 验收：网关回归覆盖非流式/流式截断、探测豁免与 finish_reason 装配；预算与批次断言更新；完整后端门禁通过后发布 ARM。

2026-08-08 整理覆盖状态与统计修复（已实施）

生产诊断（192.168.32.100 实例，2026-08-08）：26 条活动记忆中 22 条待整理（含 7 条检查点），30 份活动整理文档存在且内容正常。确认以下原因，前两条为实现缺陷：

1. _apply_documents 写新 revision 时，文档元数据的 cited_source_ids 与 source_revisions 只包含本次运行的引用与来源；随后 rebuild_memory_curation_states 按“当前活动文档元数据”全量重建生命周期，上一轮已覆盖但本轮未再次引用的记忆整体翻回待整理。生产证据：任务 ed8aa16d（18:42）将约 10 条记忆置为已整理，任务 ce73902c（23:50）写入 revision 6（每份文档仅引用 1 条新来源）后这些记忆全部回到待整理。
2. 增量任务只收集变化来源，source_revisions 缺少未变化旧来源的 key；即使模型再次引用旧来源，revision 匹配也会失败。
3. 检查点计入待整理统计，但整理文档几乎不会逐条引用检查点，统计长期虚高。
4. 附带缺陷：rebuild_memory_curation_states 赋回原 updated_at 时值未变化、不进入 UPDATE 集合，onupdate=utcnow 仍触发，生命周期翻转会污染记忆的 updated_at。

修复契约（已按以下最终形态实现）：

1. 覆盖元数据跨 revision 累计：_apply_documents 写新 revision 时继承活动文档现有 cited_source_ids、source_revisions 与 supersedes 并与本次合并（_merge_document_coverage）；已删除记忆对应的历史引用在合并时剔除。本次重新引用的来源把 source_revisions 更新到新 revision；未再次引用的旧来源保留原 revision，因此被引用记忆再次编辑（revision 变化）仍自动回到待整理，现有 revision 匹配逻辑不变。元数据新增 job_cited_source_ids 记录本次任务实际引用，便于追溯；累计规模受范围内记忆数量约束，不会无界增长。
2. 模型对本批次每个来源声明处置：cited、redundant、no_action（文档生成调用的 JSON Schema 新增顶层 source_dispositions，Prompt/修复 Prompt 同步说明；PROMPT_VERSION=2026-08-08.1、SCHEMA_VERSION=3）。处置为宽松解析：未知来源 ID 或非法值直接忽略，模型输出缺少该字段时保持现状语义，不阻断任务。实现偏差（等价且更可靠）：redundant/no_action 不写入文档元数据，而是作为持久审阅标记落在 MemoryReference.reviewed_revision/reviewed_job_id 列——审阅可能不伴随任何文档变化，文档元数据无法承载；重建时 reviewed_revision == revision 且未被引用/替代的记忆计为已整理，covered_reason 区分 cited 与 reviewed。来源在收集后被再次编辑（revision 不匹配）时跳过标记，保持待整理。
3. 检查点与“待整理”统计分离：仪表盘 memory_lifecycle、AI 整理状态与 rebuild 统计不再把 checkpoint 计入 pending/covered/superseded，检查点单独计数（rebuild 返回 checkpoints）；记忆生命周期筛选新增 checkpoint 值，Web 记忆页与项目页提供该筛选；memory_search 的 current 语义保留检查点可搜索。检查点作为整理来源的行为不变。
4. 修复 rebuild 的 updated_at 保留：_preserve_updated_at 用 flag_modified 强制把原值纳入 UPDATE 集合，杜绝 onupdate 覆盖（与 Core update 等价、改动更小）。reset_memory_curation 同步修复并清除审阅标记。
5. 迁移 20260808_0014：memory_references 新增可空 covered_reason、reviewed_revision、reviewed_job_id 列，存量 covered 记忆回填 covered_reason='cited'。历史活动文档元数据为旧格式，已丢失的跨轮覆盖关系无法凭空恢复；发布后由用户手动触发整理，以新累计语义重建覆盖。
6. 验收：回归覆盖“第二轮重写不翻回已覆盖来源 + 处置声明落库 + revision 变化后审阅失效”（test_document_rewrite_keeps_previous_citations_and_review_marks_cover_sources）、“检查点统计分离与筛选”（test_checkpoints_have_their_own_lifecycle_bucket）、“updated_at 保留”（同前者断言）；生产发布后由用户手动执行整理复测收敛。

2026-08-08 AI 整理模型退避链与场景路由（已实施）

背景：当前 CurationModelConfig 为单连接单文本模型，模型不可用时任务进入 waiting_dependency 等待探测恢复。外部网关（如 Sub2API）能在同一模型的多个账号之间切换，但不做跨模型降级；跨模型退避由 MemRelay 自身实现。

契约（已按以下最终形态实现）：

1. 保持单连接（一个 Base URL、Token、协议），CurationModelConfig 新增 candidates_json（有序候选：模型名、任务类别、启用开关）与 candidate_cooldown_seconds（默认 600 秒）。不引入多连接或多 Base URL；候选链为空时回落 text_model 单模型链，向后兼容。视觉模型维持单独字段不变。
2. 任务类别与链（实现为集合匹配，与优先级方案等价且更简单）：每个任务派生类别集合 _job_task_classes——恒含 default，scope=global 加 global，trigger=source_change 加 incremental，项目 workspace_type=development 加 development。候选按声明顺序参与匹配：类别为空的候选匹配全部任务，否则要求与任务类别集合有交集；因任务恒含 default，标记 default 的候选天然充当所有链的兜底。任务内选择粘性：候选一旦成功即服务同一任务后续全部调用，保证证据/合并/文档批次的一致性。
3. 退避语义：单次请求保持现有最多 3 次有界重试（OpenAICompatibleClient 不变）；候选调用抛出任何 ModelGatewayError 时把该候选置入共享冷却（CurationModelCandidateState.cooling_until），同一任务内顺延到链上下一候选并记录切换事件；MODEL_AUTH_FAILED 属连接级错误，不触发切换。整链耗尽或全部冷却时抛出 MODEL_CANDIDATES_EXHAUSTED（transient，retry_after 取最近冷却剩余时间），任务进入 waiting_dependency。
4. 候选健康是运行时状态，存储于独立表 curation_model_candidate_states（按模型名主键），不进配置 revision 快照、不被配置保存重置；配置 revision 快照包含完整候选链，失败任务重试按现有语义使用当前配置，或 use_original_config 复用原链。
5. 探测按需进行：不做全候选周期轮询；连接保存时仍只端到端验证 text_model。候选可用性由真实任务调用驱动（成功清除冷却、失败进入冷却），冷却到期后自动重新参与选择。
6. 可观测性：ModelCall.requested_model 记录每次实际请求的候选模型（每个候选尝试一条记录）；执行输出新增 model_candidate_switched 事件（原候选、错误码、新候选），不含 Prompt 与秘密值；任务 usage 记录 model_used，文档元数据与来源指纹使用实际产出模型。
7. REST/MCP：ModelConnectionSaveRequest 新增 candidates（模型名去重校验）与 candidate_cooldown_seconds；model_status 的 connection 返回候选链及每候选健康（冷却状态、最近错误、最近成功/失败时间）；MCP curation_model_connection_save 同步扩展参数。Web 模型页提供链编辑（增删、类别多选、启用开关）与健康标签展示。
8. 验收：单元覆盖类别路由（test_job_task_classes_follow_scope_trigger_and_workspace）、冷却/跨任务共享/整链耗尽（test_candidate_chain_routes_falls_back_and_cools_failed_models）、任务内退避与调用记录/切换事件（test_call_model_switches_candidates_and_records_each_attempt）；真实网关跨模型退避留待生产观察（用户手动触发整理验收）。未配置 AI 的零配置模式行为不变。

交付顺序：先交付“整理覆盖状态与统计修复”（生产可见的正确性问题），再交付“模型退避链与场景路由”。两份方案已在同一提交中实现并通过完整前后端门禁；发布到 ARM 生产实例后不自动触发整理任务，由用户手动执行一次整理观察新逻辑（冗余文档处置、未整理残留收敛）作为最终验收。

2026-08-07 AI 整理长请求断线修复

• 生产任务在来源收集和批次准备完成后，长时间非流式 Responses 请求间歇出现 Server disconnected without sending a response.；短模型探测仍可成功，因此该问题属于长请求传输稳定性，而不是 SQLite、Basic Memory 或文档写回故障。
• httpx.RemoteProtocolError 属于 TransportError 而不是 NetworkError。模型网关必须统一捕获全部 httpx.TransportError，映射为可恢复的 MODEL_UNAVAILABLE，让任务进入 waiting_dependency、按有界退避等待探测恢复，而不是被最外层误标记为永久 CURATION_FAILED。
• 模型调用记录必须在所有异常路径结束；已知模型异常保存稳定错误码，未知异常保存 MODEL_CALL_FAILED 后继续向上抛出。服务启动时将上个进程遗留的 running 模型调用标记为 MODEL_CALL_INTERRUPTED，避免 Web/MCP 长期显示不存在的运行中调用。
• 回归测试覆盖模型列表与生成请求的远端协议断线、请求内重试、整理任务进入依赖等待、未知调用异常收尾和启动清理遗留调用。完整后端门禁通过后才允许发布。
• 正式实例发布前创建一致性备份，只原生重建 ARM64 memrelay 服务；模型连接启用已验证可用的流式 Responses，使用当前活动模型配置重试每个范围最新的一条传输失败任务，不批量重放已经被后续成功任务覆盖的旧失败记录。
• 生产重试进一步发现实例并发值为 3 时，多个任务会同时读取本地 Basic Memory 并触发 BASIC_MEMORY_TIMEOUT。并发降低或停用整理时现有 worker 必须在当前任务结束后自动退休，不能只增不减；Basic Memory 的超时和暂时不可用必须按任务级有界退避重新排队，不得永久失败，也不得错误污染模型依赖状态。
• 流式模型请求发生网络、协议断线或服务端临时故障时，只重试当前流式模式；只有服务明确拒绝流式参数或协议时才允许退回非流式，避免一次逻辑调用被放大为多轮长超时。配置的模型超时必须直接作为每次流式读取超时，不能隐式翻倍。
• 长模型调用每 60 秒写入一次不含 Prompt 或响应正文的安全进度事件；成功事件显示底层请求尝试次数和端到端总耗时。服务停止或 worker 取消时立即结束模型调用记录，避免依赖启动清理才能修正状态。
• 修复以提交 c3304bf 发布到正式 ARM64 实例。发布前一致性备份为 memrelay-20260807T140405Z.tar.gz，新镜像摘要为 sha256:050b38618ae05c9ae8161b79252bd27e45cd983785d8e02a868d0970f609994a，旧镜像保留为 memrelay:pre-curation-recovery-20260807。发布后两个容器健康，LAN/公网 readiness 均为 200，运行时 worker 为 1 / 1，队列、活动任务和运行中模型调用均为 0。
• 正式实例通过受控故障实验验证本地依赖恢复：停止 Basic Memory 后重试旧超时任务，新任务以 BASIC_MEMORY_UNAVAILABLE、retries=1 和未来 next_retry_at 回到 queued，尝试状态为 waiting_dependency，执行输出为 local_dependency_waiting；测试任务随后取消，Basic Memory 恢复健康，模型依赖未被污染。

2026-08-07 全链路复审结果

• 对照设计初衷重新核验记忆/项目上下文、检查点与时间线、外部密码库 CRUD/TOTP、目录化文件仓储、签名上传下载、MCP、动态提示词、可选 AI 整理和可选记忆 Git；Web、REST 与 MCP 仍共用同一服务层，AI/Git 未配置时基础模式可以独立运行。
• 修正能力发现的一致性：语义搜索状态根据 Basic Memory 实际健康状态返回，不再固定宣称已启用；memrelay://capabilities 与 capabilities_get 复用同一完整能力清单；MCP dashboard_get 补齐数据库、整理、记忆 Git 和 Basic Memory 运行状态。
• ARM64 线上验收发现 AI 整理状态包含时间字段时 memrelay://capabilities 无法直接 JSON 序列化；资源输出统一经过 FastAPI jsonable_encoder，并增加带真实 datetime 状态的 Streamable HTTP MCP 回归测试。
• 修正桌面文件仓储目录按钮的可访问名称，并让 Playwright 只定位本次创建的目录，避免多设备/历史目录存在时出现歧义。
• 本轮门禁：后端 153 passed, 18 skipped、Ruff 通过；前端 34 passed、ESLint、Prettier、TypeScript/Vite 构建通过；真实桌面 Playwright 1 passed；隔离 Docker 实例的 Streamable HTTP MCP 实测 95 个工具、3 个资源。
• 本地审计数据、测试 Token、测试文件和临时容器只存在于隔离目录，正式数据不在本轮本地测试中修改；线上发布必须在提交后重新备份并只重建 memrelay 服务。
• ARM64 发布后公网 HTTPS、REST 登录、95 个 MCP 工具、3 个 MCP Resources、外部 Vaultwarden 解锁、Basic Memory 语义搜索、SQLite WAL 和记忆 Git 均通过真实验证；OpenResty 只缓存带哈希的 /assets/，API 与 MCP 不进入代理缓存。AI 上游短暂 503 时任务保持有限合并队列，探测恢复后会自动重新排队并继续执行。

持续交付审计修正

• 密码库连接兼容私有网络和反向代理环境中的 HTTP/HTTPS Vaultwarden/Bitwarden 地址，不把是否启用 TLS 作为功能前置条件。
• AI 自动保存凭证时，只在名称相同且请求中提供的用户名、URI 等身份字段与已有条目吻合时自动更新；多个候选必须返回歧义，不能因“同名或任一 URI 相同”误覆盖其他账号。
• 文件元数据更新采用真正的局部更新语义，未提交字段保持原值；MCP 同时提供明确清空可空字段和解除项目关联的能力。
• 文件说明、版本、用途、标签或项目归属变化必须生成新的整理活动版本，不能因为文件正文校验值未变化而被静默去重。
• 一次性上传任务必须持久保存发起来源和记忆档案；上传完成、元数据更新、移动与删除由 Web 或 MCP 发起时，都必须以正确的 origin 和 usage_profile_id 进入同一整理事件流。
• 整理来源达到文件数量或字符预算时，未入选但仍存在的文件只能标记为未覆盖，不能生成删除墓碑；仅 MCP 来源策略不得把活动仓储文件误判为已删除。
• 文件扫描与密码库同步周期在运行中启用、停用或修改后必须生效，不要求重启服务，也不得在周期设为 0 时形成高频空转。
• 启动、周期、Web 和 MCP 文件扫描发现的外部新增、修改、恢复或丢失文件必须生成准确的整理活动；目录变化只维护目录表，不作为正文来源。
• 未显式指定 scope 但指定 project_id 的 memory_search 必须同时搜索该项目和当前记忆空间可见的全局记忆/整理文档，与 context_get 的全局规则继承语义保持一致；显式 scope=project 或 scope=global 时仍严格限定范围。
• MCP 必须提供写权限保护的 project_resolve_or_create：优先按 Git remote、设备目录和项目名称解析，找不到时仅用已提供的标识创建项目，并返回项目与 created 标记；动态提示词和能力清单必须引用真实存在的工具，避免新项目首个会话依赖两次非原子调用。
• 上述行为必须同时由 REST 与 MCP 回归测试覆盖，并继续保持 Web、REST、MCP 共用同一服务层。

原始记忆生命周期与稳定整理文档优化

执行状态：已完成。原始 Markdown 和完整来源追溯保持不变，默认浏览、搜索和上下文只关注尚未整理或重新发生变化的内容；数据库层保证同一范围、记忆空间、项目和文档类型只有一个活动整理文档。

1. 为原始记忆增加可重建的整理状态：pending、covered、superseded。记录被哪些活动整理文档覆盖、覆盖时的原始记忆 revision、整理任务和整理时间；原始 Markdown 仍是正文来源，整理状态属于可由活动整理文档元数据和变化游标重建的 SQLite 派生索引。
2. 新建或编辑原始记忆时自动回到 pending，清除旧覆盖关系；成功整理后，仅把被模型明确引用的记忆标记为 covered，把 supersedes 明确指出的旧记忆标记为 superseded，未被引用的来源继续保持 pending，避免静默隐藏未处理内容。
3. 全局和项目整理文档继续按稳定文档更新 revision，不为同类型内容反复创建文件。增加基于 scope + COALESCE(project_id) + COALESCE(usage_profile_id) + document_type 的活动文档唯一索引；迁移时保留最新活动文档并把历史重复项标记为已替代，不删除历史 revision。
4. context_get 优先读取稳定整理文档，并补充所有类型的 pending 原始记忆、整理游标之后发生变化的内容和最近检查点；为待整理来源和最新进度保留独立上下文预算，避免超长整理文档独占返回内容。memory_search 默认使用 current，同时搜索活动整理文档和待整理来源，排除 covered、superseded 与回收站内容；Web/MCP 可以显式检索这些历史来源。
5. 全局记忆页和项目记忆页提供“待整理、已整理、已替代、回收站、全部”筛选和状态数量，默认显示待整理内容；AI 未启用时所有现有活动记忆保持 pending，页面和基础记忆工作流不受影响。
6. REST 与 MCP 返回整理状态、覆盖文档、覆盖 revision 和整理时间；memory_list、memory_search 支持生命周期筛选，并提供把已整理或已替代记忆重新放回待整理队列的能力。重新整理只更新派生状态并记录新的变化事件，不复制正文。
7. 仪表盘和 AI 整理状态增加待整理、已整理、已替代和活动整理文档统计；整理任务详情记录本次覆盖、替代和仍待整理的记忆数量。
8. 启动时检查并修复缺失或过期的派生状态；迁移、备份恢复和旧实例升级后无需手工整理数据库。覆盖状态重建不得调用外部 AI，也不得修改原始 Markdown。
9. 验收覆盖：同类型整理多次只增加 revision、不增加活动文件；被引用记忆退出默认列表和搜索；编辑后重新变为待整理；未引用来源不被隐藏；已替代来源可追溯；AI/Git 均未配置时基础模式保持原行为；Windows AMD64 与 ARM64 正式实例迁移、备份和公网 Web/MCP 均正常。

生命周期优化验收：后端 Ruff 与全量 pytest 通过，结果为 141 passed, 18 skipped；前端 33 项 Vitest、ESLint、Prettier、TypeScript/Vite 构建和桌面浏览器布局通过。Windows Docker Desktop AMD64 和物理 Armbian ARM64 均完成原生镜像构建；正式实例迁移到 20260806_0012，启动重建得到 19 条待整理、4 条已整理、1 条已替代和 13 份活动整理文档，LAN readiness、公网 HTTPS 页面和生命周期筛选均正常。

执行状态：已完成。AI 整理与记忆 Git 保持默认关闭、彼此独立且完全可选；两者均未配置时不探测、不排队、不初始化仓库，基础 Web、REST、MCP、记忆、项目、搜索、密码库和文件仓储完整可用。Responses 非流式、SSE、原生 JSON Schema、真实整理、历史/差异/回滚、Windows AMD64、Armbian ARM64、备份恢复、正式迁移、公网 HTTPS/MCP 和重启恢复均已通过验收。

零配置基础模式是正式支持的完整运行方式，不是降级或试用模式。初始化、创建项目、使用 Web/MCP、健康检查和部署均不得要求填写模型或 Git 配置；AI 整理与记忆 Git 只能由用户分别显式启用，未启用时不产生后台探测、队列、工作区 clone、.git 目录、错误告警或额外外部请求。

最终验收结果

• 后端完整环境回归、Ruff、真实 Responses、真实 Git、并发、备份冷恢复和迁移链均通过；当前无外部凭证回归为 145 passed, 18 skipped，跳过项已在带真实依赖的独立验收中覆盖。
• 前端 27 passed，ESLint、Prettier、TypeScript、Vite 和桌面浏览器验收全部通过。
• Windows Docker Desktop 在所有可选构建加速参数为空时成功构建 linux/amd64 镜像；物理 Armbian 原生构建并运行 linux/arm64 镜像。
• 正式实例部署于 192.168.32.100:/opt/1panel/docker/compose/memrelay，数据位于 /data/memrelay-stack，数据库迁移至 20260806_0013；容器重启后项目、记忆、密码库、MCP 以及中断的 AI 整理任务自动恢复。
• https://mr.asio.asia 的登录、REST、Streamable HTTP MCP 均通过；上一轮线上验收发现 93 个工具和 3 个资源，本轮源码与隔离实例已核对为 95 个工具和 3 个资源。OpenResty 只缓存 /assets/，动态 API/MCP 不缓存。
• 正式实例在 AI/Git 都未配置时模型配置、整理队列、Git 连接和记忆仓库均为空，现有 2 个项目、23 条记忆引用、文件与已连接密码库保持可用。

完整交付审计与真实模型验收

1. 保留已通过的可选模式、SQLite WAL、多 worker、备份恢复、Windows AMD64 和 Armbian ARM64 能力，并对照两个正式计划逐项重新取证，不能用单元测试数量替代功能验收。
2. 修正项目源码 Git 地址的“身份规范化值”和“真实 clone URL”混用问题；补齐工作区来源策略、分支、密码库凭证引用、整理开关、Agent 最近同步和来源覆盖状态的 REST/MCP/Web 管理。
3. 修正项目归档与永久删除顺序：普通归档不得移动仍在使用的仓库；永久删除必须先删除 Markdown、生成本地 Git 删除提交，再归档 per_workspace 历史并保留可恢复的远程同步任务。
4. 补齐整理文档 revision 差异、调度默认恢复、间隔锚点、记忆空间统计与已有 MCP Token 重新绑定能力，并保持 Web、REST 与 MCP 同一服务层。
5. 扩展来源秘密过滤和提示注入验收，覆盖常见密码、Bearer/API Token、TOTP 种子、私钥、连接 URI 和常见平台 Token；测试凭证不得进入 Markdown、Git、日志、错误或临时产物。
6. 增加真实 Git 断网补推、服务重启、远程分叉、项目删除历史、Agent 优先/源码 Git 兜底、所有工作区模板、调度继承/恢复和真实 Streamable HTTP MCP 测试。
7. 使用运行时注入的新网关和 gpt-5.6-sol 完成 Responses 非流式、SSE、JSON Schema、模型探测、真实全局/项目整理、历史、差异、回滚及故障恢复；密钥只存在于进程环境或加密测试数据库。
8. 重新执行完整 pytest、Ruff、Vitest、ESLint、Prettier、TypeScript、Vite、Playwright、Windows Docker、备份冷恢复、ARM64 原生构建、正式数据迁移和公网 HTTPS/MCP 验收，最后清理测试环境并覆盖部署。

审计修正已经锁定以下契约：项目级关闭或归档会使其待处理整理任务停止；全局首次启用 AI 只为项目级启用的工作区建立基线；增量整理把已删除的记忆和文件作为来源墓碑处理；auto 来源策略在 Agent 数据新鲜且完整时不拉取源码 Git，过期或不足时才使用 Git 兜底；静默调度的 inherit、override、disabled 与周期调度保持一致；失败任务默认使用当前模型配置重试，也可显式复用任务原配置 revision。

无人值守 AI 整理与可选 Git 版本管理完整交付

本轮以 docs/ai-curation-plan.md 为详细功能、公共接口、可靠性和验收标准的权威文档，所有能力一次完整实现，不发布缺少计划能力的中间版本。

执行顺序：

1. 增加整理任务、尝试、来源、变化日志、文档、模型连接、依赖状态、调度、记忆空间及 Git 连接/仓库/同步任务的 Alembic 迁移和服务层。
2. 实现有界任务合并、运行中单一后继、调度租约、来源游标、内部事件过滤、模型配置快照、预算分批和异常恢复。
3. 实现 OpenAI-compatible Responses 与 Chat Completions、SSE/非流式、结构化输出、能力探测、退避暂停和自动恢复；真实 Responses 验收使用运行时注入的测试凭证，不把密钥写入 Git、日志或快照。
4. 实现 MCP/文件/Git 来源收集、文本/PDF/Office/图片 OCR/压缩包提取、可信边界、秘密过滤和整理 Markdown 自动应用。
5. 实现默认关闭的记忆 Git、本地历史、可选 remote、双凭证存储、push-to-create、离线补推、分叉处理、删除归档、历史/差异/恢复及远程检查/导入/冷启动。
6. 完成 REST、MCP、中文/英文桌面 Web、动态 Agent 提示词、状态诊断和 README/许可文档；AI 与 Git 未配置时必须保持当前基础服务行为。
7. 完成后端单元/集成、真实 Responses、调度与并发、MCP、前端 Vitest/TypeScript/ESLint/构建、Playwright、Windows Docker Desktop AMD64 和 Armbian ARM64 验收。
8. 通过全部验收后备份并部署到 192.168.32.100:/opt/1panel/docker/compose/memrelay，沿用 /data/memrelay-stack、端口 3003 和 mr.asio.asia，验证 LAN、公网 HTTPS、MCP、数据迁移、重启恢复与资源状态。

交付门槛：

• 模型长期不可用并积累大量变化时队列有界且不漏事件；恢复后自动补齐。
• AI 和 Git 可分别关闭，两者都未配置时不探测、不排队、不初始化仓库，也不影响现有功能。
• 所有模型、Git、Basic Memory 和文件外部 I/O 均不占用 SQLite 长事务；多 worker 不重复调度或领取。
• 测试密钥只通过进程环境或隔离的加密测试数据库使用；正式部署不包含测试连接、密钥或模型任务。
• Windows AMD64 与真实 Armbian ARM64 上全部测试和端到端工作流通过后才允许部署完成。

完整 AI 开发记忆工作流与正式部署

目标

• 让 Codex、Cursor、Claude Code 等客户端在新项目、新设备和新会话中，仅配置 MCP 与生成的 Agent 提示词即可识别项目、恢复上下文、持续记录开发历史、复用凭证和管理文件。
• Web、REST 与 MCP 共用同一套项目、记忆、检查点、密码库、文件仓储和系统能力，避免只在页面或单一客户端中可用的功能。
• 开发历史使用检查点统一记录，每条包含完成内容、原因、关键修改、验证结果、问题与解决方案及下一步，时间精确到秒并按最新在前展示。
• 对 MemRelay、Basic Memory、本地语义模型、Vaultwarden 连接、文件仓储、Web、REST、MCP、Docker 与反向代理进行完整能力和诊断审计，确认不存在静默降级、接口缺口或阻断主要工作流的问题。

后端与数据

• 新实例首次启动自动创建管理员 admin，初始密码为 242520；已有实例管理员不受影响，初始化接口继续作为显式关闭自动初始化时的兼容入口。
• 增加记忆和检查点永久删除能力，同时删除 Basic Memory Markdown 与 SQLite 可重建引用；归档和永久删除保持为不同操作。
• 记忆 frontmatter 明确保存 created_at 与 updated_at，更新时保留创建时间；检查点默认生成秒级标题和结构化正文。
• 记忆搜索结果返回范围、项目 ID 和项目名称，全局记忆明确标记为全局。
• 增加项目文档 ZIP 导出，直接生成 aidocs/project_context.md、项目记忆、全局记忆与清单；不让 AI 逐条读取后重写。导出使用短期签名下载地址，Web 和 MCP 均可准备下载。
• 仪表盘接口提供记忆类型分布、近 14 天新增记忆趋势、项目记忆排行、最近检查点、检查点数量、文件容量、有效 Token 与密码库状态。

MCP 与 Agent 提示词

• 补齐项目创建、更新、归档、删除和文档导出；记忆列表、永久删除；检查点删除；密码库同步；仪表盘与系统设置查询/更新等 MCP 工具。
• 能力资源和 capabilities_get 返回实际可用工具、权限及推荐工作流；破坏性操作保留明确标记，但不人为削减读写 Token 的管理能力。
• 动态提示词提供中英文版本并锁定工作流：会话开始发现能力和解析项目，支持 Resource 的客户端继续读取 memrelay://guide 与 memrelay://capabilities 获取当前能力状态；工作前读取上下文与最新检查点，过程中保存规则、偏好、事实、决定和经验，获得凭证后立即写入密码库，重要节点和结束前保存结构化检查点。
• 提示词要求登录或连接前先查密码库，唯一匹配直接复用；通用文件进入仓储；需要本地项目文档时直接下载并解压 ZIP 到 aidocs/，同时确保 .gitignore 包含 aidocs/。

Web

• 已有记忆的 Markdown 编辑器每次打开默认预览，新建记忆默认编辑。
• 项目列表增加搜索，项目名和 Git remote 分行显示；项目详情提供“项目记忆”和“开发时间线”标签及项目文档下载。
• 不设置独立进度页面；项目开发时间线显示秒级检查点并支持创建、编辑和删除；搜索与编辑页面显示每条结果所属项目或全局范围。
• 弹窗头部和底部操作区固定，正文按内容在内部滚动；Markdown、预览、日志和列表使用独立滚动区域并按桌面浏览器高度自适应。普通表单标签在左、控件在右，大型多行编辑器标签在上；提示文案使用标题旁帮助图标并在悬停时显示。
• MCP Token 页面同时管理记忆空间；默认提供共享/全部空间范围，全部记忆空间 Token 自动覆盖后续新增空间，具体空间 Token 仍可限制写入范围。
• 仪表盘使用原生 CSS、SVG 折线图和环形占比图展示聚合统计、趋势、依赖状态与最近活动，不新增重量级图表依赖；最近开发活动固定在依赖状态之后。
• 全局 AI 整理调度不显示或提交项目字段，项目调度才允许选择具体项目。

正式数据、文档与部署

• 更新 MemRelay 正式全局记忆、BDYG18Pro 项目记忆及最新开发检查点，清理无效测试数据。
• 将当前仍有效且可明确定位的基础设施账号、密码、Token 和服务登录信息精确匹配写入已连接 Vaultwarden，避免重复；普通记忆仅保存条目名称和用途。
• README 补充部署、使用、MCP 工具、Agent 提示词、备份恢复、项目导出，以及 AI、MCP、MemRelay、Basic Memory、Vaultwarden 和文件仓储的 Mermaid 架构图、关系图与时序图。
• 在 Windows Docker Desktop 完成 AMD64 回归后，构建并部署到 192.168.32.100 的 /opt/1panel/docker/compose/memrelay，数据保存在 /data/memrelay-stack，主机端口使用 3003。
• 备份 OpenWrt FRPC 配置后新增 mr.asio.asia 到 192.168.32.100:3003 的 HTTP 映射，验证公网 HTTPS、MCP Streamable HTTP、登录 Cookie 和转发头；API、MCP、认证及签名下载禁用代理缓存，仅静态资源允许长期缓存。
• 正式服务、数据和公网访问验收通过后关闭本机 MemRelay Compose，保留源码与构建缓存。

验收顺序

1. 后端迁移、单元测试、真实 Basic Memory、语义模型与 Vaultwarden 集成测试，并检查依赖健康、索引状态、降级状态和诊断信息。
2. MCP 工具发现、权限、完整新项目/新会话工作流与项目 ZIP 导出测试。
3. 前端 Vitest、TypeScript、ESLint、Prettier、Vite 构建和桌面 Playwright 验收。
4. Windows AMD64 镜像验收、Armbian ARM64 原生构建部署、FRP 与公网 HTTPS 验收。
5. 清理临时内容，更新时间线记忆、README 与第三方说明，检查 .gitignore 和全部工作树改动后提交独立中文 Commit。

总体方案

• MemRelay 是单管理员、单共享工作区的自托管 AI 记忆、密码库接入和文件仓储服务。
• 后端：Python 3.12、FastAPI、FastMCP、Pydantic、SQLAlchemy 2、Alembic、SQLite，使用 uv 管理依赖。
• 前端：Vue 3、TypeScript、Vite、Pinia、Vue Router、Element Plus、Vue I18n，使用 pnpm。
• 记忆引擎：Basic Memory v0.22.1，通过 Git 子模块固定源码并构建定制镜像。
• 密码库：只连接用户已有的外部 Vaultwarden/Bitwarden，不部署密码库服务。
• 许可证：AGPL-3.0-only；同步提供第三方依赖和本地语义模型许可清单。
• 支持 Windows Docker Desktop 的 Linux 容器模式，以及 Linux 原生 Docker/Compose 部署；不支持 Windows 容器模式。
• 发布固定版本的 linux/amd64、linux/arm64 Docker 镜像，不绑定特定 CPU 型号、核心数、内存容量或 Linux 发行版。
• 其他架构不作为正式发布和测试目标；不为缺少上游依赖的架构维护专用实现。

执行顺序

1. 同步计划与源码

• 任何代码实施前，先将本 Codex 计划完整同步到 docs/implementation-plan.md。
• 更新 aidocs/project_context.md，检查 .gitignore，提交 docs: 同步完整实施计划。
• 将 Basic Memory 添加为 third_party/basic-memory Git 子模块，固定到 v0.22.1，禁止跟随浮动分支。
• 提交 .gitmodules 和子模块引用，提交 chore: 引入Basic Memory源码。
• 后续所有实现必须同时遵循 Codex 计划和正式计划文档；决策变化时先同步两处。

2. 阶段零验证

• 从本地 Basic Memory 子模块审查 MCP 工具、Markdown 格式、自定义元信息、项目、归档、索引和错误模型。
• 验证 Streamable HTTP MCP 的写入、读取、搜索、移动、归档、索引重建和并发行为。
• 构建定制 Basic Memory 镜像，预置 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2。
• FastEmbed 完全在本地运行，不配置 OpenAI/LiteLLM，不消耗外部 AI Token 或产生 API 费用。
• ONNX/FastEmbed 线程数根据容器可用 CPU 自动选择并允许环境变量覆盖，模型缓存持久化到 /data/basic-memory/cache。
• 在 Windows Docker Desktop 的 Linux 容器环境验证 linux/amd64，在真实 ARM64 Linux 设备验证 linux/arm64；两种镜像均须能够启动并提供完整能力。记录模型加载、首次索引、增量写入、查询延迟和内存占用，用于发布说明和后续优化，不设置特定硬件性能门槛，也不使用 QEMU 模拟替代正式 ARM64 验收。
• 模型故障时保留全文、标签、元数据和关系搜索，Web 显示语义搜索降级状态。
• 验证 Bitwarden CLI 2026.7.0 在 AMD64/ARM64 下连接外部 Vaultwarden/Bitwarden、注册邮箱加主密码登录、个人 API 密钥登录、同步、TOTP、自动解锁、离线缓存和并发读取。
• 验证不通过时停止后续开发，先修正兼容版本或接口契约，不由实现者临时替换架构。

3. 基础框架与数据

• 建立 backend/、frontend/、deploy/、scripts/、third_party/ 目录。
• Web 使用 HttpOnly 服务端会话；管理员密码使用 Argon2id；MCP 使用 Bearer Token。
• 部署主密钥首次启动自动生成到持久化目录；可取回 Token 和密码库登录凭据使用 AES-GCM 加密。
• SQLite 保存管理员、会话、Token、项目、项目别名、记忆引用、幂等请求、密码库连接、凭证映射、文件目录、上传任务和系统设置。
• Alembic 管理迁移；迁移前备份数据库，失败时停止启动并保留旧数据。
• 后端统一错误码、超时、取消、健康检查和结构化日志；日志不保存密码、Token、TOTP 或文件上传地址。

4. 记忆与项目

• Basic Memory Markdown 是记忆正文唯一来源，按 global/、projects/<id>/、archive/ 组织。
• frontmatter 保存稳定 ID、范围、类型、项目、状态、revision、标签和时间；MemRelay SQLite 只保存可重建引用。
• 统一 SSH/HTTPS Git remote，结合目录、仓库名、人工别名和设备路径识别项目；歧义选择一次后保存映射。
• 明确规则、偏好、稳定事实、已确定决定和有效进度由读写 MCP 客户端自动保存。
• 推测、临时信息、冲突内容、普通闲聊及秘密值不自动保存；任务无实质变化时不生成空检查点。
• 记忆更新携带 revision；冲突返回最新内容；检查点只追加；创建使用请求 ID 保证幂等。
• Obsidian 可以直接读取 Markdown；第一版不保证外部编辑后的同步，所有正式写入统一通过 Web/MCP。
• 上下文依次组装全局规则、项目规则、偏好、事实、决定、最新检查点和相关经验，并限制返回长度。

5. 外部密码库

• 一个 MemRelay 实例维护一个外部 Vaultwarden/Bitwarden 连接。
• Web 支持两种登录方式：注册邮箱加主密码，或个人 API 密钥的 client_id、client_secret 加主密码；账号密码方式必须填写 Vaultwarden/Bitwarden 的注册邮箱，不能使用显示名称。
• API 密钥只负责 CLI 身份认证，主密码仍用于解锁密码库；账号、主密码、client_id 和 client_secret 均使用 AES-GCM 加密保存且不进入日志。
• 第一版不支持密码库账号二步验证；启用二步验证的账号使用个人 API 密钥方式连接。
• Bitwarden CLI 配置和加密缓存持久化，服务启动后自动登录和解锁。
• 默认每 5 分钟同步并支持 Web 手动同步。
• 外部服务不可达时允许读取最后一次成功同步的加密缓存，结果标明缓存状态和最后同步时间；恢复联网后自动刷新。
• 唯一凭证自动解析；多个候选选择一次并保存非秘密映射；未找到时才创建或询问用户。
• Web 和 MCP 支持登录条目的完整列表、详情、新建、修改和删除，字段覆盖账号、密码、多个 URI、备注、TOTP 和自定义字段。
• MCP 在 AI 获得、生成或修改可复用凭证后自动保存；没有条目 ID 时先按名称匹配，并使用请求中实际提供的用户名和 URI 继续收窄，唯一匹配才更新，没有匹配则创建，多个匹配返回稳定歧义错误。
• 秘密结果不进入普通日志、记忆或文件目录表。

6. 文件仓储

• 文件正文保存在配置目录；SQLite 文件目录表保存路径、名称、可空说明、可空版本、用途、标签、项目、MIME、大小、校验值、状态和时间。
• 启动时扫描，默认每 15 分钟周期扫描，Web/MCP 支持手动扫描；管理员可以调整或关闭周期扫描。
• Web/MCP 操作后立即更新目录表；外部新增、修改和丢失文件由扫描补齐。
• 文件版本只是可搜索字段，不保存历史版本。
• 只读 Token 可以搜索、列出和下载；读写 Token 可以更新说明、移动、重命名、删除及准备上传。
• 覆盖和删除只在用户明确要求时执行。
• MCP 不传输文件正文；file_upload_prepare 创建上传任务并返回一次性短期 HTTP PUT 地址。
• PUT 流写入临时文件，校验大小和可选哈希后原子移动，随后自动写入目录表；失败临时文件定期清理。
• 下载使用短期签名 GET 地址，支持 HTTP Range；上传和下载地址默认 10 分钟有效。

7. Web、部署与恢复

• 页面包括初始化、仪表盘、全局记忆、项目、搜索编辑、外部密码库、文件仓储、MCP Token、客户端配置、提示词、系统与备份；检查点统一在项目开发时间线中管理。
• 中文为默认语言，可切换英文；只适配桌面浏览器。
• 为 Codex、Cursor、Claude Code、VS Code 和通用 Streamable HTTP MCP 客户端生成配置和动态提示词。
• Compose 只包含 memrelay 和定制 basic-memory，统一挂载 /data。
• 同一套 Compose 配置用于 Windows Docker Desktop 和 Linux Docker；宿主机差异只通过环境变量、卷路径和部署脚本处理。
• 支持 UID/GID、时区、公共 URL、扫描周期、文件容量、上传限制和外部密码库配置。
• HTTP 不附加加密；HTTPS 由反向代理提供 TLS；生成地址沿用公共 URL 协议。
• 提供 Linux Shell 和 Windows PowerShell 手动备份脚本：停止 Compose、归档 /data、生成版本清单与校验值、恢复服务。
• 不实现定时备份和 Web 备份调度；外部 Vaultwarden/Bitwarden 数据由其自身备份。

公共接口

• REST 统一使用 /api/v1，覆盖认证、状态、项目、记忆、检查点、密码库、文件、上传任务、Token、客户端配置和系统设置。
• MCP 项目与记忆工具：capabilities_get、project_create/update/archive/delete/resolve/resolve_or_create/list/export_prepare、context_get、memory_list/search/get/save/mark_pending/archive/delete、checkpoint_get/save/delete。
• MCP 密码库工具：secret_capabilities、secret_list、secret_item_get、secret_search、secret_resolve、secret_get、secret_totp、secret_save、secret_delete。
• MCP 文件工具：file_search/list/get、file_directory_create、file_upload_prepare/status、file_metadata_update、file_move、file_delete、file_scan。
• MCP 整理工具：curation_run/status/history/source_submit/cancel/retry、curated_document_list/get/update/history/diff/revert、curation_settings_get/update、curation_schedule_list/save/delete/reset_defaults/preview、curation_model_connection_status/save/test、curation_model_list、usage_profile_list/save/token_bind/delete。
• MCP 记忆 Git 工具：git_connection_get/save/test/delete、git_mode_migration_preview/execute、memory_repository_list/create/status/sync/history/diff、memory_version_get/restore、memory_snapshot_restore、memory_repository_remote_inspect、memory_remote_import/bootstrap、memory_repository_unbind/archive_purge。历史查询支持时间、提交者、操作类型、工作区和资源 ID 筛选。
• MCP 系统工具：dashboard_get、system_settings_get/update、token_list/create/reveal/revoke/delete。
• MCP Resources：memrelay://guide、memrelay://capabilities、memrelay://projects。
• 读取和状态查询允许一次受控重试；写入不自动重试；超时、取消、冲突、候选歧义和依赖不可用返回稳定错误码。

测试与验收

• pytest 覆盖权限、加密、项目归一、revision、幂等、自动记忆、密码库映射与条目 CRUD、签名 URL、扫描和错误映射。
• 使用真实 Basic Memory 和测试 Vaultwarden 进行集成测试，覆盖在线、断网、重启、离线缓存与索引重建。
• 使用固定中英文检索样本验证多语言语义搜索，并断言运行期间没有外部嵌入 API 请求。
• Vitest 覆盖状态、表单、国际化和组件；Playwright 覆盖桌面端完整工作流。
• 验证 MCP 完整文件管理、一次性 PUT、Range 下载、15 分钟扫描、目录表实时更新和说明/版本搜索。
• 验证 HTTP、反向代理 HTTPS、Windows Docker Desktop、Linux Docker、linux/amd64、linux/arm64、目录权限、迁移失败和完整备份恢复。
• 每个阶段完成后清理临时内容、更新 aidocs/project_context.md、检查 .gitignore 并提交独立中文 Git commit。

已锁定默认值

• 单实例、单管理员、单共享工作区、单外部密码库连接。
• Element Plus、Vue I18n、AGPL-3.0-only。
• Basic Memory 以 Git 子模块固定在 third_party/basic-memory。
• Obsidian 只读兼容，不承诺外部 Markdown 编辑同步。
• 本地多语言 MiniLM 默认启用并预置镜像，不使用付费嵌入服务。
• 明确记忆自动保存；已有唯一凭证无感使用。
• 新获得或生成的可复用凭证由读写 MCP 客户端自动保存到外部密码库；唯一匹配条目直接更新，避免重复创建。
• 文件扫描默认 15 分钟；文件版本仅为元数据。
• MCP 完整管理文件，但上传只生成 HTTP PUT 地址。
• 密码库离线时允许使用最后同步缓存。
• 完整备份由手动短暂停机脚本触发。
• Windows 通过 Docker Desktop Linux 容器部署；Linux 通过原生 Docker/Compose 部署。
• 正式构建和测试 linux/amd64、linux/arm64 镜像，不针对 ARMv7 等缺少上游依赖的架构开发替代实现。