@pcircle/memesh 4.0.2 → 4.1.0

package/README.zh-CN.md

@@ -1,10 +1,13 @@
+<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
+<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
+
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>最轻量的通用 AI 记忆层。</strong><br />
-    一个 SQLite 文件。任何 LLM。零云端依赖。
+    <strong>为 Claude Code 和 MCP 编码代理设计的本地内存层。</strong><br />
+    一个 SQLite 文件。无需 Docker。无需云服务。
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
@@ -16,15 +19,17 @@
 
 ---
 
-## 问题所在
+## 问题
+
+编码代理在会话间会遗忘。每个架构决策、每次 bug 修复、失败的测试用例、每一次来之不易的经验教训都需要重新解释一遍。Claude Code 每次都从零开始，重新发现老约束，浪费上下文在早该掌握的东西上。
 
-你的 AI 在每次对话结束后都会忘记一切。每一个决策、每一次修复、每一个学到的教训——全部归零。你不断重新解释相同的背景，Claude 反复重新发现相同的模式，而你的 AI 知识库每次都从零开始。
+**MeMesh 为编码代理提供持久化、可搜索、不断演进的本地内存。**
 
-**MeMesh 让每个 AI 都能拥有持久、可搜索、持续进化的记忆。**
+本包是 MeMesh 产品系列的本地内存层。我们刻意保持简洁并开源：用 npm 安装，内存文件保存在 `~/.memesh/knowledge-graph.db`，连接到 Claude Code 或任何兼容 MCP 的客户端即可。托管工作区和企业级操作系统产品应当独立于本包的 README 和路线图。
 
 ---
 
-## 60 秒快速上手
+## 60 秒快速开始
 
 ### 第一步：安装
 
@@ -32,53 +37,59 @@
 npm install -g @pcircle/memesh
 ```
 
-### 第二步：AI 开始记忆
+### 第二步：记录一个决策
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 第三步：AI 召回记忆
+### 第三步：之后随时调用
 
 ```bash
 memesh recall "login security"
-# → 搜索「login security」也能找到「OAuth 2.0 with PKCE」
+# → 即使用词不同，也能找到 "OAuth 2.0 with PKCE"
 ```
 
-**就这样。** MeMesh 已开始在不同对话之间记忆与召回。
+**就这样。** MeMesh 现在已经在会话间记忆和回忆了。
 
-运行以下命令探索你的记忆库：
+想验证安装和本地接线是否完整：
+
+```bash
+memesh doctor
+```
+
+打开仪表板浏览你的内存：
 
 ```bash
 memesh
 ```
 
 <p align="center">
-  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — 瞬间找到任何记忆" width="100%" />
+  <img src="docs/images/dashboard-search.png" alt="MeMesh 搜索 — 瞬间找到任何记忆" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — 深入了解 AI 的知识" width="100%" />
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh 分析 — 健康评分、时间线、模式、知识覆盖" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — 交互式知识图谱，支持类型筛选与自我模式" width="100%" />
+  <img src="docs/images/dashboard-graph.png" alt="MeMesh 知识图 — 交互式知识图，支持类型过滤和中心模式" width="100%" />
 </p>
 
 ---
 
 ## 这是为谁设计的？
 
-| 如果你是… | MeMesh 能帮你… |
-|---------------|---------------------|
-| **使用 Claude Code 的开发者** | 自动记忆决策、模式与每次对话中的心得 |
-| **以 LLM 打造产品的团队** | 通过导出/导入共享团队知识，让每个人的 AI 上下文保持一致 |
-| **AI Agent 开发者** | 通过 MCP、HTTP API 或 Python SDK 赋予 Agent 持久记忆 |
-| **同时使用多款 AI 工具的重度用户** | 一个记忆层，兼容 Claude、GPT、LLaMA、Ollama 或任何 MCP 客户端 |
+| 你是... | MeMesh 帮助你... |
+|--------|-----------------|
+| **使用 Claude Code 的开发者** | 工作时自动回忆项目决策、文件特定的经验教训和过去的失败 |
+| **编码代理重度用户** | 在 MCP 兼容工具间共享一个本地内存层 |
+| **团队试验 AI 编码工作流** | 导出/导入项目知识，无需引入托管基础设施 |
+| **代理开发者** | 通过 MCP、HTTP、CLI 或 Python SDK 添加本地内存 |
 
 ---
 
-## 与所有工具兼容
+## 为编码代理优先设计
 
 <table>
 <tr>
@@ -88,28 +99,28 @@ memesh
 ```bash
 memesh-mcp
 ```
-MCP 协议（自动配置）
+MCP 工具 + Claude Code 钩子
 
 </td>
 <td width="33%" align="center">
 
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
+**任何 HTTP 客户端**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
 ```
