memorix 1.0.4 → 1.0.6

package/README.zh-CN.md

@@ -5,8 +5,8 @@
 <h1 align="center">Memorix</h1>
 
 <p align="center">
-  <strong>面向 AI 编码 Agent 的本地优先记忆平台。</strong><br>
-  将 Git 真相、推理记忆和跨 Agent 召回统一到一个 MCP 服务器中。
+  <strong>面向 Coding Agent 的开源跨 Agent Memory Layer。</strong><br>
+  通过 MCP 兼容 Cursor、Claude Code、Codex、Windsurf、Gemini CLI、GitHub Copilot、Kiro、OpenCode、Antigravity 和 Trae。
 </p>
 
 <p align="center">
@@ -18,29 +18,62 @@
 </p>
 
 <p align="center">
-  <strong>Git Memory</strong> · <strong>Reasoning Memory</strong> · <strong>跨 Agent 召回</strong> · <strong>控制台仪表盘</strong>
+  <strong>Git Memory</strong> | <strong>Reasoning Memory</strong> | <strong>跨 Agent 召回</strong> | <strong>Control Plane Dashboard</strong>
 </p>
 
 <p align="center">
-  <a href="README.md">English</a> ·
-  <a href="#快速开始">快速开始</a> ·
-  <a href="#工作原理">工作原理</a> ·
-  <a href="#文档导航">文档导航</a> ·
-  <a href="docs/SETUP.md">配置指南</a>
+  <a href="README.md">English</a> |
+  <a href="#快速开始">快速开始</a> |
+  <a href="#支持的客户端">支持的客户端</a> |
+  <a href="#核心工作流">核心工作流</a> |
+  <a href="#文档导航">文档导航</a> |
+  <a href="docs/SETUP.md">安装与接入</a>
 </p>
 
 ---
 
+## 给 Coding Agent 的说明
+
+如果你在用 AI coding agent 帮用户安装、配置或排障 Memorix，请先读 [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md)。
+
+这份文档是给 agent 的正式操作手册，重点说明：
+
+- 安装与运行模式选择
+- Git 与项目绑定规则
+- stdio 与 HTTP control plane 的区别
+- 各 IDE / Agent 的集成和 hooks
+- dot 目录按需生成策略
+- 排障顺序和安全操作边界
+
 ## 为什么是 Memorix
 
-大多数 AI 编码 Agent 只能记住当前对话。Memorix 提供跨 IDE、跨会话、跨 Agent 的共享持久化记忆层，让工程上下文真正沉淀下来。
+大多数 Coding Agent 只记得当前线程。Memorix 提供的是一层共享、持久、可检索的项目记忆，让不同 IDE、不同 Agent、不同会话都能在同一套本地记忆库上继续工作。
+
+Memorix 的几个关键差异点：
+
+- **Git Memory**：把 `git commit` 变成可检索的工程记忆，保留提交来源、变更文件和噪音过滤结果。
+- **Reasoning Memory**：不只记录“改了什么”，还记录“为什么这么做”。
+- **跨 Agent 本地召回**：多个 IDE 和 Agent 可以读取同一套本地记忆，而不是各自形成孤岛。
+- **记忆质量管线**：formation、压缩、保留衰减和 source-aware retrieval 协同工作，而不是一堆彼此独立的小功能。
+
+一句话说，Memorix 解决的是：让多个 Coding Agent 通过 MCP 共享同一套耐久项目记忆，同时保留 Git 真相、推理上下文和本地控制权。
 
-Memorix 的差异化主要在这几条线：
+## 支持的客户端
 
