memorix 0.9.18 → 0.9.19

package/README.md

@@ -21,7 +21,7 @@
     <img src="https://img.shields.io/badge/Works%20with-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
   </p>
   <p align="center">
-    <a href="#-stop-re-explaining-your-project">Why</a> •
+    <a href="#%EF%B8%8F-stop-re-explaining-your-project">Why</a> •
     <a href="#-get-started-in-30-seconds">Quick Start</a> •
     <a href="#-real-world-scenarios">Scenarios</a> •
     <a href="#-what-memorix-can-do">Features</a> •
@@ -32,7 +32,7 @@
 
 ---
 
-## 😤 Stop Re-Explaining Your Project
+## ⚠️ Stop Re-Explaining Your Project
 
 Your AI assistant forgets everything when you start a new chat. You spend 10 minutes re-explaining your architecture. **Again.** And if you switch from Cursor to Claude Code? Everything is gone. **Again.**
 
@@ -167,17 +167,46 @@ No API keys. No cloud accounts. No dependencies. Works with any directory (git r
 
 > 📖 **Full setup guide for all 8 agents** → [docs/SETUP.md](docs/SETUP.md)
 
-<details>
-<summary><strong>🔧 Troubleshooting</strong></summary>
+### 🔧 Troubleshooting — MCP Connection Issues
 
-| Problem | Solution |
-|---------|----------|
-| `MCP server initialization timed out after 60 seconds` | You're using `npx`. Run `npm install -g memorix` and change config to `"command": "memorix"` |
-| `Cannot start Memorix: no valid project detected` | Your CWD is a system directory (home, Desktop, etc). Open a real project folder or set `MEMORIX_PROJECT_ROOT` |
-| `memorix: command not found` | Run `npm install -g memorix` first. Verify with `memorix --version` |
-| Parameter type errors (GLM/non-Anthropic models) | Update to v0.9.1+: `npm install -g memorix@latest` |
+> **⚠️ #1 Mistake: Do NOT manually run `memorix serve` in a terminal.**
+> MCP uses **stdio transport** — your IDE (Claude Code, Cursor, etc.) launches memorix as a subprocess automatically. Running it manually in PowerShell/Terminal does nothing for the IDE connection.
 
-</details>
+**Quick diagnostic** — run this first:
+```bash
+memorix --version       # Should print version number
+memorix serve --cwd .   # Should show "[memorix] MCP Server running on stdio"
+```
+If either fails, follow the table below:
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `memorix · ✗ failed` in IDE | IDE can't find the `memorix` command | Run `npm install -g memorix`. On Windows, **restart your IDE** after install so it picks up the new PATH |
+| `MCP server initialization timed out` | Using `npx` (downloads every time) | Switch to global install: `npm install -g memorix`, change config to `"command": "memorix"` |
+| Repeated "Reconnected to memorix" then fails | memorix process crashes on startup | Check: 1) Node.js ≥ 18 (`node -v`), 2) open a **real project folder** (not Desktop/Home), 3) set `MEMORIX_PROJECT_ROOT` in MCP config |
+| `Cannot start Memorix: no valid project detected` | CWD is a system directory | Open a project folder with code, or add `"env": { "MEMORIX_PROJECT_ROOT": "/path/to/project" }` to your MCP config |
+| `memorix: command not found` | npm global bin not in PATH | Run `npm config get prefix` to find install location, add its `bin/` to your system PATH, then restart IDE |
+| Works in terminal but not in IDE | IDE uses a different PATH than your shell | **Windows:** restart IDE after `npm install -g`. **macOS/Linux:** ensure `~/.bashrc` or `~/.zshrc` exports the npm global bin path |
+| Parameter type errors | Old version or non-Anthropic model quirks | Update: `npm install -g memorix@latest` |
+
+**Correct `.claude.json` config:**
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**❌ Wrong** — do NOT use any of these:
+```
+"command": "npx"                    ← will timeout
+"command": "npx -y memorix serve"   ← wrong format
+"command": "node memorix serve"     ← not how it works
+```
 
 ---
 
