memorix 1.4.0 → 1.4.2

package/docs/1.4.2-EVIDENCE-GOVERNED-MEMORY-SPEC.md

@@ -0,0 +1,434 @@
+# Memorix 1.4.2: Evidence-Governed Memory and CodeGraph
+
+Status: implementation complete; release verification recorded in v1.4.2
+Branch: `codex/1.4.2-evidence-governor`
+Baseline: `v1.4.1`
+Updated: 2026-08-06
+
+## One-Sentence Product Contract
+
+Memorix should give an agent the smallest useful set of **current, source-backed
+project knowledge**, and should say "do not use memory here" when it cannot
+justify a useful answer.
+
+This is not a new prompt wrapper or a second knowledge store. It is the policy
+layer that unifies existing observations, claims, workflows, CodeGraph evidence,
+Git state, and verification results before they reach an agent.
+
+## Why This Release Exists
+
+The product already has much of the necessary foundation:
+
+- source-backed claims and code-reference freshness;
+- versioned CodeGraph snapshots and bounded Worksets;
+- retention, archive, workflow, and background-maintenance primitives;
+- project context through MCP and CLI.
+
+Those pieces currently answer related questions in different modules. A memory
+can be relevant but old, source-backed but never verified, or compact but still
+harmful for the current task. 1.4.2 makes the final decision explicit,
+consistent, inspectable, and shared by CLI, MCP, hooks, and dashboard surfaces.
+
+## Research Constraints
+
+This release follows published findings without overstating what they prove.
+
+1. Similar retrieved experiences can cause agents to imitate prior outputs,
+   including wrong or misaligned ones. Memory quality and deletion policy are
+   product safety concerns, not cleanup cosmetics.
+2. Long-horizon memory needs indexing, retrieval, reading, temporal updates,
+   and abstention. Retrieval quality alone is not enough.
+3. Dynamic note links and hierarchical storage are useful only when the source,
+   freshness, and revision path remain visible.
+4. Persistent memory is a privacy boundary. Retrieval must preserve scope,
+   visibility, and provenance instead of treating all stored text as promptable.
+
+The primary research references are listed at the end of this document. Recent
+2026 preprints may guide investigation but do not become product truth without
+reproducible local tests.
+
+## Terms
+
+| Term | Meaning |
+| --- | --- |
+| Candidate | Any possible context item: observation, claim, workflow, code fact, Git fact, test result, or wiki page. |
+| Evidence | A source that can be checked later: file/symbol hash, CodeGraph snapshot, commit, test/run result, document, or explicit user action. |
+| Qualification | The deterministic check that decides whether a candidate is current enough, visible to this caller, and safe enough to use. |
+| Context plan | The bounded answer to: inject nothing, inject a compact card, inject selected evidence, or schedule more work. |
+| Outcome signal | A later, auditable fact such as a focused test passing, a claim being corrected, or a memory helping a verified task. |
+| Observation period | The period after capture before a memory is promoted to trusted reusable knowledge. |
+
+## Non-Negotiable Invariants
+
+1. **No automatic context dump.** Existing memory is not a reason to inject it.
+2. **No silent truth rewrite.** A model may propose a link, summary, or
+   promotion; it cannot overwrite evidence-backed claims without an auditable
+   transition.
+3. **No model-only authority.** Test, Git, code, and explicit user signals outrank
+   a generated confidence score.
+4. **No new default MCP tool explosion.** `memorix_project_context` remains the
+   primary agent surface. Advanced diagnostics stay grouped and opt-in.
+5. **CLI and MCP parity.** Both construct the same context plan from the same
+   policy. Hooks only trigger the plan; they do not own a separate policy.
+6. **Foreground stays fast.** Context assembly may schedule refresh or analysis,
+   but never waits for a corpus scan, remote provider, or LLM synthesis.
+7. **Code facts are versioned.** A narrative cannot claim that code is current
+   without a matching snapshot or an explicit caution.
+8. **Scope is enforced before relevance.** Personal, project, team, and public
+   knowledge do not mix merely because embeddings are similar.
+
+## Target Architecture
+
+```text
+observations / claims / workflows / wiki / Git / tests / CodeGraph
+                              |
+                              v
+                    candidate collection
+                              |
+                              v
+                  evidence qualification gate
+          scope -> provenance -> freshness -> conflict -> quality
+                              |
+                              v
+                   budgeted context planner
+             abstain | compact card | selected detail
+                              |
+                              v
+               MCP / CLI / hook / dashboard explain view
+                              |
+                              v
+          verified outcomes feed lifecycle and CodeGraph links
+```
+
+The governor is deliberately a pure, deterministic core. Storage adapters and
+renderers call it; it does not import an MCP server, hook implementation, or UI.
+
+## Data Contracts
+
+### 1. Context Candidate
+
+```text
+ContextCandidate
+  id, kind, projectId, scope, visibility
+  title, compactText, sourceRefs
+  capturedAt, observedAt
+  freshness                 current | suspect | stale | unknown
+  conflict                  none | possible | confirmed
+  quality                   probation | verified | degraded | blocked
+  relevanceSignals          lexical, semantic, task-lens, code-link
+  estimatedTokens
+```
+
+Existing records are adapted into candidates. This is not a duplicated store.
+
+### 2. Qualification Result
+
+```text
+QualificationResult
+  candidateId
+  disposition              include | compact | defer | exclude
+  reasons[]                stable machine-readable reason codes
+  evidenceSummary[]        source type, id, snapshot/revision, locator
+  qualitySignals[]         verified test, successful reuse, user pin, correction
+  freshness
+  tokenCost
+```
+
+An excluded item is visible in diagnostics only. It is never silently presented
+as if it had not existed.
+
+### 3. Context Plan
+
+```text
+ContextPlan
+  task, taskLens, projectState
+  mode                     abstain | card | workset
+  selected[]               QualificationResult
+  deferred[]               bounded follow-up suggestions
+  cautions[]
+  budget                   requested, used, remaining
+  scheduledMaintenance[]
+  explanationId
+```
+
+`abstain` is a successful result. It means Memorix did not find sufficiently
+qualified context and recommends normal repository inspection instead.
+
+### 4. Outcome Signal
+
+```text
+MemoryOutcomeSignal
+  id, candidateId, projectId, kind
+  kind                     test-pass | test-fail | verified-reuse |
+                           user-pin | user-correction | source-changed |
+                           conflict-confirmed | manual-review
+  sourceRef, snapshotId, observedAt
+  detail                   sanitized, bounded explanation
+```
+
+Outcome signals are append-only audit facts. They update a derived quality
+state; they do not erase the original memory. A generic manual review is
+auditable but does not by itself raise quality: verification or an explicit
+user pin is still required.
+
+## Lifecycle Policy
+
+1. **Capture:** new observations remain usable as local session material but are
+   labelled `probation` for durable retrieval.
+2. **Qualify:** source and scope are checked. Code-bound items are matched to a
+   snapshot; unbound assertions remain lower confidence.
+3. **Promote:** explicit user pin, review approval, successful verified reuse,
+   or source-backed test/Git evidence can promote a candidate.
+4. **Degrade:** changed/deleted source, failing verification, contradiction, or
+   a user correction downgrades the derived quality state.
+5. **Archive:** retention rules continue to govern cleanup, but archive decisions
+   consume this shared state instead of copying their own freshness formula.
+6. **Recover:** an archived fact can be revisited with its original evidence;
+   archive never means invisible deletion by default.
+
+No score alone can cause destructive deletion. A score can only suggest a
+review or make a candidate ineligible for automatic injection.
+
+## CodeGraph Upgrade
+
+### Product Goal
+
+CodeGraph becomes the code evidence service for the governor. It should answer
+four practical questions quickly:
+
+1. What files and symbols are relevant to this task now?
+2. What changed since this memory or workflow was formed?
+3. What may be affected if this symbol or file changes?
+4. How complete and trustworthy is that structural answer?
+
+### New Capabilities
+
+#### A. Snapshot Diff
+
+The first 1.4.2 slice adds a hash-only **file** manifest to each completed
+snapshot. It can report added, modified, and removed indexed files between two
+complete snapshots. It stores paths and hashes, never a second copy of source.
+
+Symbol and relation history are not yet retained per snapshot, so this release
+does **not** pretend to provide historical symbol/edge diffs. Current graph
+relations are used only for the bounded impact slice below.
+
+Target shape for later schema evolution:
+
+```text
+CodeStateDiff
+  fromSnapshotId, toSnapshotId
+  added/changed/removed files
+  added/changed/removed symbols
+  added/changed/removed relations
+  completeness delta
+  affected observation/claim/workflow references
+```
+
+This must report unknowns from incomplete scans. It is not allowed to label an
+unscanned path as unchanged.
+
+#### B. Impact Slice
+
+Given a file or symbol, return a bounded, explainable graph slice:
+
+```text
+ImpactSlice
+  root references
+  inbound and outbound relations
+  direct test/config/workflow references when available
+  confidence, coverage, traversal limit, and reasons
+```
+
+The first release supports direct edges and a small bounded traversal only. It
+does not claim whole-program call-graph precision.
+
+#### Implemented Slice
+
+- `memorix codegraph diff` compares the newest two snapshots by default, or
+  accepts explicit `--from` and `--to` snapshot ids.
+- `memorix codegraph impact --path <relative-source-path>` exposes the same
+  bounded current one-hop graph slice to CLI-only agents. It rejects paths that
+  are not in the current index instead of reporting a misleading empty result.
+- A diff is refused when either snapshot is incomplete or predates the manifest
+  schema. The result explains why instead of treating absent data as unchanged.
+- The impact view resolves both file edges and symbol edges to current files,
+  follows only one hop, and caps relation traversal. It is an inspection aid,
+  not a guarantee of complete impact coverage.
+- Lite deterministically resolves local relative import paths, including the
+  Node ESM `.js`-from-`.ts` convention. It still does not claim semantic symbol
+  resolution or whole-program call-graph precision.
+- A continuation Workset reports how many stale memory bindings point directly
+  at the changed snapshot files. It does not attribute unrelated old stale
+  memory to the current change.
+- The Workset governor now filters optional claims, workflows, durable memory,
+  and code-bound memory before prompt rendering. Its receipt records the safe
+  disposition and reason without exposing hidden content. In this first slice,
+  task facts, Git state, current code state, and safety cautions remain outside
+  the optional-evidence gate so an abstention never hides current source facts.
+
+#### C. Test and Verification Links
+
+Workflow runs now record an append-only pass/fail signal for their selected
+claims and durable memories. The newest signal is applied only as a delivery
+qualification: a failed verification degrades optional context instead of
+silently rewriting or deleting the original record. A later code change can
+then downgrade the confidence of a memory that says "this is verified" rather
+than leaving an old green test as permanent proof. File/symbol references on
+individual test outcomes remain a later extension.
+
+#### D. Provider Coverage Contract
+
+Every provider returns:
+
+```text
+ProviderCoverage
+  provider, parserMode, supportedLanguages
+  indexedFiles, skippedFiles, skippedReasons
+  relationTypes, confidencePolicy
+  snapshotCompleteness
+```
+
+CodeGraph Lite remains a mandatory local fallback. Parser-backed or external
+providers are optional accelerators and may only add normalized facts through
+this contract. They cannot bypass project scope, source epoch, or secret rules.
+
+#### E. Claim-to-Code Requalification
+
+Existing claim and observation code references should consume snapshot diffs:
+
+- removed source -> `blocked` or `needs-review`;
+- changed bound source -> `degraded` until rechecked;
+- current source plus fresh verification -> `verified`;
+- incomplete provider coverage -> `unknown`, never falsely `current`.
+
+## Retrieval Policy
+
+The governor collects candidates first, then applies this order:
+
+1. project identity, scope, visibility, and secret policy;
+2. hard exclusions: deleted evidence, forbidden scope, confirmed contradiction;
+3. source freshness and provider completeness;
+4. task lens and direct code/Git/test links;
+5. quality signals and explicit user review;
+6. relevance ranking and diversity;
+7. strict section and total token budgets.
+
+Default delivery is progressive:
+
+- **abstain:** no qualified advantage; return normal start files only;
+- **card:** one compact "where we were / what changed / what to verify" card;
+- **workset:** selected details with source references and cautions;
+- **defer:** schedule a refresh or requalification without blocking the agent.
+
+## Public Experience
+
+Normal users still say a natural-language task, for example:
+
+> Continue the auth migration. What remains and what must be checked first?
+
+They receive a short, useful answer. They do not see score arithmetic.
+
+An explicit diagnostic path can answer:
+
+```text
+Why did Memorix include or skip this memory?
+Which code snapshot supports it?
+What changed since it was verified?
+How much context budget did it consume?
+```
+
+This diagnostic output is grouped under existing context/knowledge diagnostics;
+it is not a new default tool for every graph operation.
+
+## Delivery Phases
+
+### Phase 0: Baseline and Compatibility
+
+- Inventory all existing context ranking, retention, claim, freshness, and
+  CodeGraph paths.
+- Add a behavior matrix covering current output and no-regression fixtures.
+- Establish deterministic context-plan fixtures: abstain, compact card, stale
+  code caution, conflict exclusion, and incomplete graph coverage.
+
+### Phase 1: Governor Core
+
+- Implement candidate adapters and pure qualification/context-plan modules.
+- Route `project_context`, `context_pack`, and CLI context/resume through the
+  same plan builder without changing their stable output contracts.
+- Add explicit abstention and reason codes.
+
+### Phase 2: Outcome and Lifecycle Unification
+
+- Add append-only outcome signals and derived candidate quality.
+- Route retention report, HTTP/dashboard status, archive eligibility, and
+  claim requalification through one lifecycle evaluation path.
+- Treat test/Git/source changes as higher-quality signals than model estimates.
+
+### Phase 3: CodeGraph Evidence Upgrade
+
+- Add snapshot diffs, bounded impact slices, coverage reporting, and test/run
+  reference links.
+- Requalify claim/observation references from diffs.
+- Add fixture coverage for changed symbol, removed file, incomplete scan, and
+  uncertain relation handling.
+
+### Phase 4: Explainability and Operator UX
+
+- Add context-plan explanations to CLI JSON and grouped diagnostics.
+- Add dashboard views for quality state, source freshness, impact slice, and
+  exclusion reason without leaking hidden/private evidence.
+- Keep the normal agent path quiet.
+
+### Phase 5: Verification and Release Gate
+
+- Run unit, SQLite reopen, provider fallback, CLI, MCP, hook, and packaged
+  installation checks.
+- Run isolated agent smoke tests with qualified context, stale context, and
+  abstention scenarios.
+- Measure first-turn latency, token usage, stale-context catches, and false
+  inclusion/exclusion rates against Phase 0 fixtures.
+
+## Acceptance Criteria
+
+1. Every automatic inclusion has a machine-readable reason and at least one
+   visible source or explicit `unknown` caution.
+2. A changed or deleted code source changes the retrieval disposition without a
+   human rediscovering the mismatch.
+3. A task with no qualified memory returns less context, not a generic summary.
+4. CLI, MCP, and hooks select the same qualified evidence for the same task and
+   project state.
+5. An incomplete CodeGraph provider result can never be formatted as complete
+   code truth.
+6. Test failure, user correction, and source change can lower reusable-memory
+   quality; no score-only path deletes a memory.
+7. Existing stored observations, claims, workflows, context commands, and lite
+   MCP profile remain backward compatible.
+8. Default MCP tool count does not increase.
+
+## Explicit Non-Goals
+
+- A remote graph database requirement.
+- Silent LLM rewriting of a project's wiki or workflow.
+- Claiming exact whole-program impact analysis from CodeGraph Lite.
+- Replacing a real language server, CodeGraph product, Git, or test runner.
+- Auto-capturing all conversations, screenshots, or tool outputs.
+- Treating a visual graph as proof of a maintained semantic knowledge graph.
+
+## Research References
+
+- Xiong et al., "How Memory Management Impacts LLM Agents: An Empirical Study
+  of Experience-Following Behavior," ACL 2026.
+  https://aclanthology.org/2026.acl-long.27/
+- Wu et al., "LongMemEval: Benchmarking Chat Assistants on Long-Term
+  Interactive Memory," ICLR 2025.
+  https://iclr.cc/virtual/2025/poster/28290
+- Xu et al., "A-MEM: Agentic Memory for LLM Agents," NeurIPS 2025.
+  https://neurips.cc/virtual/2025/poster/119020
+- Kang et al., "Memory OS of AI Agent," EMNLP 2025.
+  https://aclanthology.org/2025.emnlp-main.1318
+- Tan et al., "MemBench: Towards More Comprehensive Evaluation on the Memory
+  of LLM-based Agents," Findings of ACL 2025.
+  https://aclanthology.org/2025.findings-acl.989.pdf
+- Wang et al., "Unveiling Privacy Risks in LLM Agent Memory," ACL 2025.
+  https://aclanthology.org/2025.acl-long.1227.pdf