-- **Git Memory**：把 `git commit` 转成带来源、可检索、可过滤噪音的工程记忆。
-- **Reasoning Memory**：不仅记录“改了什么”，还能记录“为什么这样做”。
-- **跨 Agent 本地召回**：Cursor、Windsurf、Claude Code、Codex、Copilot、Kiro、OpenCode、Gemini CLI 等都可以读写同一套本地记忆。
-- **质量治理管线**：Formation、写入压缩、保留衰减、source-aware retrieval 协同工作，而不是一堆孤立工具。
+当前已经做了明确适配的集成目标有：
+
+- Cursor
+- Claude Code
+- Codex
+- Windsurf
+- Gemini CLI
+- GitHub Copilot
+- Kiro
+- OpenCode
+- Antigravity
+- Trae
+
+如果某个客户端能通过 MCP 连接本地命令或 HTTP 端点，通常也可以接入 Memorix，只是暂时没有单独的适配器或引导页。
 
 ---
 
@@ -52,35 +85,92 @@ Memorix 的差异化主要在这几条线：
 npm install -g memorix
 ```
 
-初始化项目配置：
+初始化 Memorix 配置：
 
 ```bash
 memorix init
 ```
 
-Memorix 采用“两类文件、两种职责”：
+`memorix init` 会让你在 `Global defaults` 和 `Project config` 之间选择作用域。
+
+Memorix 使用两类文件：
+
+- `memorix.yml`：行为配置和项目设置
+- `.env`：API key 等 secrets
+
+然后按你的目标选择一条最顺手的路径：
+
+| 你想做什么 | 运行命令 | 适合场景 |
+| --- | --- | --- |
+| 先把 Memorix 快速接到一个 IDE 里 | `memorix serve` | Cursor、Claude Code、Codex、Windsurf、Gemini CLI 等 stdio MCP 客户端 |
+| 在后台长期运行 HTTP MCP + Dashboard | `memorix background start` | 日常使用、多 Agent、协作、dashboard |
+| 把 HTTP 模式放在前台调试或自定义端口 | `memorix serve-http --port 3211` | 调试、手动观察日志、自定义启动方式 |
+
+对大多数用户来说，先从下面两条里选一条就够了：
 
-- `memorix.yml`：行为配置、项目策略
-- `.env`：密钥和敏感端点
+- `memorix serve`：你只想尽快在 IDE 里用起来
+- `memorix background start`：你想要 dashboard 和后台常驻的 HTTP control plane
 
-选择一种运行模式：
+可选的本地交互式界面：
 
 ```bash
