@pcircle/memesh 4.0.3 → 4.1.1

package/README.zh-CN.md

@@ -1,110 +1,284 @@
+<!-- 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>给 Claude Code 和 MCP coding agents 用的本地记忆层。</strong><br />
-    一个 SQLite 文件。不需要 Docker。不需要云端。
+    <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>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
 
-> 这份简体中文版 README 是精简导览。最新、最完整的内容请以 [English README](README.md) 为准。
+---
 
-## 它解决什么问题？
+## 问题
 
-coding agent 很容易在不同 session 之间丢失上下文。架构决策、修 bug 的过程、踩过的坑、项目限制，常常要反复解释。
+编码代理在会话间会遗忘。每个架构决策、每次 bug 修复、失败的测试用例、每一次来之不易的经验教训都需要重新解释一遍。Claude Code 每次都从零开始，重新发现老约束，浪费上下文在早该掌握的东西上。
 
-**MeMesh 把这些知识保存在本地，可搜索、可查看，也能在后续工作里再次被召回。**
+**MeMesh 为编码代理提供持久化、可搜索、不断演进的本地内存。**
 
-这个 npm package 是 MeMesh 的本地 plugin / package 版本，重点是本地记忆，不是云端工作台，也不是企业平台。
+本包是 MeMesh 产品系列的本地内存层。我们刻意保持简洁并开源：用 npm 安装，内存文件保存在 `~/.memesh/knowledge-graph.db`，连接到 Claude Code 或任何兼容 MCP 的客户端即可。托管工作区和企业级操作系统产品应当独立于本包的 README 和路线图。
 
-## 60 秒上手
+---
 
-### 1. 安装
+## 60 秒快速开始
+
+### 第一步：安装
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 2. 记下一条决策
+### 第二步：记录一个决策
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 3. 之后再找回来
+### 第三步：之后随时调用
 
 ```bash
 memesh recall "login security"
-# → 即使换种说法，也能找到 "OAuth 2.0 with PKCE"
+# → 即使用词不同，也能找到 "OAuth 2.0 with PKCE"
+```
+
+**就这样。** MeMesh 现在已经在会话间记忆和回忆了。
+
+想验证安装和本地接线是否完整：
+
+```bash
+memesh doctor
 ```
 
-打开 dashboard：
+打开仪表板浏览你的内存：
 
 ```bash
 memesh
 ```
 