package/docs/API_REFERENCE.md

@@ -114,7 +114,7 @@ MCP:
 - `memorix_codegraph_status` returns provider/index counts for the current project.
 - `memorix_context_pack` builds a task-specific packet with reliable current memories, lower-trust unbound memories, current code facts, freshness warnings, suggested reads, and suggested verification.
 
-`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Continuation delivery is separate from the task lens: continuation language in `memorix_project_context` enables a bounded prior-work projection, and `memorix resume "..."` makes that choice explicit. It includes only the latest useful session summary, up to three readable durable memories, and at most one recent source-labelled compact checkpoint. Checkpoints are host lifecycle evidence, not durable memory or transcript backups; ordinary new tasks do not receive historical-session context. A completed MCP brief is the default retrieval boundary: search, detail, or Context Pack should expand it only for a named missing fact or an explicit request for deeper history. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
+`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags an old `ACTIVE_WORK.md`, legacy `progress.txt`, or legacy dev-log note as historical when it predates the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Continuation delivery is separate from the task lens: continuation language in `memorix_project_context` enables a bounded prior-work projection, and `memorix resume "..."` makes that choice explicit. It includes only the latest useful session summary, up to three readable durable memories, and at most one recent source-labelled compact checkpoint. Checkpoints are host lifecycle evidence, not durable memory or transcript backups; ordinary new tasks do not receive historical-session context. A completed MCP brief is the default retrieval boundary: search, detail, or Context Pack should expand it only for a named missing fact or an explicit request for deeper history. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
 
 Project-specific generated, vendored, or cache paths can be excluded from Code State with `[codegraph].exclude_patterns` in `memorix.toml` or `~/.memorix/config.toml` (`codegraph.excludePatterns` in legacy YAML). User patterns extend the built-in excludes and are applied to indexing, Project Context suggested reads, and Context Pack suggested reads.
 