-`pip install memesh`
+`memesh serve` (REST API)
 
 </td>
 <td width="33%" align="center">
 
-**任何 LLM（OpenAI 格式）**
+**任何 LLM (OpenAI 格式)**
 ```bash
 memesh export-schema \
   --format openai
 ```
-粘贴到任何 API 调用
+粘贴工具到任何 API 调用
 
 </td>
 </tr>
@@ -117,32 +128,34 @@ memesh export-schema \
 
 ---
 
-## 为何不用 Mem0 / Zep？
+## 为什么不用 OpenMemory、Cursor Memories、Mem0 或 Zep？
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **安装时间** | 5 秒 | 30–60 分钟 | 30+ 分钟 |
-| **配置方式** | `npm i -g` — 完成 | Neo4j + VectorDB + API 密钥 | Neo4j + 配置 |
-| **存储方式** | 单一 SQLite 文件 | Neo4j + Qdrant | Neo4j |
-| **离线使用** | 支持，始终如此 | 不支持 | 不支持 |
-| **仪表板** | 内置（7 个标签页 + 分析） | 无 | 无 |
-| **依赖包** | 6 | 20+ | 10+ |
-| **价格** | 永久免费 | 免费方案／付费 | 免费方案／付费 |
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **最佳适用场景** | 编码代理的本地内存 | 本地/跨客户端 MCP 内存 | Cursor 原生项目内存 | 托管应用/代理内存 | 时间知识图 |
+| **安装形式** | `npm install -g @pcircle/memesh` | 本地应用/服务器流程 | 内置于 Cursor | 云 API / SDK / MCP | 服务/框架配置 |
+| **存储方式** | 单个本地 SQLite 文件 | 本地内存栈 | Cursor 管理的规则/内存 | 托管或自托管栈 | 图数据库 |
+| **是否需要云** | 否 | 本地模式不需要 | 取决于 Cursor 账户/设置 | 平台需要 | 通常需要/自托管 |
+| **Claude Code 钩子** | 一级支持 | MCP 工具 | 否 | MCP 工具 | 不针对 Claude Code |
+| **仪表板** | 内置 | 内置 | Cursor 设置 | 平台仪表板 | 平台/图形工具 |
+| **权衡** | 简洁的本地方案，不适用企业规模 | 更宽泛的本地应用足迹 | 绑定 Cursor | 强大的托管平台，本地化程度低 | 强大的图模型，配置更复杂 |
 
-**MeMesh 的取舍：** 放弃企业级多租户功能，换来**即时安装、零基础设施、百分之百隐私**。
+**MeMesh 用即插即用的本地设置、可检视的存储和编码代理工作流钩子，换取企业级托管基础设施。**
 
 ---
 
-## 自动运作的功能
+## Claude Code 中的自动化流程
 
-你不需要手动记忆每一件事。MeMesh 有 **4 个 Hook**，在你不做任何事的情况下自动捕获知识：
+你不需要手动记住一切。MeMesh 有 **6 个钩子**在你工作时自动捕获和注入知识：
 
-| 时机 | MeMesh 做了什么 |
-|------|------------------|
-| **每次会话开始** | 加载最相关的记忆 + 来自过去教训的主动警告 |
-| **每次 `git commit` 后** | 记录你的变更内容与差异统计 |
-| **Claude 结束时** | 捕获已编辑的文件、已修复的错误，并自动从失败中生成结构化教训 |
-| **上下文压缩前** | 在知识因上下文限制消失前保存起来 |
+| 触发条件 | MeMesh 的动作 |
+|---------|------------|
+| **每个会话开始** | 加载最相关的记忆 + 来自过去经验教训的主动警告 + 代理编排横幅 |
+| **编辑文件前** | 回忆与该文件或项目相关的记忆，然后 Claude 才开始写代码 |
+| **执行 bash 命令前** | 推动 Claude 派遣高可验证性命令（测试、构建、lint、迁移、部署、基准测试）作为后台代理 |
+| **每次 `git commit` 后** | 记录你的改动，附带 diff 统计 |
+| **Claude 停止时** | 捕获编辑过的文件、修复的错误、自动从失败中生成结构化经验教训 |
+| **上下文压缩前** | 在知识被上下文限制吞没前保存 |
 
 > **随时退出：** `export MEMESH_AUTO_CAPTURE=false`
 
