Yggdrasil

<!-- mcp-name: io.github.VonderVuflya/yggdrasil --> <h1 align="center">🌳 尤格德拉西尔</h1> <p align="center"><b>所有 AI 编码代理共享的持久性内存</b><br/> Claude Code、Codex 和任何 MCP 主机都记得你的决策、经验教训和项目状态 — 跨会话、工具和项目。</p> <p align="center"> <a href="https://github.com/VonderVuflya/Yggdrasil/releases/latest"><img src="https://img.shields.io/github/v/release/VonderVuflya/Yggdrasil?label=release&color=blue" alt="最新版本"></a> <a href="https://pypi.org/project/yggdrasil-memory/"><img src="https://img.shields.io/pypi/v/yggdrasil-memory?label=PyPI&color=blue" alt="PyPI"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Elastic%202.0-blue.svg" alt="Elastic License 2.0"></a> <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"> <img src="https://img.shields.io/badge/deps-zero%20(stdlib)-brightgreen" alt="零依赖"> <img src="https://img.shields.io/badge/MCP-Claude%20·%20Codex%20·%20Desktop-purple" alt="MCP"> <img src="https://img.shields.io/badge/local--first-100%25%20private-success" alt="本地优先"> <img src="https://img.shields.io/badge/status-alpha-orange" alt="alpha"> </p> <p align="center"> <a href="#-快速开始">快速开始</a> · <a href="#-工作原理">工作原理</a> · <a href="#-尤格德拉西尔与其他工具的比较">比较</a> · <a href="#-命令">命令</a> · <a href="#-常见问题">常见问题</a> </p> <p align="center"> <a href="./README.md"><img src="https://img.shields.io/badge/README-English-blue" alt="English"></a> <a href="./i18n/README.ru.md"><img src="https://img.shields.io/badge/docs-Русский-darkblue" alt="Русский"></a> <a href="./i18n/README.zh.md"><img src="https://img.shields.io/badge/docs-简体中文-red" alt="简体中文"></a> <a href="./i18n/README.es.md"><img src="https://img.shields.io/badge/docs-Español-orange" alt="Español"></a> <a href="./i18n/README.fr.md"><img src="https://img.shields.io/badge/docs-Français-blue" alt="Français"></a> <a href="./i18n/README.ja.md"><img src="https://img.shields.io/badge/docs-日本語-red" alt="日本語"></a> <a href="./i18n/README.de.md"><img src="https://img.shields.io/badge/docs-Deutsch-yellow" alt="Deutsch"></a> </p> --- 每次新的聊天，你的 AI 都会忘记。你需要重新解释项目、决策和注意事项 — 每次、每个工具都是如此。**尤格德拉西尔是一个小型的、始终在线的记忆大脑，任何代理都可以连接到它。** 打开一个新会话，在任何项目中使用任何 AI，它已经知道你做出了什么决定，什么地方出了问题，什么仍然是开放的 — 而且它会在后台不断学习。 ```text $ cd ~/projects/checkout-api && claude # 一个全新的会话 🌳 尤格德拉西尔 （在会话开始时自动注入） 打开后续任务和状态： • [project_status] 支付重构：添加幂等键；开放：端到端测试 用于 `checkout-api` 的持久性内存： • [debugging_lesson] webhook 401 → 签名密钥轮换；更新环境变量 + 重新部署 > "我是否在其他地方解决过 flaky websocket reconnect 问题？" 🌳 回忆 → 在项目 `realtime-dash` 中找到： 刷新令牌 *在* 打开套接字之前，然后使用上限退避重试。 ``` 无需 "让我提醒你我们昨天做了什么"。它就在那里。 ## 为什么 **没有尤格德拉西尔**，你需要在每个新聊天中重新解释上下文，一个项目中的经验教训永远不会传递到下一个项目，从 Claude Code 切换到 Codex 从零开始，辛苦获得的调试见解随着会话结束而消失。 **有了尤格德拉西尔：** - 🧠 **持久性内存** — 决策、经验教训和状态在会话之间存活。 - 🔌 **任何代理，一个大脑** — Claude Code、Codex、任何 MCP 主机共享相同的内存。 - 🌐 **跨项目回忆** — *"这看起来像你在项目 B 中做的事情 — 重用它？"* - 🌱 **自我学习** — 本地模型在后台整合内存（零 API 令牌）。 - 🪪 **灵魂** — 给它取个名字和个性；它在每个工具中都会出现。 - 🔒 **100% 本地和私有** — 你的内存存活在你的机器上。没有云，没有账户。 ## 🚀 快速开始 > **要求：** macOS（Linux/Windows 即将支持），Python 3.10+ — 或让 `uv`/`npx` 为你获取 Python。语义搜索是可选的，使用本地 [Ollama](https://ollama.com) 模型。 **选项 A — 作为插件安装** （一步到位，直接在你的代理中 — 零配置）。在 **Claude Code** 中： ```text /plugin marketplace add VonderVuflya/Yggdrasil /plugin install yggdrasil ``` 引擎在第一次使用时延迟启动并生成自己的本地令牌 — **无需 API 密钥，无需云，无需配置。** （Codex 和 Cursor 使用相同的流程。） **选项 B — 安装完整服务** （始终在线的守护进程 + 自动注入到会话开始 + 可选的本地模型）： ```bash uvx --from yggdrasil-memory ygg install # 一次引导式设置 ``` <details> <summary>所有安装渠道（相同的引擎）</summary> | 主机/工具 | 命令 | | --- | --- | | **Claude Code · Codex · Cursor** （插件） | `/plugin marketplace add VonderVuflya/Yggdrasil` → `/plugin install yggdrasil` | | **uvx** _（推荐的 CLI）_ | `uvx --from yggdrasil-memory ygg install` | | **npm / npx** | `npx yggdrasil-memory install` | | **pipx** | `pipx install yggdrasil-memory && ygg install` | | **pip** | `pip install yggdrasil-memory && ygg install` | | **Homebrew** _（macOS）_ | `brew install VonderVuflya/tap/yggdrasil && ygg install` | | **Claude Desktop** _（应用）_ | 从 [最新版本](https://github.com/VonderVuflya/Yggdrasil/releases/latest) 拖拽 `.mcpb` 到 设置 → 扩展 ([指南](./packaging/mcpb/README.md)) | | **从源码** | `uvx --from git+https://github.com/VonderVuflya/yggdrasil.git ygg install` | </details> `ygg install` 是一个一次性的引导式设置：它检测你的硬件并 **推荐适合的本地模型** （或选择 `none` 进行零配置，仅限词典）。它生成一个私有认证令牌，安装一个 **始终在线的后台服务**，并将工具注册到 Claude Code 和 Codex。 **验证和使用：** ```bash ygg doctor # 引擎 · 模型 · MCP 注册 · 全部绿色？ ``` 然后直接工作。询问你的代理 *"回忆一下我们对这个项目的决定"*, 或告诉它 *"记住这个决定"* — 在下一个会话中，它已经存在。 随便试试？ `uvx --from yggdrasil-memory ygg serve --reset --db /tmp/ygg.sqlite`. ## 🔌 更多连接方式 除了上述的插件和 `ygg install` 之外： - 🖥️ **Claude Desktop （应用）** — 安装 MCP 扩展：从 [最新版本](https://github.com/VonderVuflya/Yggdrasil/releases/latest) 获取 `yggdrasil-<version>.mcpb`，拖拽到 **设置 → 扩展**，并粘贴你的令牌（`ygg token`）。桌面应用现在与你的 CLI 代理共享 **相同的内存**。 → [设置指南](./packaging/mcpb/README.md) - 🧠 **技能（任意 Claude）** — [`yggdrasil-memory` 技能](./skills/) 教会代理工作流程：工作前回忆，工作后记住。 通过 **设置 → 技能 → 创建技能 → 上传技能** 上传 `yggdrasil-memory.zip`。 > **MCP vs 技能：** MCP 连接 *工具*（如何访问内存）；技能教会 *何时使用它们*。同时使用两者以获得最佳行为。 ## 🧠 工作原理 尤格德拉西尔是 **内存 + 工具** — *智能* 是你的 LLM。它只是确保在合适的时间将正确的内存呈现给合适的代理。 - 🛎️ **始终在线的守护进程** — 一个小型本地服务（~21 MB RAM）你的代理通过 MCP 工具（`ygg_search`, `ygg_recall`, `ygg_remember` …）访问。 - 🪝 **会话开始** — 一个钩子自动注入身份、项目状态和未完成的任务。 - 📌 **排名** — 频繁回忆和固定的记忆会浮现得更高（存储和层级如下 ↓）。 - 🧹 **治理** — 重复/冲突被审查；更改是非破坏性的（存档，永不删除）。 - 📓 **Obsidian** — 每个记忆也是一个 Markdown 注释，你可以阅读和编辑。 ## 🎛️ 内存层级 — 默认零配置 开箱即用，尤格德拉西尔运行在 **SQLite + FTS5，零依赖** — 即时关键词（词典）搜索，无模型，无 GPU，无需下载。已经很有用：recall@1 ≈ 0.77. 想要它匹配 **含义** 和跨语言？如果你的硬件允许，`ygg install` 可以通过 [Ollama](https://ollama.com) 拉取可选的 **本地模型** — 它检测你的 CPU/RAM/GPU 并推荐合适的（或选择 `none` 以保持零配置）。两个可选的独立层级： ```text 你的代理 ─► ygg_search / ygg_recall / ygg_remember │ ┌───────────▼───────────┐ │ SQLite （存储） │ │ ├─ FTS5 / BM25 ─────┼─► 关键词搜索 （始终 · 零依赖） │ └─ 嵌入列 ─┼─► 语义搜索 （可选） └───────────▲───────────┘ │ 向量输入 可选 · 本地： Ollama 模型 ── 仅计算向量 / 运行整合 ``` | 层级 | 你添加 | 你获得 | | --- | --- | --- | | **0 · 默认** | 无 - SQLite + FTS5 | 关键词搜索，零依赖，立即 — recall@1 ≈ **0.77** | | **1 · 语义** | 通过 Ollama 的 **嵌入** 模型（例如 `all-minilm` 45 MB · `paraphrase-multilingual` ~560 MB） | 按 **含义** 搜索 + 跨语言 — recall@1 ≈ **0.94** | | **2 · 自我学习** | 通过 Ollama 的小型 **整合** LLM（例如 `qwen2.5:1.5b` ~1 GB） | 背景重复/合并内存（建议安全） | Olama 仅 **计算** 向量 / 运行后台模型 — 向量和所有内存仍存放在 **相同的 SQLite** 中。层级是独立且可选的。 <details> <summary>完整的模型菜单（或运行 <code>ygg recommend</code>）</summary> **嵌入（语义搜索）： | 模型 | 大小 | 适用场景 | | --- | --- | --- | | `all-minilm` | 45 MB | 英语，轻量且快速 | | `nomic-embed-text` | 274 MB | 英语，质量更好 | | `paraphrase-multilingual` | ~560 MB | 多语言（EN/RU + 50 种语言） | | `bge-m3` | 1.2 GB | 多语言，顶级质量（较重） | **后台整合（不建议安全） | </details> 一切保持 **100% 本地 — 零 API 令牌，无需云服务**。安装程序推荐适合您硬件的模型（或选择 `none` 以保持零配置）。 > 引擎本身是可互换的 — 任何符合 `MemoryBackend` 契约的服务都是一个即插即用的替代品（将 `YGG_ENGINE_URL` 指向它）；SQLite 是零依赖的默认实现。参见 [docs/backend-boundary.md](./docs/backend-boundary.md). ## 🆚 尤格德拉西尔与其他工具的比较 最接近的工具是 **claude-mem** — 同样适用于编码代理的持久性内存，但一个 *更重量级* 的系统，它捕获所有内容并进行 AI 压缩（需要 Node + Bun + 矢量数据库）。**mem0** 是一个用于应用的内存 **SDK**，以便记住其用户。context-mode 和 Context7 拥有 **不同的层级**（您的实时上下文窗口；新鲜的库文档）。尤格德拉西尔是 **安装即用，零依赖，本地优先的您自己的工作内存** — 精心策划的，而不是全面的，以 Markdown 格式存储，您可以编辑。 | | **尤格德拉西尔** | [claude-mem](https://github.com/thedotmack/claude-mem) | [mem0](https://github.com/mem0ai/mem0) | [context-mode](https://github.com/mksglu/context-mode) | [Context7](https://github.com/upstash/context7) | | --- | --- | --- | --- | --- | --- | | 您自己的工作（决策，经验教训，状态）的持久性内存 | ✅ | ✅ | ✅ | ⚠️ 会话内 | ❌ | | 代理的**即插即用**（无需代码，MCP） | ✅ | ✅ | ⚠️ SDK | ✅ | ✅ | | **零依赖**（stdlib + SQLite；无 Node/Bun/矢量数据库） | ✅ | ❌ | ❌ | ❌ | — | | 无需 LLM 和 API 密钥即可工作（默认词典） | ✅ | ❌ *AI 压缩* | ❌ *需要 LLM* | ✅ | ❌ | | **策划**且可编辑的 Markdown 格式（非全捕获） | ✅ | ❌ *自动捕获所有* | ⚠️ | ❌ | — | | **100% 本地和私有**（默认无云） | ✅ | ⚠️ | ⚠️ *默认云* | ✅ | ☁️ 托管 | | 跨项目回忆（“在项目 B 中解决了”） | ✅ | ⚠️ | ⚠️ | ❌ | — | | 一个内存跨工具共享（Claude Code · Codex · 任意 MCP 主机） | ✅ | ✅ | ⚠️ *每应用* | ✅ | ✅ | | 实时公共库文档 | ❌ *(使用 Context7)* | ❌ | ❌ | ❌ | ✅ | > **claude-mem vs 尤格德拉西尔，一句话：** claude-mem 自动捕获 **所有内容** 并进行 AI 压缩（Node + Bun + 矢量数据库；~84k★，附带加密令牌） — 存储随会话增长。尤格德拉西尔保留 **重要的事情** — 精心策划并 **语义重复** （近似的课程会合并，因此它保持小且高信号），零依赖，以纯行存储，你可以 grep，编辑和拥有 — 无需 AI，无令牌。不同的理念；你可以同时运行两者。 > **mem0 vs 尤格德拉西尔，一句话：** mem0 是一个内存 **SDK/平台，用于构建记住用户的应用** （你写代码；它通常调用 LLM，默认云）。尤格德拉西尔是 **即插即用，本地优先的你自己的工作内存**，适用于你已经使用的编码代理。不同的任务 — 选择适合你的。 > 还与 [**autoresearch**](https://github.com/karpathy/autoresearch) 搭配良好 — 一个自主实验循环（不是内存工具）；尤格德拉西尔为其提供长期内存，以尝试过的内容 → [集成](./integrations/autoresearch/). **TL;DR:** 如果您想要跨多个 IDE 自动捕获所有内容，并且不介意更重量级的堆栈，请使用 **claude-mem**。如果您正在构建一个必须按比例记住用户的 AI **产品**，请使用 **mem0**。如果您想要一个小型的本地、策划的内存，您拥有它 — 零依赖，无需 AI — 适用于您已经使用的编码代理，请使用 **尤格德拉西尔**。 ## 🧰 命令 代理看到六个 MCP 工具：`ygg_health`, `ygg_bootstrap`, `ygg_search`, `ygg_recall`, `ygg_remember`, `ygg_materialize`. 在 `ygg install` 后，它们会自动注册到 Claude Code 和 Codex — 只需打开一个项目并工作。 <details> <summary>完整的 <code>ygg</code> CLI 参考</summary> **内存操作** | 命令 | 功能 | | --- | --- | | `ygg recall --query "…"` | **跨项目** 搜索 — "我是否在其他地方做过这个？" | | `ygg search --project P --query "…"` | 项目范围内的搜索 (`--type`, `--tag`, `--limit`, `--json`) | | `ygg remember --project P --type debugging_lesson --content "…"` | 保存持久性内存（秘密保护，重复检查； `--tag` 添加标签） | | `ygg bootstrap --project P` | 拉取项目内存 | | `ygg pin --id ID` · `ygg unpin --id ID` | 固定记忆使其可靠显示 | | `ygg supersede --id ID` | 用新记忆存档过时的记忆 | | `ygg materialize --id ID --project P` | 导出记忆到 Obsidian 注释 | **服务和设置** | 命令 | 功能 | | --- | --- | | `ygg install` · `ygg setup` | 引导式设置 → 后台服务 + MCP 注册 | | `ygg doctor` · `ygg update` | 诊断安装 · 重新部署最新代码 | | `ygg status` · `start` · `stop` · `restart` · `logs` | 管理始终在线的守护进程 | | `ygg hooks` · `unhooks` | 启用/禁用会话启动自动引导钩子 | | `ygg recommend` | 显示硬件感知的模型目录 | | `ygg token` · `uninstall` | 打印认证令牌 · 删除服务 + 注册 | 给它一个个性 — 编辑 `~/.yggdrasil/identity.json`: ```json { "name": "Jarvis", "persona": "简洁，积极，冷幽默", "user_facts": ["偏好 TypeScript", "提交小 PRs"] } ``` </details> ## ❓ 常见问题 <details> <summary><b>它是否将代码或内存发送到云端？</b></summary> 不。引擎、数据库和可选模型都在本地运行。无需账户，无需遥测。你的内存永远不会离开你的机器。 </details> <details> <summary><b>它会自动记住所有事情吗？</b></summary> 不 — 出于设计考虑。检索是自动的；**写入** 是故意的（代理调用 `ygg_remember` 进行持久性经验教训）。自动捕获所有内容会使内存污染，所以我们不这样做。后台模型会整合已保存的内容（默认仅建议）。 </details> <details> <summary><b>我需要 GPU 或 API 密钥吗？</b></summary> 不。默认情况下，它是纯粹的词典搜索 — 零依赖，立即生效。语义搜索是可选的，并且使用本地模型通过 Ollama（无需 API 密钥）。安装程序会推荐适合您硬件的模型。 </details> <details> <summary><b>它的重量是多少，需要多少令牌？</b></summary> 很小。引擎 **~21 MB RAM，~0% 空闲 CPU，零依赖** （Python 标准库）；磁盘占用为数十 KB 每条内存。会话开始时注入约 300 个令牌，每个工具调用返回一个小片段 — 所有繁重的工作（索引，嵌入，整合）都在本地 LLM 上运行。 </details> <details> <summary><b>检索效果如何？</b></summary> 通过 `eval/ygg_eval.py` 测量（35 个标记案例，开发/保留分割），recall@1: | 模式 | recall@1 | 释义 | 跨语言（EN→RU） | | --- | --- | --- | --- | | 词典（默认） | 0.77 | 0.63 | 0.00 | | 密集 · `all-minilm` (45 MB, EN) | 0.83 | 0.88 | 0.00 | | 密集 · `paraphrase-multilingual` (~560 MB) | **0.94** | 0.88 | **0.80** | `keyword` 和 `identifier` 查询在每种模式下均为 1.0；使用多语言模型 **recall@3 = 1.0**（每个目标的前 3 个结果中）。 </details> <details> <summary><b>我可以手动编辑或删除记忆吗？</b></summary> 是的。记忆表现为 Obsidian 仓库中的 Markdown 注释 — 像任何文件一样读取，编辑或删除它们。引擎永远不会硬删除；它会存档（可逆）。 </details> <details> <summary><b>它是否适用于生产环境？</b></summary> 这是一个诚实的 **alpha**：快乐路径和完整的治理循环由通过的门控保护（`scripts/run_gates.sh`）。尚未针对多用户/生产环境进行强化。 </details> ## 🗺️ 路线图 - 🛰️ **跨界面同步** — 从 ChatGPT / Claude 网络和移动版连接；一个跨 CLI，浏览器和手机的内存。 - 🔗 关系图 (`SOLVES` / `SUPERSEDES` / `CONTRADICTS`) 实现更丰富的推理。 - 🐧 Linux/Windows 服务安装程序（已实现；设备端测试完成）。 ## 🤝 贡献 欢迎提交问题和 PR。在提交前运行 `scripts/run_gates.sh` 和 `python3 -m unittest discover -s tests` — 所有门控必须保持绿色。 ## 📜 许可 **Elastic License 2.0** — 参见 [LICENSE](./LICENSE)。您可以免费使用、修改、自行托管和重新分发尤格德拉西尔。您 **不能** 将其作为产品出售或向他人提供托管/管理的服务。它是源代码可用 — 而不是 OSI 开源。