package/docs/KNOWN_ISSUES_AND_ROADMAP.md

@@ -1,149 +1,73 @@
-# Memorix 已知问题 & 未来路线图
+# Memorix 已知边界与路线图
 
-> 最后更新: 2026-03-09 (v1.0.0)
+> 最后审阅：2026-08-03（对照 v1.4.0）
 
----
+这份文档说明仍然成立的产品边界、风险和方向；它不是发布流水账。
 
-## 已知问题 & 限制
+- 已发布版本和每次修复的事实，以 [CHANGELOG](../CHANGELOG.md) 为准。
+- 当前正在进行的维护工作，以 [ACTIVE_WORK](../ACTIVE_WORK.md) 为准。
+- 可讨论、可订阅的后续事项，以 GitHub Open Issues 为准。
 
-### 🔴 严重
+---
 
-| # | 问题 | 影响 | 状态 |
-|---|------|------|------|
-| 1 | ~~**无文件锁**~~ — 多 Agent 同时写入 | 数据完整性 | ✅ v0.7.11 (`withFileLock` + `atomicWriteFile`) |
-| 2 | **Orama where 过滤不可靠** — 空 term + number filter 时结果可能不正确 | `compactDetail` 已绕过 (使用内存查找) | 已变通 |
+## 当前产品边界
 