-## 适合谁？
+<p align="center">
+  <img src="docs/images/dashboard-search.png" alt="MeMesh 搜索 — 瞬间找到任何记忆" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh 分析 — 健康评分、时间线、模式、知识覆盖" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-graph.png" alt="MeMesh 知识图 — 交互式知识图，支持类型过滤和中心模式" width="100%" />
+</p>
+
+---
+
+## 这是为谁设计的？
+
+| 你是... | MeMesh 帮助你... |
+|--------|-----------------|
+| **使用 Claude Code 的开发者** | 工作时自动回忆项目决策、文件特定的经验教训和过去的失败 |
+| **编码代理重度用户** | 在 MCP 兼容工具间共享一个本地内存层 |
+| **团队试验 AI 编码工作流** | 导出/导入项目知识，无需引入托管基础设施 |
+| **代理开发者** | 通过 MCP、HTTP、CLI 或 Python SDK 添加本地内存 |
+
+---
+
+## 为编码代理优先设计
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+**Claude Code / Desktop**
+```bash
+memesh-mcp
+```
+MCP 工具 + Claude Code 钩子
+
+</td>
+<td width="33%" align="center">
+
+**任何 HTTP 客户端**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
+```
+`memesh serve` (REST API)
+
+</td>
+<td width="33%" align="center">
+
+**任何 LLM (OpenAI 格式)**
+```bash
+memesh export-schema \
+  --format openai
+```
+粘贴工具到任何 API 调用
+
+</td>
+</tr>
+</table>
+
+---
 
-- 使用 Claude Code，希望跨 session 保留项目上下文的开发者
-- 使用 MCP coding agents，希望共用同一份本地记忆的高级用户
-- 小型 AI-native 开发团队，希望通过 export / import 共享项目知识
-- 想把本地记忆接入 CLI、HTTP 或 MCP 工作流的 agent 开发者
+## 为什么不用 OpenMemory、Cursor Memories、Mem0 或 Zep？
 
-## 为什么选 MeMesh？
+| | **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 | 强大的托管平台，本地化程度低 | 强大的图模型，配置更复杂 |
 
-- 本地优先：数据保存在你自己的 SQLite 文件里
-- 安装轻量：`npm install -g` 后即可使用
-- 接入直接：同时支持 CLI、HTTP、MCP
-- 对 Claude Code 友好：提供 hooks，可在工作流里自动带入相关记忆
-- 可查看可清理：内建 dashboard，不是黑盒
-- 更安全的导入边界：导入的记忆默认可搜索，但不会直接自动注入到 Claude hooks，除非你重新审核或在本地重新保存
+**MeMesh 用即插即用的本地设置、可检视的存储和编码代理工作流钩子，换取企业级托管基础设施。**
 
-## 在 Claude Code 里会自动做什么？
+---
 
-MeMesh 目前会在 5 个时机帮你：
+## Claude Code 中的自动化流程
 
-- session 开始时，加载项目相关记忆和已知教训
-- 编辑文件前，先召回与该文件或项目相关的记忆
-- `git commit` 后，记录你做了哪些改动
-- session 结束时，整理本次修复、错误和 lesson learned
-- context compact 之前，先把重要内容写回本地记忆
+你不需要手动记住一切。MeMesh 有 **6 个钩子**在你工作时自动捕获和注入知识：
 
-## Dashboard 里有什么？
+| 触发条件 | MeMesh 的动作 |
+|---------|------------|
+| **每个会话开始** | 加载最相关的记忆 + 来自过去经验教训的主动警告 + 代理编排横幅 |
+| **编辑文件前** | 回忆与该文件或项目相关的记忆，然后 Claude 才开始写代码 |
+| **执行 bash 命令前** | 推动 Claude 派遣高可验证性命令（测试、构建、lint、迁移、部署、基准测试）作为后台代理 |
+| **每次 `git commit` 后** | 记录你的改动，附带 diff 统计 |
+| **Claude 停止时** | 捕获编辑过的文件、修复的错误、自动从失败中生成结构化经验教训 |
+| **上下文压缩前** | 在知识被上下文限制吞没前保存 |
 
-Dashboard 目前有 7 个标签页，并支持 11 种语言：
+> **随时退出：** `export MEMESH_AUTO_CAPTURE=false`
 
-- Search：搜索记忆
-- Browse：浏览全部记忆
-- Analytics：查看健康度、趋势和使用情况
-- Graph：查看知识关系图
-- Lessons：查看过往经验教训
-- Manage：归档或恢复记忆
-- Settings：设置 LLM provider 和语言
+---
 
-## Smart Mode 是什么？
+## 仪表板
 
-MeMesh 默认就能离线使用。若你额外配置 LLM API key，可以启用更智能的能力，例如：
+7 个标签页，11 种语言，零外部依赖。服务器运行时访问 `http://localhost:3737/dashboard`。
 
-- query expansion
-- 更好的自动提取
-- 更智能的记忆整理与压缩
+| 标签页 | 你看到什么 |
+|--------|---------|
+| **搜索** | 全文 + 向量相似度搜索，覆盖所有记忆 |
+| **浏览** | 所有实体的分页列表，支持归档/恢复 |
+| **分析** | 内存健康评分（0-100）、30 天时间线、价值指标、知识覆盖、清理建议、你的工作模式 |
+| **知识图** | 交互式力导向图，支持类型过滤、搜索、中心模式、新近度热力图 |
+| **经验教训** | 来自过去失败的结构化经验教训（错误、根本原因、修复、预防） |
+| **管理** | 归档和恢复实体 |
+| **设置** | LLM 提供商配置、即时语言切换器 |
 