@@ -236,138 +265,33 @@ Now you want to try Kiro.
   → Kiro is ready in seconds, not hours!
 ```
 
-### Scenario 5: Auto-Generated Project Skills
-
-```
-After 2 weeks of development, you have 50+ observations:
-  - 8 gotchas about Windows path issues
-  - 5 decisions about the auth module
-  - 3 problem-solutions for database migrations
-
-  You: "Generate project skills"
-  → memorix_skills clusters observations by entity
-  → Auto-generates SKILL.md files:
-    - "auth-module-guide.md" — JWT setup, refresh flow, common pitfalls
-    - "database-migrations.md" — Prisma patterns, rollback strategies
-  → Syncs skills to any agent: Cursor, Claude Code, Kiro...
-  → New team members' AI instantly knows your project's patterns!
-```
-
-### Scenario 6: Session Lifecycle (v0.8.0)
-
-```
-Morning — Start a new session in Windsurf:
-  → memorix_session_start auto-injects:
-    📋 Previous Session: "Implemented JWT auth middleware"
-    🔴 JWT tokens expire silently (gotcha)
-    🟤 Use Docker for deployment (decision)
-  → AI instantly knows what you did yesterday!
-
-Evening — End the session:
-  → memorix_session_end saves structured summary
-  → Next session (any agent!) gets this context automatically
-```
-
-### Scenario 7: Topic Key Upsert — No More Duplicates (v0.8.0)
-
-```
-You update your architecture decision 3 times over a week:
-
-  Day 1: memorix_store(topicKey="architecture/auth-model", ...)
-  → Creates observation #42 (rev 1)
-
-  Day 3: memorix_store(topicKey="architecture/auth-model", ...)
-  → Updates #42 in-place (rev 2) — NOT a new #43!
-
-  Day 5: memorix_store(topicKey="architecture/auth-model", ...)
-  → Updates #42 again (rev 3)
-
-  Result: 1 observation with latest content, not 3 duplicates!
-```
-
 ---
 
 ## 🧠 What Memorix Can Do
 
-### Smart Memory (24 MCP Tools)
-
-| What You Say | What Memorix Does |
-|-------------|-------------------|
-| "Remember this architecture decision" | `memorix_store` — Classifies as 🟤 decision, extracts entities, creates graph relations, auto-associates session |
-| "What did we decide about auth?" | `memorix_search` → `memorix_detail` — 3-layer progressive disclosure, ~10x token savings |
-| "What auth decisions last week?" | `memorix_search` with `since`/`until` — Temporal queries with date range filtering |
-| "What happened around that bug fix?" | `memorix_timeline` — Shows chronological context before/after |
-| "Show me the knowledge graph" | `memorix_dashboard` — Opens interactive web UI with D3.js graph + sessions panel |
-| "Which memories are getting stale?" | `memorix_retention` — Exponential decay scores, identifies archive candidates |
-| "Start a new session" | `memorix_session_start` — Tracks session lifecycle, auto-injects previous session summaries + key memories |
-| "End this session" | `memorix_session_end` — Saves structured summary (Goal/Discoveries/Accomplished/Files) for next session |
-| "What did we do last session?" | `memorix_session_context` — Retrieves session history and key observations |
-| "Suggest a topic key for this" | `memorix_suggest_topic_key` — Generates stable keys for deduplication (e.g. `architecture/auth-model`) |
-| "Clean up duplicate memories" | `memorix_consolidate` — Find & merge similar observations by text similarity, preserving all facts |
-| "Export this project's memories" | `memorix_export` — JSON (importable) or Markdown (human-readable for PRs/docs) |
-| "Import memories from teammate" | `memorix_import` — Restore from JSON export, re-assigns IDs, deduplicates by topicKey |
-
-### Cross-Agent Workspace Sync
-
-| What You Say | What Memorix Does |
-|-------------|-------------------|
-| "Sync my MCP servers to Kiro" | `memorix_workspace_sync` — Migrates configs, merges (never overwrites) |
-| "Check my agent rules" | `memorix_rules_sync` — Scans 8 agents, deduplicates, detects conflicts |
-| "Generate rules for Cursor" | `memorix_rules_sync` — Cross-format conversion (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`) |
-| "Generate project skills" | `memorix_skills` — Creates SKILL.md from observation patterns |
-| "Inject the auth skill" | `memorix_skills` — Returns skill content directly into agent context |
-
-### Knowledge Graph (MCP Official Compatible)
-
-| Tool | What It Does |
-|------|-------------|
-| `create_entities` | Build your project's knowledge graph |
-| `create_relations` | Connect entities with typed edges (causes, fixes, depends_on) |
-| `add_observations` | Attach observations to entities |
-| `search_nodes` / `open_nodes` | Query the graph |
-| `read_graph` | Export full graph for visualization |
-
-> **Drop-in compatible** with [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — same API, more features.
-
-### 9 Observation Types
+### 25 MCP Tools
 
-Every memory is classified for intelligent retrieval:
+| Category | Tools | What They Do |
+|----------|-------|-------------|
+| **Store & Classify** | `memorix_store`, `memorix_suggest_topic_key` | Store memories with 9 types (🔴gotcha 🟤decision 🟡fix ...), dedup via topic keys |
+| **Search & Retrieve** | `memorix_search`, `memorix_detail`, `memorix_timeline` | 3-layer progressive disclosure (~10x token savings), temporal queries, chronological context |
+| **Sessions** | `memorix_session_start/end/context` | Auto-inject previous session context, save structured summaries |
+| **Maintenance** | `memorix_retention`, `memorix_consolidate`, `memorix_export/import` | Decay scoring, merge duplicates, backup & share |
+| **Dashboard** | `memorix_dashboard` | Interactive web UI — D3.js knowledge graph, observation browser, retention panel |
+| **Workspace Sync** | `memorix_workspace_sync`, `memorix_rules_sync`, `memorix_skills` | Migrate MCP configs across 8 agents, sync rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), auto-generate project skills |
+| **Knowledge Graph** | `create_entities`, `create_relations`, `add_observations`, `delete_entities`, `delete_observations`, `delete_relations`, `search_nodes`, `open_nodes`, `read_graph` | [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) compatible — same API, more features |
 