-### 🟡 中等
+Memorix 是本地优先、可插拔的 Agent Memory 系统。它给不同 Agent 或同一 Agent 的新会话提供同一个项目记忆层，并把 CLI 作为最完整、最稳定的控制面；MCP 是面向 Agent 的受控入口，而不是唯一入口。
 
-| # | 问题 | 影响 | 状态 |
-|---|------|------|------|
-| 3 | **非 Git 项目的 projectId 不稳定** — 基于目录名，不同机器或路径会不同 | 数据隔离 | 未修复 |
-| 4 | ~~**retention 只有报告没有执行**~~ | 数据膨胀 | ✅ v0.7.11 (`archiveExpired` + `action="archive"`) |
-| 5 | ~~**实体抽取不支持中文标识符**~~ | 中文项目覆盖不足 | ✅ v0.7.11 (中文括号/反引号 + 因果语言) |
-| 6 | ~~**auto-relations 每次读取全图**~~ | 性能 | ✅ v0.7.11 (entityIndex O(1) 查找) |
-| 7 | **高重要性 observations 永远免疫** — gotcha/decision/trade-off 永不过期 | 数据膨胀 | 设计如此，需评估 |
+当前版本已经包括：
 
-### 🟢 轻微
+- 项目记忆、会话续接、任务透镜和按需展开的上下文；
+- 代码状态、知识库 / Wiki、知识图谱投影和工作流记录；
+- 受控的本地媒体资产库，可显式导入图片、音频、视频和 PDF，并保留来源、哈希、配额和删除审计；
+- 多 Agent 集成、hook、doctor / repair，以及可选择的后台维护；
+- SQLite 规范存储、可见性边界、保留策略和清理审计。
 