-memorix serve
+memorix
 ```
 
-`serve` 用于标准的 stdio MCP 集成。
+只有在你确实想在 TTY 里直接使用本地 workbench 时，才需要运行裸命令 `memorix`。对大多数用户来说，它不是主安装路径。
+
+配套命令：
+
+```bash
+memorix background status
+memorix background logs
+memorix background stop
+```
+
+如果你确实需要把 HTTP control plane 放在前台运行、做调试、手动观察日志或使用自定义端口，再用：
 
 ```bash
 memorix serve-http --port 3211
 ```
 
-`serve-http` 用于 HTTP transport、团队协作，以及与之共端口的 dashboard。
+如果你在多个工作区或多个 Agent 之间共享 HTTP control plane，请让每个 session 都在开始时调用 `memorix_session_start(projectRoot=...)`。
+
+更细的启动根路径选择、项目绑定、配置优先级和 agent 操作说明，放在 [docs/SETUP.md](docs/SETUP.md) 和 [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md) 里。
+
+把 Memorix 加进你的 MCP 客户端：
+
+### 通用 stdio MCP 配置
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### 通用 HTTP MCP 配置
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+如果你用的是 HTTP control plane，并且会跨多个工作区或多个 Agent 共享，请确保客户端或 agent 在每个项目 session 开始时调用 `memorix_session_start(projectRoot=绝对工作区路径)`。
 
-把 Memorix 加入 MCP 配置：
+下面这些客户端示例展示的是最简单的 stdio 形态。如果你更想使用共享的 HTTP control plane，请沿用上面的通用 HTTP 配置块，并到 [docs/SETUP.md](docs/SETUP.md) 查看各客户端字段差异。
 
 <details open>
-<summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
+<summary><strong>Cursor</strong> | <code>.cursor/mcp.json</code></summary>
 
 ```json
 {
@@ -103,7 +193,7 @@ claude mcp add memorix -- memorix serve
 </details>
 
 <details>
-<summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
+<summary><strong>Codex</strong> | <code>~/.codex/config.toml</code></summary>
 
 ```toml
 [mcp_servers.memorix]
@@ -112,13 +202,13 @@ args = ["serve"]
 ```
 </details>
 
-完整 IDE 配置矩阵、Windows 注意事项和排障请看 [docs/SETUP.md](docs/SETUP.md)。
+完整 IDE 配置矩阵、Windows 注意事项和排障说明见 [docs/SETUP.md](docs/SETUP.md)。
 
 ---
 
 ## 核心工作流
 
-### 1. 存储并检索项目记忆
+### 1. 存储与检索项目记忆
 
 常用 MCP 工具包括：
 
@@ -128,9 +218,9 @@ args = ["serve"]
 - `memorix_timeline`
 - `memorix_resolve`
 
-这条主链适合沉淀决策、踩坑、问题修复、会话交接等上下文。
+这条主链适合沉淀决策、坑点、问题修复和会话交接。
 
-### 2. 自动捕获 Git 工程真相
+### 2. 自动捕获 Git 真相
 
 安装 post-commit hook：
 
@@ -138,19 +228,19 @@ args = ["serve"]
 memorix git-hook --force
 ```
 
-也可以手动导入：
+或者手动导入：
 
 ```bash
 memorix ingest commit
 memorix ingest log --count 20
 ```
 
-Git Memory 会带上 `source='git'`、commit hash、文件列表，以及噪音过滤结果。
+Git Memory 会保留 `source='git'`、提交哈希、文件变更和噪音过滤结果。
 
-### 3. 运行控制台与协作入口
+### 3. 运行控制面与 Dashboard
 
 ```bash
-memorix serve-http --port 3211
+memorix background start
 ```
 
 然后访问：
@@ -158,38 +248,114 @@ memorix serve-http --port 3211
 - MCP HTTP 端点：`http://localhost:3211/mcp`
 - Dashboard：`http://localhost:3211`
 
-这个模式会把 dashboard、团队协作、配置诊断、项目身份健康度等能力统一到同一个入口。
+配套命令：
+
+```bash
+memorix background status
+memorix background logs
+memorix background stop
+```
+
+如果你需要把控制面放在前台做调试或手动观察，也可以使用：
+
+```bash
+memorix serve-http --port 3211
+```
+
+这一模式会把 dashboard、配置诊断、项目身份、团队协作和 Git Memory 视图统一到一个控制面入口里。
+
+当多个 HTTP session 同时存在时，每个 session 都应先用 `memorix_session_start(projectRoot=...)` 显式绑定当前工作区，再去调用项目级记忆工具。
 
 ---
 
 ## 工作原理
 
 ```mermaid
-graph TB
-    A["git commit / agent 工具调用 / 手动存储"] --> B["Memorix Runtime"]
-    B --> C["Observation / Reasoning / Git Memory"]
-    C --> D["Formation + Indexing + Graph + Retention"]
-    D --> E["Search / Detail / Timeline / Dashboard / Team"]
+flowchart LR
+    subgraph Ingress["入口层"]
+        A1["Git hooks / ingest"]
+        A2["MCP tools"]
+        A3["CLI / TUI"]
+        A4["HTTP dashboard"]
+    end
+
+    subgraph Runtime["Memorix Runtime"]
+        B1["stdio MCP server"]
+        B2["HTTP control plane"]
+        B3["project binding + config"]
+    end
+
+    subgraph Memory["记忆基底"]
+        C1["Observation memory"]
+        C2["Reasoning memory"]
+        C3["Git memory"]
+        C4["Session + team state"]
+    end
+
+    subgraph Processing["异步处理"]
+        D1["Formation pipeline"]
+        D2["Embedding + indexing"]
+        D3["Graph linking"]
+        D4["Dedup + retention"]
+    end
+
+    subgraph Consumption["消费面"]
+        E1["Search / detail / timeline"]
+        E2["Dashboard / team views"]
+        E3["Agent recall / handoff"]
+    end
+
+    A1 --> B1
+    A2 --> B1
+    A2 --> B2
+    A3 --> B1
+    A3 --> B2
+    A4 --> B2
+
+    B1 --> B3
+    B2 --> B3
+
+    B3 --> C1
+    B3 --> C2
+    B3 --> C3
+    B3 --> C4
+
+    C1 --> D1
+    C1 --> D2
+    C1 --> D3
+    C1 --> D4
+    C2 --> D1
+    C2 --> D3
+    C3 --> D2
+    C4 --> D3
+
+    D1 --> E1
+    D2 --> E1
+    D3 --> E2
+    D4 --> E3
+    C4 --> E3
 ```
 
-### 三层记忆模型
+Memorix 不是一条单线流水线。它从多个入口接收记忆，把内容落到多种记忆基底上，经过异步质量与索引处理，再通过不同的检索和协作界面提供给用户与 agent。
+
+### 记忆层
 
-- **Observation Memory**：记录 what-changed、how-it-works、gotcha、problem-solution 等工程知识
-- **Reasoning Memory**：记录决策理由、备选方案、权衡、风险
-- **Git Memory**：从 commit 提取的不可变工程事实
+- **Observation Memory**：记录“改了什么 / 系统怎么工作 / 踩过什么坑”
+- **Reasoning Memory**：记录“为什么这么做 / 替代方案 / 权衡 / 风险”
+- **Git Memory**：记录从提交中提炼出的工程事实
 
 ### 检索模型
 
-- 默认搜索是**当前项目隔离**
-- `scope="global"` 才会跨项目搜索
-- 全局结果可通过带 `projectId` 的 refs 精确打开详情
-- source-aware retrieval 会根据问题类型动态提升 Git 或 reasoning memory 的权重
+- 默认搜索是**当前项目作用域**
+- `scope="global"` 可以跨项目搜索
+- 全局结果可通过带项目信息的 ref 再展开
+- source-aware retrieval 会对“发生了什么”问题偏向 Git Memory，对“为什么”问题偏向 reasoning memory
 
 ---
 
 ## 文档导航
 
-### 上手与配置
+### 入门
 
 - [Setup Guide](docs/SETUP.md)
 - [Configuration Guide](docs/CONFIGURATION.md)
@@ -200,7 +366,7 @@ graph TB
 - [Memory Formation Pipeline](docs/MEMORY_FORMATION_PIPELINE.md)
 - [Design Decisions](docs/DESIGN_DECISIONS.md)
 
-### 参考文档
+### 参考资料
 
 - [API Reference](docs/API_REFERENCE.md)
 - [Git Memory Guide](docs/GIT_MEMORY.md)
@@ -211,8 +377,10 @@ graph TB
 - [Development Guide](docs/DEVELOPMENT.md)
 - [Known Issues and Roadmap](docs/KNOWN_ISSUES_AND_ROADMAP.md)
 
-### 面向 AI 的项目文档
+### AI / Agent 文档
 
+- [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md)
+- [AI Context Note](docs/AI_CONTEXT.md)
 - [`llms.txt`](llms.txt)
 - [`llms-full.txt`](llms-full.txt)
 
@@ -235,17 +403,18 @@ npm run build
 ```bash
 memorix status
 memorix dashboard
+memorix background start
 memorix serve-http --port 3211
 memorix git-hook --force
 ```
 
 ---
 
-## 致谢
+## 鸣谢
 
-Memorix 借鉴了 [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)、[MemCP](https://github.com/maydali28/memcp)、[claude-mem](https://github.com/anthropics/claude-code)、[Mem0](https://github.com/mem0ai/mem0) 以及更广义 MCP 生态中的许多思路。
+Memorix 借鉴了 [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)、[MemCP](https://github.com/maydali28/memcp)、[claude-mem](https://github.com/anthropics/claude-code)、[Mem0](https://github.com/mem0ai/mem0) 和整个 MCP 生态中的许多思路。
 
-## Star History
+## Star 历史
 
 <a href="https://star-history.com/#AVIDS2/memorix&Date">
  <picture>