-不配置也可以正常使用核心功能。
+---
 
-## 更多信息
+## 聪慧功能
 
-- 完整功能、对比、API 和 release 细节：请看 [English README](README.md)
-- 平台集成方式：请看 [docs/platforms/README.md](docs/platforms/README.md)
-- API 参考：请看 [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+**🧠 智能搜索** — 搜索"登录安全"会找到"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 钩子中，直到你审查或本地重新存储它们。
+
+---
+
+## 使用示例
+
+> "MeMesh 记得我们三周前选择了 PKCE 而不是隐式流。我再次问 Claude 有关身份验证的问题时，它已经知道——无需重新解释。"
+> — **独立开发者，正在构建 SaaS**
+
+> "我们每周五导出团队的内存，周一导入。每个人的 Claude 周一开始时都知道团队上周学到了什么。"
+> — **3 人初创公司，共享知识库**
+
+> "仪表板显示我 90% 的记忆是自动生成的会话日志。我开始有意使用 `remember` 记录架构决策。彻底改变了游戏规则。"
+> — **发现分析标签页的开发者**
+
+---
+
+## 解锁智能模式（可选）
+
+MeMesh 默认离线工作。仅当你需要查询扩展、更聪慧的提取和压缩时，才添加 LLM API 密钥：
+
+```bash
+memesh config set llm.provider anthropic
+memesh config set llm.api-key sk-ant-...
+```
+
+或使用仪表板设置标签页（可视化配置）：
+
+```bash
+memesh  # 打开仪表板 → 设置标签页
+```
+
+| | 级别 0（默认） | 级别 1（智能模式） |
+|---|---|---|
+| **搜索** | FTS5 关键词匹配 | + LLM 查询扩展（~97% 召回率） |
+| **自动捕获** | 基于规则的模式 | + LLM 提取决策和经验教训 |
+| **压缩** | 不可用 | `consolidate` 压缩冗长的记忆 |
+| **成本** | 免费，无需 API 密钥 | ~$0.0001 每次搜索（Haiku） |
+
+---
+
+## 全部 9 个内存工具
+
+| 工具 | 它做什么 |
+|------|--------|
+| `remember` | 存储知识，附带观察、关系和标签 |
+| `recall` | 智能搜索，多因素评分和 LLM 查询扩展 |
+| `forget` | 软归档（永不删除）或移除特定观察 |
+| `consolidate` | LLM 驱动的冗长记忆压缩 |
+| `export` | 在项目或团队成员间共享内存，格式为 JSON |
+| `import` | 导入内存，支持合并策略（跳过 / 覆盖 / 追加） |
+| `learn` | 从错误中记录结构化经验教训（错误、根本原因、修复、预防） |
+| `user_patterns` | 分析你的工作模式——日程、工具、优势、学习领域 |
+| `verify_agent_work` | 为后台代理工作保存验证报告；对照 `git diff` 验证声称的文件改动 |
+
+---
+
+## 架构
+
+```
+                    ┌─────────────────┐
+                    │   Core Engine   │
+                    │  (8 operations) │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
+```
+
+核心是框架无关的。相同逻辑从终端、HTTP 或 MCP 运行。
+
+---
+
+## 贡献
 
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory
-npm install
-npm run build
-npm test
+cd memesh-llm-memory && npm install && npm run build
+npm test             # 489 个测试
+npm run test:e2e-dashboard
 ```
+
+仪表板：`cd dashboard && npm install && npm run dev`
+
+---
+
+<p align="center">
+  <strong>MIT</strong> — 由 <a href="https://pcircle.ai">PCIRCLE AI</a> 开发
+</p>