-| # | 问题 | 影响 | 状态 |
-|---|------|------|------|
-| 8 | ~~**Kiro/Trae Agent hooks 未实现**~~ | 功能缺失 | ✅ v0.9.12+ (Kiro/Trae/OpenCode/Gemini CLI 全部支持) |
-| 9 | **fastembed 首次使用需下载模型** — ~30MB，可能在网络不好时超时 | 用户体验 | 需用户显式安装 |
-| 10 | **npx 缓存可能损坏** — 见 `MODULE_NOT_FOUND chownr` 问题 | 安装体验 | 需文档说明 |
+这些能力并不等于“任何数据都会被自动收集”或“所有媒体都已经被模型理解”。Memorix 的默认边界是显式、可追溯、可清理，避免把无关聊天、任意本地文件或有成本的模型调用悄悄写入长期记忆。
 
 ---
 
-## 未来路线图
-
-### Phase 1: 稳定化 ✅
-- [x] Copilot Adapter 实现
-- [x] Antigravity Adapter 实现
-- [x] MCP Server 集成验证
-- [x] 753 测试通过 (v1.0.0)
-- [x] 开发文档编写
-- [x] README 优化 (中英双语, Antigravity 配置指南)
-- [x] npm 发布配置优化
-
-### Phase 2: 推广 & 用户获取
-- [ ] 社区推广 (Reddit, HN, X, Discord)
-- [ ] 技术博客文章
-- [ ] 演示视频
-- [ ] 与其他 MCP Server 项目的对比文档
-
-### Phase 3: Web Dashboard ✅
-- [x] 知识图谱可视化 (D3.js force graph)
-- [x] Observation 搜索/浏览 Web UI
-- [x] 记忆保留状态仪表板
-- [x] 跨项目记忆概览 (project switcher)
-
-### Phase 4: 功能增强 ✅
-- [x] 自动归档过期记忆 (`memorix_retention action="archive"`)
-- [x] 文件锁机制 (多进程安全)
-- [x] 搜索精确度优化 (fuzzy + field boosting)
-- [x] 中文实体抽取
-- [x] 图谱-记忆双向同步
-- [x] `memorix_transfer` — 导出/导入记忆 (JSON + Markdown)
-- [x] 记忆去重和冲突检测 (`memorix_deduplicate` + `memorix_consolidate`)
-- [x] LLM 增强模式 (压缩/重排序/写入时去重)
-
-### Phase 5: Agent 集成 ✅
-- [x] Kiro 完整支持
-- [x] Trae 支持
-- [x] OpenCode 支持
-- [x] Gemini CLI 支持
-- [x] Copilot hooks 支持
-- [x] 10 个 Agent 全覆盖
-
-### Phase 6: v1.0.0 特性 ✅
-- [x] 团队协作 (Agent注册/文件锁/任务板/消息)
-- [x] 工具合并 (41 → 22 默认)
-- [x] 启动自动清理 (归档 + LLM/Jaccard 去重)
-- [x] Mini-Skills (永久技能, 自动注入)
-- [x] 会话管理 (跨会话上下文注入)
-
-### Phase 7: 未来路线图
-- [ ] 多项目记忆关联搜索
-- [ ] LLM-based 实体抽取 (替代正则)
-- [ ] JetBrains AI 支持
-- [ ] VS Code + Continue.dev 支持
-- [ ] 自定义 embedding 模型支持
-- [ ] 记忆联邦协议 (跨团队共享)
+## 仍需注意的边界
+
+| 主题 | 现状 | 使用建议 |
+|---|---|---|
+| 项目绑定 | 没有可靠工作区根目录时，MCP 会等待显式根目录、MCP Roots 或会话启动，而不会猜测上一个项目。 | 这是防止跨项目读写的安全边界；首次接入时按客户端的项目根目录配置即可。 |
+| 向量与外部模型 | 可选嵌入提供商、网络和首次模型准备会影响写入或检索延迟。 | 不要把外部 API 的瞬时可用性当作本地数据是否已写入的唯一判断；先用 `memorix status` / `doctor` 看状态。 |
+| 媒体记忆 | 已有受控附件和元数据/向量基础，但 PDF 文本提取、音频转写、视频语义提取仍不是默认的全自动链路。 | 只导入确实需要长期复用的资产；不要把截图或工具输出当作默认记忆来源。 |
+| 图谱与 Wiki | 它们是从规范记忆和代码状态生成的可追溯投影，不是可任意编辑的 GraphRAG 数据库。 | 先写清楚有来源的知识和决策，让投影自然形成关联；不要把图谱当作另一份手工真相。 |
+| Agent 集成 | 上游客户端会改变 hook、MCP、配置文件和权限模型。 | 使用 `memorix doctor agents` 诊断，优先让 `setup` / `repair` 做非破坏性修复。 |
+| 大规模数据 | 保留、归档、去重和检索预算已存在，但上万至百万级数据仍需要按项目负载做容量验证。 | 为高增长项目配置明确的保留与清理策略，并关注 Dashboard / CLI 的审计信息。 |
 
 ---
 