-| Icon | Type | When To Use |
-|------|------|-------------|
-| 🎯 | `session-request` | Original task/goal for this session |
-| 🔴 | `gotcha` | Critical pitfall — "Never do X because Y" |
-| 🟡 | `problem-solution` | Bug fix with root cause and solution |
-| 🔵 | `how-it-works` | Technical explanation of a system |
-| 🟢 | `what-changed` | Code/config change record |
-| 🟣 | `discovery` | New insight or finding |
-| 🟠 | `why-it-exists` | Rationale behind a design choice |
-| 🟤 | `decision` | Architecture/design decision |
-| ⚖️ | `trade-off` | Compromise with pros/cons |
-
-### Visual Dashboard
-
-Run `memorix_dashboard` to open a web UI at `http://localhost:3210`:
+### 9 Observation Types
 
-- **Interactive Knowledge Graph** — D3.js force-directed visualization of entities and relations
-- **Observation Browser** — Filter by type, search with highlighting, expand/collapse details
-- **Retention Panel** — See which memories are active, stale, or candidates for archival
-- **Project Switcher** — View any project's data without switching IDEs
-- **Batch Cleanup** — Auto-detect and bulk-delete low-quality observations
-- **Light/Dark Theme** — Premium glassmorphism design, bilingual (EN/中文)
+Every memory is classified: 🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
 
 ### Auto-Memory Hooks
 
-Memorix can **automatically capture** decisions, errors, and gotchas from your coding sessions:
-
 ```bash
 memorix hooks install    # One-command setup
 ```
 
-- **Implicit Memory** — Detects patterns like "I decided to...", "The bug was caused by...", "Never use X"
-- **Session Start Injection** — Loads recent high-value memories into agent context automatically
-- **Multi-Language** — English + Chinese keyword matching
-- **Smart Filtering** — 30s cooldown, skips trivial commands (ls, cat, pwd)
+Automatically captures decisions, errors, and gotchas from your coding sessions. Detects patterns in English + Chinese, injects high-value memories at session start, with smart filtering (30s cooldown, skips trivial commands).
 
 ---
 