@@ -150,70 +163,85 @@ memesh export-schema \
 
 ## 仪表板
 
-7 个标签页、11 种语言、零外部依赖。服务器运行后在 `http://localhost:3737/dashboard` 访问。
+7 个标签页，11 种语言，零外部依赖。服务器运行时访问 `http://localhost:3737/dashboard`。
 
-| 标签页 | 内容 |
-|--------|------|
-| **Search** | 跨所有记忆的全文搜索 + 向量相似度搜索 |
-| **Browse** | 所有实体的分页列表，支持归档/恢复 |
-| **Analytics** | 记忆健康分数（0-100）、30 天时间轴、价值指标、知识覆盖率、清理建议、你的工作模式 |
-| **Graph** | 交互式力导向知识图谱，支持类型筛选、搜索、自我模式、时间热力图 |
-| **Lessons** | 从过去失败中生成的结构化教训（错误、根因、修复方法、预防措施） |
-| **Manage** | 归档与恢复实体 |
-| **Settings** | LLM 提供者配置、语言选择 |
+| 标签页 | 你看到什么 |
+|--------|---------|
+| **搜索** | 全文 + 向量相似度搜索，覆盖所有记忆 |
+| **浏览** | 所有实体的分页列表，支持归档/恢复 |
+| **分析** | 内存健康评分（0-100）、30 天时间线、价值指标、知识覆盖、清理建议、你的工作模式 |
+| **知识图** | 交互式力导向图，支持类型过滤、搜索、中心模式、新近度热力图 |
+| **经验教训** | 来自过去失败的结构化经验教训（错误、根本原因、修复、预防） |
+| **管理** | 归档和恢复实体 |
+| **设置** | LLM 提供商配置、即时语言切换器 |
 
 ---
 
-## 智能功能
+## 聪慧功能
 
-**🧠 智能搜索** — 搜索「login security」就能找到关于「OAuth PKCE」的记忆。MeMesh 使用你配置的 LLM 将查询扩展为相关词汇。
+**🧠 智能搜索** — 搜索"登录安全"会找到"OAuth PKCE"相关的记忆。MeMesh 用你配置的 LLM 扩展查询。
+
+**📊 评分排序** — 结果按相关性（30%）+ 新近度（25%）+ 频率（15%）+ 置信度（15%）+ 回忆影响（10%）+ 时间有效性（5%）排序。
+
+**🔄 知识演进** — 决策会变化。`forget` 归档旧记忆（永不删除）。`supersedes` 关系链接 旧 → 新。你的 AI 总是看到最新版本。
+
+**⚠️ 冲突检测** — 如果你有两条相互矛盾的记忆，MeMesh 会警告你。
+
+**📦 团队共享** — `memesh export > team-knowledge.json` → 与团队分享 → `memesh import team-knowledge.json`
+导入的包保持可搜索，但 MeMesh 不会自动将导入的记忆注入到 Claude 钩子中，直到你审查或本地重新存储它们。
+
+---
 
-**📊 评分排名** — 结果依相关性（35%）+ 最近使用时间（25%）+ 使用频率（20%）+ 可信度（15%）+ 信息时效性（5%）排序。
+## 使用示例
 
-**🔄 知识演进** — 决策会改变。`forget` 是归档旧记忆（从不真正删除）。`supersedes` 关系将旧记忆与新记忆链接。你的 AI 始终看到最新版本。
+> "MeMesh 记得我们三周前选择了 PKCE 而不是隐式流。我再次问 Claude 有关身份验证的问题时，它已经知道——无需重新解释。"
+> — **独立开发者，正在构建 SaaS**
 
-**⚠️ 冲突检测** — 若有两条记忆相互矛盾，MeMesh 会发出警告。
+> "我们每周五导出团队的内存，周一导入。每个人的 Claude 周一开始时都知道团队上周学到了什么。"
+> — **3 人初创公司，共享知识库**
 