-## 依赖关系
-
-### 运行时依赖
-| 包 | 版本 | 用途 |
-|---|------|------|
-| `@modelcontextprotocol/sdk` | ^latest | MCP 协议 SDK |
-| `@orama/orama` | ^latest | 全文/向量搜索 |
-| `gpt-tokenizer` | ^latest | Token 计数 |
-| `citty` | ^latest | CLI 框架 |
-| `@clack/prompts` | ^latest | CLI 交互提示 |
-| `zod` | ^3 | 参数验证 |
-
-### 可选依赖
-| 包 | 版本 | 用途 |
-|---|------|------|
-| `fastembed` | ^latest | 本地 ONNX embedding (384d)，需用户显式安装 |
-
-### 开发依赖
-| 包 | 版本 | 用途 |
-|---|------|------|
-| `vitest` | ^latest | 测试框架 |
-| `tsup` | ^latest | 打包构建 |
-| `typescript` | ^5 | 类型系统 |
+## 公开路线
 
----
+### 1. 稳定性与可操作性
+
+- 继续以 Windows、macOS/Linux、CLI、MCP、后台服务和全新安装作为发布门槛；
+- 保持 MCP 工具面小而按需展开，CLI 保持完整的管理和恢复能力；
+- 让配置迁移、诊断、修复和清理保持非破坏性、可解释、可回退。
+
+### 2. 记忆质量与知识工作区
 