@@ -375,7 +299,7 @@ memorix hooks install    # One-command setup
 
 | | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | [claude-mem](https://github.com/anthropics/claude-code) | **Memorix** |
 |---|---|---|---|---|
-| **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **7 IDEs (MCP)** |
+| **Agents supported** | SDK-based | 13+ (MCP) | Claude Code only | **8 agents (MCP)** |
 | **Cross-agent sync** | No | No | No | **Yes (configs, rules, skills, workflows)** |
 | **Rules sync** | No | No | No | **Yes (7 formats)** |
 | **Skills engine** | No | No | No | **Yes (auto-generated from memory)** |
@@ -387,7 +311,7 @@ memorix hooks install    # One-command setup
 | **Visual dashboard** | Cloud UI | Yes | No | **Yes (web UI + D3.js graph)** |
 | **Privacy** | Cloud | Local | Local | **100% Local** |
 | **Cost** | Per-call API | $0 | $0 | **$0** |
-| **Install** | `pip install` | `pip install` | Built into Claude | **`npx memorix serve`** |
+| **Install** | `pip install` | `pip install` | Built into Claude | **`npm i -g memorix`** |
 
 **Memorix is the only tool that bridges memory AND workspace across agents.**
 
@@ -413,9 +337,9 @@ With vector search, queries like "authentication" also match memories about "log
 
 - **Auto-detected** — Project identity from `git remote` URL, zero config needed
 - **MCP roots fallback** — If `cwd` is not a project (e.g., Antigravity), Memorix tries the [MCP roots protocol](https://modelcontextprotocol.io/docs/concepts/roots) to get your workspace path from the IDE
-- **Per-project storage** — `~/.memorix/data/<owner--repo>/` per project
+- **Shared storage, metadata isolation** — All data lives in `~/.memorix/data/`, with `projectId` embedded in each observation. This ensures cross-IDE sharing works even when different IDEs detect different project IDs for the same repo
 - **Scoped search** — Defaults to current project; `scope: "global"` to search all
-- **Zero cross-contamination** — Project A's decisions never leak into project B
+- **Zero cross-contamination** — Search results are filtered by project ID; project A's decisions never appear in project B's searches
 
 **Detection priority:** `--cwd` → `MEMORIX_PROJECT_ROOT` → `INIT_CWD` → `process.cwd()` → MCP roots → error
 
@@ -436,7 +360,7 @@ Run `memorix_workspace_sync` with action `"migrate"` and your target IDE. It sca
 Memorix workspace sync migrates MCP configs, agent rules (`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`), skills, and workflows. One command, seconds to complete.
 
 **Is there an MCP server for persistent AI coding memory?**
-Yes — Memorix is a cross-agent memory MCP server supporting 7 IDEs with knowledge graph, 3-layer progressive disclosure search, workspace sync, and auto-generated project skills.
+Yes — Memorix is a cross-agent memory MCP server supporting 8 agents with knowledge graph, 3-layer progressive disclosure search, workspace sync, and auto-generated project skills.
 
 **How is this different from mcp-memory-service?**
 Both are great memory servers. Memorix adds: cross-agent workspace sync (MCP configs, rules, skills), auto-generated project skills from memory patterns, 3-layer token-efficient search, and session-start memory injection hooks.
@@ -456,7 +380,7 @@ cd memorix
 npm install
 
 npm run dev          # tsup watch mode
-npm test             # vitest (422 tests)
+npm test             # vitest (509 tests)
 npm run lint         # TypeScript type check
 npm run build        # Production build
 ```

package/README.zh-CN.md

@@ -21,7 +21,7 @@
     <img src="https://img.shields.io/badge/Works%20with-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
   </p>
   <p align="center">
-    <a href="#-别再反复解释你的项目了">痛点</a> •
+    <a href="#%EF%B8%8F-别再反复解释你的项目了">痛点</a> •
     <a href="#-30-秒快速开始">快速开始</a> •
     <a href="#-真实使用场景">场景</a> •
     <a href="#-memorix-能做什么">功能</a> •
@@ -32,7 +32,7 @@
 
 ---
 
-## 😤 别再反复解释你的项目了
+## ⚠️ 别再反复解释你的项目了
 
 你的 AI 助手每次新对话都会忘记一切。你要花 10 分钟重新解释架构。**又一次。** 如果从 Cursor 切到 Claude Code？所有上下文全部丢失。**又一次。**
 
@@ -167,17 +167,46 @@ claude mcp add memorix -- memorix serve
 
 > 📖 **8 个 Agent 的完整配置指南** → [docs/SETUP.md](docs/SETUP.md)
 
-<details>
-<summary><strong>🔧 常见问题</strong></summary>
+### 🔧 常见问题 — MCP 连接失败
 
-| 问题 | 解决方案 |
-|------|----------|
-| `MCP server initialization timed out after 60 seconds` | 你在用 `npx`。执行 `npm install -g memorix`，然后把配置改成 `"command": "memorix"` |
-| `Cannot start Memorix: no valid project detected` | 你的工作目录是系统目录（主目录、桌面等）。打开一个真正的项目文件夹，或设置 `MEMORIX_PROJECT_ROOT` |
-| `memorix: command not found` | 先执行 `npm install -g memorix`，用 `memorix --version` 验证 |
-| 参数类型错误（GLM/非 Anthropic 模型） | 更新到 v0.9.1+：`npm install -g memorix@latest` |
+> **⚠️ 最常见的错误：不要在终端手动运行 `memorix serve`！**
+> MCP 使用 **stdio 传输** — 你的 IDE（Claude Code、Cursor 等）会自动启动 memorix 子进程。在 PowerShell/终端里手动运行对 IDE 连接毫无帮助。
 
-</details>
+**快速诊断** — 先在终端跑这两条命令：
+```bash
+memorix --version       # 应该输出版本号
+memorix serve --cwd .   # 应该显示 "[memorix] MCP Server running on stdio"
+```
+如果任何一条失败，参考下表：
+
+| 症状 | 原因 | 解决方案 |
+|------|------|----------|
+| IDE 里显示 `memorix · ✗ failed` | IDE 找不到 `memorix` 命令 | 执行 `npm install -g memorix`。Windows 用户安装后**必须重启 IDE** 才能识别新的 PATH |
+| `MCP server initialization timed out` | 使用了 `npx`（每次都重新下载） | 改用全局安装：`npm install -g memorix`，配置改成 `"command": "memorix"` |
+| 反复出现 "Reconnected to memorix" 最终失败 | memorix 进程启动后崩溃 | 检查：1) Node.js ≥ 18（`node -v`），2) 打开**真正的项目文件夹**（不是桌面/主目录），3) 在 MCP 配置中设置 `MEMORIX_PROJECT_ROOT` |
+| `Cannot start Memorix: no valid project detected` | 工作目录是系统目录 | 打开包含代码的项目文件夹，或在 MCP 配置中添加 `"env": { "MEMORIX_PROJECT_ROOT": "/项目路径" }` |
+| `memorix: command not found` | npm 全局安装目录不在 PATH 中 | 执行 `npm config get prefix` 查看安装位置，将其 `bin/` 加入系统 PATH，然后重启 IDE |
+| 终端里能用但 IDE 里不行 | IDE 使用的 PATH 和终端不同 | **Windows：** 安装后重启 IDE。**macOS/Linux：** 确保 `~/.bashrc` 或 `~/.zshrc` 导出了 npm 全局 bin 路径 |
+| 参数类型错误 | 版本过旧或非 Anthropic 模型的兼容问题 | 更新：`npm install -g memorix@latest` |
+
+**正确的 `.claude.json` 配置：**
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**❌ 错误写法** — 不要用这些：
+```
+"command": "npx"                    ← 会超时
+"command": "npx -y memorix serve"   ← 格式错误
+"command": "node memorix serve"     ← 不是这样用的
+```
 
 ---
 
@@ -236,138 +265,33 @@ claude mcp add memorix -- memorix serve
   → Kiro 几秒内就绑定好了，不用花几个小时！
 ```
 
-### 场景 5：自动生成项目技能
-
-```
-开发两周后，你有了 50+ 条观察记录：
-  - 8 个关于 Windows 路径问题的 gotcha
-  - 5 个关于认证模块的决策
-  - 3 个数据库迁移的问题-解决方案
-
-  你: "生成项目技能"
-  → memorix_skills 按实体聚类观察记录
-  → 自动生成 SKILL.md 文件：
-    - "auth-module-guide.md" — JWT 设置、刷新流程、常见陷阱
-    - "database-migrations.md" — Prisma 模式、回滚策略
-  → 同步技能到任何 Agent：Cursor、Claude Code、Kiro...
-  → 新同事的 AI 立即掌握你项目的最佳实践！
-```
-
-### 场景 6：会话生命周期（v0.8.0）
-
-```
-早上 — 在 Windsurf 中开始新会话：
-  → memorix_session_start 自动注入：
-    📋 上次会话: "实现了 JWT 认证中间件"
-    🔴 JWT token 静默过期（踩坑）
-    🟤 使用 Docker 部署（决策）
-  → AI 立即知道你昨天做了什么！
-
-晚上 — 结束会话：
-  → memorix_session_end 保存结构化摘要
-  → 下次会话（任何 Agent！）自动获取这些上下文
-```
-
-### 场景 7：Topic Key 去重 — 不再有重复记忆（v0.8.0）
-
-```
-你在一周内更新了 3 次架构决策：
-
-  第 1 天: memorix_store(topicKey="architecture/auth-model", ...)
-  → 创建观察记录 #42（rev 1）
-
-  第 3 天: memorix_store(topicKey="architecture/auth-model", ...)
-  → 原地更新 #42（rev 2）— 不是新建 #43！
-
-  第 5 天: memorix_store(topicKey="architecture/auth-model", ...)
-  → 再次更新 #42（rev 3）
-
-  结果：1 条记录包含最新内容，而不是 3 条重复！
-```
-
 ---
 
 ## 🧠 Memorix 能做什么
 
-### 智能记忆（24 个 MCP 工具）
-
-| 你说的 | Memorix 做的 |
-|--------|-------------|
-| "记住这个架构决策" | `memorix_store` — 分类为 🟤 决策，提取实体，创建图关系，自动关联会话 |
-| "我们之前关于认证决定了什么？" | `memorix_search` → `memorix_detail` — 3 层渐进式展示，节省约 10 倍 token |
-| "上周关于认证的决策？" | `memorix_search` + `since`/`until` — 时序查询，按日期范围过滤 |
-| "那个 bug 修复前后发生了什么？" | `memorix_timeline` — 按时间显示前后上下文 |
-| "显示知识图谱" | `memorix_dashboard` — 打开交互式 Web UI，含 D3.js 图谱 + 会话面板 |
-| "哪些记忆快过期了？" | `memorix_retention` — 指数衰减评分，识别归档候选 |
-| "开始新会话" | `memorix_session_start` — 跟踪会话生命周期，自动注入上次会话摘要 + 关键记忆 |
-| "结束这次会话" | `memorix_session_end` — 保存结构化摘要（目标/发现/完成/文件），供下次会话使用 |
-| "上次我们做了什么？" | `memorix_session_context` — 检索会话历史和关键观察记录 |
-| "给这个建议一个 topic key" | `memorix_suggest_topic_key` — 生成稳定的去重键（如 `architecture/auth-model`） |
-| "清理重复记忆" | `memorix_consolidate` — 按文本相似度查找并合并相似观察记录，保留所有事实 |
-| "导出这个项目的记忆" | `memorix_export` — JSON（可导入）或 Markdown（人类可读，适合 PR/文档） |
-| "导入队友的记忆" | `memorix_import` — 从 JSON 导出恢复，重新分配 ID，按 topicKey 去重 |
-
-### 跨 Agent 工作区同步
-
-| 你说的 | Memorix 做的 |
-|--------|-------------|
-| "把 MCP 服务器同步到 Kiro" | `memorix_workspace_sync` — 迁移配置，合并（永不覆盖） |
-| "检查我的 Agent 规则" | `memorix_rules_sync` — 扫描 7 个 Agent，去重，检测冲突 |
-| "为 Cursor 生成规则" | `memorix_rules_sync` — 跨格式转换（`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`） |
-| "生成项目技能" | `memorix_skills` — 从观察模式创建 SKILL.md |
-| "注入认证技能" | `memorix_skills` — 将技能内容直接返回到 Agent 上下文 |
-
-### 知识图谱（兼容 MCP 官方接口）
-
-| 工具 | 功能 |
-|------|-----|
-| `create_entities` | 构建项目知识图谱 |
-| `create_relations` | 用类型化边连接实体（causes、fixes、depends_on） |
-| `add_observations` | 将观察附加到实体 |
-| `search_nodes` / `open_nodes` | 查询图谱 |
-| `read_graph` | 导出完整图谱用于可视化 |
-
-> **即插即用**，兼容 [MCP 官方 Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — 相同 API，更多功能。
-
-### 9 种观察类型
+### 25 个 MCP 工具
 
-每条记忆都有分类标签，用于智能检索：
+| 类别 | 工具 | 功能 |
+|------|------|------|
+| **存储与分类** | `memorix_store`, `memorix_suggest_topic_key` | 存储记忆，9 种类型（🔴踩坑 🟤决策 🟡修复 ...），通过 topic key 去重 |
+| **搜索与检索** | `memorix_search`, `memorix_detail`, `memorix_timeline` | 3 层渐进式展示（节省约 10 倍 token），时序查询，时间线上下文 |
+| **会话管理** | `memorix_session_start/end/context` | 自动注入上次会话上下文，保存结构化摘要 |
+| **维护** | `memorix_retention`, `memorix_consolidate`, `memorix_export/import` | 衰减评分，合并重复，备份与共享 |
+| **可视化** | `memorix_dashboard` | 交互式 Web UI — D3.js 知识图谱、观察浏览器、衰减面板 |
+| **工作区同步** | `memorix_workspace_sync`, `memorix_rules_sync`, `memorix_skills` | 跨 8 个 Agent 迁移 MCP 配置，同步规则（`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`），自动生成项目技能 |
+| **知识图谱** | `create_entities`, `create_relations`, `add_observations`, `delete_entities`, `delete_observations`, `delete_relations`, `search_nodes`, `open_nodes`, `read_graph` | 兼容 [MCP 官方 Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — 相同 API，更多功能 |
 
-| 图标 | 类型 | 使用场景 |
-|------|------|---------|
-| 🎯 | `session-request` | 本次会话的原始任务/目标 |
-| 🔴 | `gotcha` | 关键陷阱 — "永远不要做 X，因为 Y" |
-| 🟡 | `problem-solution` | bug 修复，含根因和解决方案 |
-| 🔵 | `how-it-works` | 系统的技术解释 |
-| 🟢 | `what-changed` | 代码/配置变更记录 |
-| 🟣 | `discovery` | 新的洞见或发现 |
-| 🟠 | `why-it-exists` | 设计选择背后的原因 |
-| 🟤 | `decision` | 架构/设计决策 |
-| ⚖️ | `trade-off` | 取舍权衡，含利弊分析 |
-
-### 可视化 Dashboard
-
-运行 `memorix_dashboard` 在 `http://localhost:3210` 打开 Web UI：
+### 9 种观察类型
 
-- **交互式知识图谱** — D3.js 力导向图，可视化实体和关系
-- **观察浏览器** — 按类型筛选，高亮搜索，展开/折叠详情
-- **记忆衰减面板** — 查看哪些记忆活跃、过期或待归档
-- **项目切换器** — 无需切换 IDE 即可查看任何项目的数据
-- **批量清理** — 自动检测并批量删除低质量观察
-- **明暗主题** — 玻璃拟态设计，中英双语界面
+每条记忆都有分类标签：🎯 session-request · 🔴 gotcha · 🟡 problem-solution · 🔵 how-it-works · 🟢 what-changed · 🟣 discovery · 🟠 why-it-exists · 🟤 decision · ⚖️ trade-off
 
 ### 自动记忆 Hook
 
-Memorix 可以**自动捕获**编码会话中的决策、错误和踩坑经验：
-
 ```bash
 memorix hooks install    # 一条命令安装
 ```
 
-- **隐式记忆** — 检测 "I decided to..."、"bug 是因为..."、"永远不要用 X" 等模式
-- **会话启动注入** — 自动将近期高价值记忆加载到 Agent 上下文
-- **多语言** — 支持英文 + 中文关键词匹配
-- **智能过滤** — 30 秒冷却，跳过无关命令（ls、cat、pwd）
+自动捕获编码会话中的决策、错误和踩坑经验。支持中英文模式检测，会话启动时自动注入高价值记忆，智能过滤（30 秒冷却，跳过无关命令）。
 
 ---
 
@@ -375,7 +299,7 @@ memorix hooks install    # 一条命令安装
 
 | | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | [claude-mem](https://github.com/anthropics/claude-code) | **Memorix** |
 |---|---|---|---|---|
-| **支持的 Agent** | SDK 集成 | 13+（MCP） | 仅 Claude Code | **7 个 IDE（MCP）** |
+| **支持的 Agent** | SDK 集成 | 13+（MCP） | 仅 Claude Code | **8 个 Agent（MCP）** |
 | **跨 Agent 同步** | 否 | 否 | 否 | **是（配置、规则、技能、工作流）** |
 | **规则同步** | 否 | 否 | 否 | **是（7 种格式）** |
 | **技能引擎** | 否 | 否 | 否 | **是（从记忆自动生成）** |
@@ -387,7 +311,7 @@ memorix hooks install    # 一条命令安装
 | **可视化面板** | 云端 UI | 是 | 否 | **是（Web UI + D3.js 图谱）** |
 | **隐私** | 云端 | 本地 | 本地 | **100% 本地** |
 | **费用** | 按量付费 | $0 | $0 | **$0** |
-| **安装** | `pip install` | `pip install` | 内置于 Claude | **`npx memorix serve`** |
+| **安装** | `pip install` | `pip install` | 内置于 Claude | **`npm i -g memorix`** |
 
 **Memorix 是唯一同时桥接记忆和工作区跨 Agent 共享的工具。**
 
@@ -413,9 +337,9 @@ npm install -g @huggingface/transformers
 
 - **自动检测** — 通过 `git remote` URL 识别项目，零配置
 - **MCP roots 回退** — 如果 `cwd` 不是项目目录（如 Antigravity），Memorix 会尝试 [MCP roots 协议](https://modelcontextprotocol.io/docs/concepts/roots) 从 IDE 获取工作区路径
-- **按项目存储** — `~/.memorix/data/<owner--repo>/` 每个项目独立
+- **统一存储，元数据隔离** — 所有数据存储在 `~/.memorix/data/`，每条观察记录内嵌 `projectId`。这样即使不同 IDE 对同一仓库检测出不同的项目 ID，跨 IDE 共享也能正常工作
 - **作用域搜索** — 默认搜索当前项目；`scope: "global"` 搜索所有项目
-- **零交叉污染** — 项目 A 的决策永远不会泄漏到项目 B
+- **零交叉污染** — 搜索结果按项目 ID 过滤，项目 A 的决策不会出现在项目 B 的搜索结果中
 
 **检测优先级：** `--cwd` → `MEMORIX_PROJECT_ROOT` → `INIT_CWD` → `process.cwd()` → MCP roots → 报错
 
@@ -436,7 +360,7 @@ npm install -g @huggingface/transformers
 Memorix 工作区同步可以迁移 MCP 配置、Agent 规则（`.mdc` ↔ `CLAUDE.md` ↔ `.kiro/steering/`）、技能和工作流。一条命令，几秒完成。
 
 **有没有用于持久 AI 编码记忆的 MCP 服务器？**
-有 — Memorix 是一个跨 Agent 记忆 MCP 服务器，支持 7 个 IDE，提供知识图谱、3 层渐进式搜索、工作区同步和自动生成项目技能。
+有 — Memorix 是一个跨 Agent 记忆 MCP 服务器，支持 8 个 Agent，提供知识图谱、3 层渐进式搜索、工作区同步和自动生成项目技能。
 
 **和 mcp-memory-service 有什么区别？**
 两个都是优秀的记忆服务器。Memorix 额外提供：跨 Agent 工作区同步（MCP 配置、规则、技能）、从记忆模式自动生成项目技能、3 层 token 高效搜索、会话启动记忆注入 Hook。
@@ -456,7 +380,7 @@ cd memorix
 npm install
 
 npm run dev          # tsup 监听模式
-npm test             # vitest（422 个测试）
+npm test             # vitest（509 个测试）
 npm run lint         # TypeScript 类型检查
 npm run build        # 生产构建
 ```