-**📦 团队共享** — `memesh export > team-knowledge.json` → 分享给团队 → `memesh import team-knowledge.json`
+> "仪表板显示我 90% 的记忆是自动生成的会话日志。我开始有意使用 `remember` 记录架构决策。彻底改变了游戏规则。"
+> — **发现分析标签页的开发者**
 
 ---
 
-## 启用智能模式（可选）
+## 解锁智能模式（可选）
 
-MeMesh 默认完全离线运作。加入 LLM API 密钥即可解锁更聪明的搜索：
+MeMesh 默认离线工作。仅当你需要查询扩展、更聪慧的提取和压缩时，才添加 LLM API 密钥：
 
 ```bash
 memesh config set llm.provider anthropic
 memesh config set llm.api-key sk-ant-...
 ```
 
-或使用仪表板的设置标签页（可视化配置）：
+或使用仪表板设置标签页（可视化配置）：
 
 ```bash
 memesh  # 打开仪表板 → 设置标签页
 ```
 
-| | 第 0 级（默认） | 第 1 级（智能模式） |
+| | 级别 0（默认） | 级别 1（智能模式） |
 |---|---|---|
-| **搜索** | FTS5 关键字匹配 | + LLM 查询扩展（约 97% 召回率） |
-| **自动捕获** | 规则式模式 | + LLM 提取决策与心得 |
-| **压缩** | 不支持 | `consolidate` 压缩冗长记忆 |
-| **费用** | 免费，无需 API 密钥 | 约 $0.0001 每次搜索（Haiku） |
+| **搜索** | FTS5 关键词匹配 | + LLM 查询扩展（~97% 召回率） |
+| **自动捕获** | 基于规则的模式 | + LLM 提取决策和经验教训 |
+| **压缩** | 不可用 | `consolidate` 压缩冗长的记忆 |
+| **成本** | 免费，无需 API 密钥 | ~$0.0001 每次搜索（Haiku） |
 
 ---
 
-## 全部 8 个记忆工具
+## 全部 9 个内存工具
 
-| 工具 | 功能说明 |
-|------|-------------|
-| `remember` | 存储知识，支持观察记录、关联关系与标签 |
-| `recall` | 智能搜索，结合多因子评分与 LLM 查询扩展 |
-| `forget` | 软归档（从不真正删除）或移除特定观察记录 |
+| 工具 | 它做什么 |
+|------|--------|
+| `remember` | 存储知识，附带观察、关系和标签 |
+| `recall` | 智能搜索，多因素评分和 LLM 查询扩展 |
+| `forget` | 软归档（永不删除）或移除特定观察 |
 | `consolidate` | LLM 驱动的冗长记忆压缩 |
-| `export` | 将记忆以 JSON 格式分享给其他项目或团队成员 |
-| `import` | 导入记忆，支持合并策略（跳过 / 覆盖 / 追加） |
-| `learn` | 记录来自错误的结构化教训（错误、根因、修复方法、预防措施） |
-| `user_patterns` | 分析你的工作模式 — 时间安排、工具、优势、学习方向 |
+| `export` | 在项目或团队成员间共享内存，格式为 JSON |
+| `import` | 导入内存，支持合并策略（跳过 / 覆盖 / 追加） |
+| `learn` | 从错误中记录结构化经验教训（错误、根本原因、修复、预防） |
+| `user_patterns` | 分析你的工作模式——日程、工具、优势、学习领域 |
+| `verify_agent_work` | 为后台代理工作保存验证报告；对照 `git diff` 验证声称的文件改动 |
 
 ---
 
@@ -234,7 +262,7 @@ memesh  # 打开仪表板 → 设置标签页
                     (~/.memesh/knowledge-graph.db)
 ```
 
-核心引擎与框架无关。无论从终端、HTTP 还是 MCP 调用，逻辑完全相同。
+核心是框架无关的。相同逻辑从终端、HTTP 或 MCP 运行。
 
 ---
 
@@ -243,7 +271,8 @@ memesh  # 打开仪表板 → 设置标签页
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
 cd memesh-llm-memory && npm install && npm run build
-npm test -- --run    # 413 tests
+npm test             # 489 个测试
+npm run test:e2e-dashboard
 ```
 
 仪表板：`cd dashboard && npm install && npm run dev`