-## 技术债务
+- 提高“新会话接手”时的相关性：先给简短进度卡，再按任务取详情；
+- 统一保留状态、归档、检索预算和 Dashboard 的解释，避免同一条记忆在不同入口显示不同状态；
+- 继续发展代码状态、知识库、Wiki、图谱和工作流之间的可追溯关联，而不是重复堆叠文本摘要。
 
-| 优先级 | 项目 | 说明 |
-|--------|------|------|
-| ~~P0~~ | ~~文件锁~~ | ~~✅ v0.7.11~~ |
-| ~~P1~~ | ~~自动归档~~ | ~~✅ v0.7.11~~ |
-| P1 | projectId 稳定性 | 非 Git 项目需要更好的识别策略 |
-| ~~P2~~ | ~~中文实体抽取~~ | ~~✅ v0.7.11~~ |
-| ~~P2~~ | ~~auto-relations 性能~~ | ~~✅ v0.7.11~~ |
-| P3 | Orama 持久化 | 考虑 Orama 的原生持久化而非每次重建 |
-| ~~P3~~ | ~~测试覆盖~~ | ~~✅ 753 tests, 56 files, 含 HTTP 集成测试~~ |
+### 3. 受控的多模态派生能力
+
+- 在现有资产生命周期之上评估 PDF 文本提取、音频转写、视频语义派生；
+- 每一类派生都必须有来源、成本边界、配额、删除联动和重建路径；
+- 不把“接受任意 URL / 任意文件”误宣传为完整多模态 RAG。
+
+### 4. Agent 生态与研究
+
+- 跟进受用户需求推动的集成，例如 [Qwen 自动 hooks](https://github.com/AVIDS2/memorix/issues/3) 与 [持久化 Agent 身份](https://github.com/AVIDS2/memorix/issues/49)；
+- 独立推进记忆能力的实证研究，例如[模型能力如何改变项目记忆收益与伤害边界](https://github.com/AVIDS2/memorix/issues/152)，不把研究假设当作产品已经证明的效果。
 
 ---
 
-## 历史重要事件
-
-| 日期 | 事件 |
-|------|------|
-| 2026-02-13 | Copilot Adapter 实现完成，274 测试全部通过 |
-| 2026-02-13 | Antigravity MCP 配置修复，Memorix MCP Server 首次成功运行 |
-| 2026-02-13 | 发现并修复 npx 缓存损坏问题 (MODULE_NOT_FOUND chownr) |
-| 2026-02-15 | 完成全部核心模块的深度代码审查 |
-| 2026-02-15 | 开发文档完成 (ARCHITECTURE, MODULES, DEVELOPMENT, DESIGN_DECISIONS, API_REFERENCE) |
-| 2026-02-24 | v0.7.8-0.7.10: Antigravity 兼容 + MCP roots + 中英双语文档 |
-| 2026-02-24 | v0.7.11: P0-P2 全部完成 (文件锁 + 搜索优化 + 自动归档 + 中文实体 + 性能优化 + 图谱同步) |
-| 2026-02-25 | v0.9.0-0.9.12: Hooks 系统全量修复 + 10 Agent 支持 |
-| 2026-02-28 | v0.9.25: Windsurf 兼容性修复 |
-| 2026-03-05 | v0.10.5: Antigravity/Claude Code hooks 修复 |
-| 2026-03-07 | v0.11.0: Mini-Skills + LLM 增强模式 |
-| 2026-03-09 | **v1.0.0**: 首个稳定版 — 22 工具 + 团队协作 + 自动清理 + 753 测试 |
+## 贡献与验证原则
+
+贡献会先检查三件事：是否符合当前存储/可见性/生命周期边界，是否能由 CLI 与 MCP 一致地使用，是否有可重复的测试或人工验证证据。功能方向有价值但架构已演进的 PR 会保留作者署名，并通过公开后续 Issue 延续，而不是悄悄重写或吞掉成果。
+
+历史版本、已解决问题和详细发布日期请查看 [CHANGELOG](../CHANGELOG.md)。