Yggdrasil

🌳 Yggdrasil

别再每次开启新的 AI 会话时，都重新解释你的项目。
为 Claude Code、Codex 和所有 MCP Agent 提供一份本地记忆，供不同会话、工具和项目共享。零依赖。数据绝不离开你的设备。

安装 · 工作原理 · 数据 · 对比 · 常见问题

阅读其他语言版本：Русский · 简体中文 · Español · Français · 日本語 · Deutsch

每次开启新聊天，AI 都会忘记一切。你不得不在每次使用每种工具时，重新解释项目、决策和注意事项。**Yggdrasil 是一份轻量、始终运行的记忆，任何 Agent 都能接入。**在任何项目中使用任何 AI 开启新会话，它都能立即了解你做出的决策、遇到的问题，以及尚未解决的事项。

$ cd ~/projects/checkout-api && claude        # a brand-new session

🌳 Yggdrasil  (injected automatically at session start)
   • [project_status] payments refactor: idempotency keys added; open: e2e tests
   • [lesson] webhook 401 → signing secret rotated; update env + redeploy

> "have I solved a flaky websocket reconnect anywhere before?"

🌳 recall → found in project `realtime-dash`:
   refresh the token *before* opening the socket, then retry with capped backoff.

再也不用说“让我提醒你昨天做了什么”。它就在那里。

🚀 安装

在 Claude Code 中运行两条命令（插件通过 uv 启动）：

/plugin marketplace add VonderVuflya/Yggdrasil
/plugin install yggdrasil

引擎会在首次使用时延迟启动，并生成自己的本地令牌——无需 API 密钥、云服务，也无需任何配置。Codex 和 Cursor 使用相同的流程。

opencode mcp list        # -> ✓ yggdrasil connected

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yggdrasil": {
      "type": "local",
      "command": ["/path/to/python3", "~/.yggdrasil/scripts/ygg_mcp_server.py"],
      "enabled": true,
      "environment": { "YGG_ENGINE_URL": "http://127.0.0.1:42069" }
    }
  }
}

然后就可以开始工作了：让 Agent “回忆一下我们对这个项目做了什么决定”，告诉它*“记住这个决定”*——下次会话中，这些内容就已经在那里了。随时运行 ygg doctor 验证安装情况。

已有历史记录？ 从现有的 Claude Code 和 Codex 对话记录、Obsidian 库以及 CLAUDE.md 仓库中提取记忆——整个过程都在本地完成：

ygg seed --dry-run    # see what it would import; drop the flag to distill for real

要从其他记忆工具迁移？ ygg import --from mcp-memory --path memory.json 会将其中的全部数据导入 Yggdrasil（自动去重并防护机密信息）——之后你就可以删除原工具了。

为什么选择它

• 🧠 持久保存 — 决策、经验和项目状态会跨会话保留。
• 🔌 一个大脑，适用于每种工具 — Claude Code、Codex、OpenCode 和任何 MCP 宿主都共享同一份记忆。
• 🌐 跨项目回忆 — “这看起来和你在项目 B 中做过的事情很像——要复用吗？”
• 🧹 精选，而非全盘记录 — 你的 Agent 只保存少数重要内容；治理机制会去重和归档，但绝不删除。
• 🌱 自我维护 (可选) — 一个小型本地模型会在后台整理记忆。无需 API 令牌。
• 🪪 统一身份 — 可选的名称和角色设定会被每个 Agent 采用，让 Claude Code 和 Codex 感觉就像同一个助手。
• 🔒 100% 本地 — 你的记忆保存在自己的设备上。没有云服务、账户或遥测数据。

🧠 工作原理

Yggdrasil = 记忆 + 工具，智能来自你的 LLM。它只负责确保在正确的时机，将正确的记忆提供给正确的 Agent。

• 🛎️ 始终运行的守护进程 — 一个小型本地服务（约占用 21 MB RAM），你的 Agent 可通过 MCP 工具（ygg_search、ygg_recall、ygg_remember …）访问它。
• 🪝 钩子 — 会话开始时自动注入身份信息、项目状态和待跟进事项（约 300 个 token）；可选的逐提示词钩子会自动召回与每个请求相关的记忆。
• 📌 排序 — 置顶和经常召回的记忆会优先显示。
• 🧹 治理 — 重复和冲突内容会进入审核队列；更改不会造成破坏（只归档，绝不删除）。
• 📓 Obsidian — 每条记忆也都是一份纯 Markdown 笔记，可供你阅读、编辑和搜索。

🎛️ 记忆层级——默认零配置

开箱即用时，Yggdrasil 使用 SQLite + FTS5，无需任何依赖——即时关键词搜索，无需模型，也无需下载。可选的本地模型可增加两个独立层级：

运行时只会计算向量并运行后台模型——所有记忆和向量都保存在同一个本地 SQLite 数据库中。

ygg install 会扫描 Ollama、LM Studio 和 llama.cpp，提供启动已安装但处于闲置状态的运行时，然后针对每项任务显示一个菜单：绿色表示你已有的模型，红色表示需要下载的模型。选择一项后，它会替你写入 embed_backend、embed_url 和 distill_url——包括那个没人能猜对的细节：embed_url 需要以 /v1 结尾，而 distill_url 需要指向主机根目录。在另一台机器上运行的运行时只需一个 URL：粘贴后即可自动检测接口类型。ygg recommend 会显示相同的扫描结果和完整目录，但不会更改任何设置。

# local llama.cpp — no key needed
ygg config set embed_backend openai
ygg config set embed_url http://127.0.0.1:8080/v1
ygg config set embed_model bge-small-en-v1.5
ygg redeploy

# OpenRouter — free embeddings, no GPU needed
ygg config set embed_backend openai
ygg config set embed_url https://openrouter.ai/api/v1
ygg config set embed_model nvidia/llama-nemotron-embed-vl-1b-v2:free
ygg config set embed_api_key sk-or-...    # or export YGG_EMBED_API_KEY
ygg redeploy

✓ dense    active (nvidia/llama-nemotron-embed-vl-1b-v2:free)

同时使用笔记本和性能更强的机器？配对一次，它们就不再是两个独立的大脑。

# on the laptop
$ ygg link
🔗 pairing code   valid 5 minutes · single use

    ygg://192.168.3.152:42070/a4e0df489737#FOucjgJ1FrUB…

# on the other machine — paste it
$ ygg link ygg://192.168.3.152:42070/a4e0df489737#FOucjgJ1FrUB…
  ✓ linked with laptop   https://192.168.3.152:42070
  ✓ laptop: fetch 84 · push 12 · delete 0 · tombstones 0

就这么简单。从此，在一台机器上写入的记忆大约一秒后就会出现在另一台机器上；执行 ygg delete 会从两台机器上删除记忆；即使另一台机器处于休眠状态，每台机器也能使用自己的本地副本继续工作——读取绝不会等待网络。机器重新上线时，会比较指纹并修复所有遗漏，无需你执行任何操作。

不会轮询。 Yggdrasil 每天只会被调用几次，因此写入会即时推送，读取会触发同步；空闲机器不会发送任何内容。

这不是云服务： 没有中继、没有账户，也没有我们的服务介入通信。机器通过你自己的网络直接互连，使用 TLS，并固定对方的证书；密钥对只存在于这两台机器上。配对码本身会标明签发机器的证书，因此即使是首次连接，也会经过验证——网络上的其他设备若冒充对方响应，会在发送配对码密钥之前被拒绝。只有运行 ygg link 后才会绑定网络端口——安装 Yggdrasil 后，它仍与之前一样只监听本地回环接口。

ygg link --list          # what's linked, and whether writes are actually arriving
ygg link --sync          # reconcile now, don't wait for a read
ygg unlink <name>        # revoke that machine's key here

使用 eval/ygg_eval.py 测得：232 条记忆、110 个带标签的查询；排序权重仅在 dev 划分上调优，因此 holdout 是无偏的指标（recall@1，使用 paraphrase-multilingual 模型）：

在一个项目内——也就是你实际使用的路径——0.94 的查询中，正确的记忆排名第 1，且每次都在前 3 名内（recall@3 = 1.00）。 不加筛选、搜索整个存储库更难（全部 232 条记忆的 recall@1 为 0.72，recall@3 为 0.87）。零依赖词法模式已能处理关键词和代码标识符查询（1.00）；本地模型则能理解语义并支持跨语言搜索（跨语言查询从 0.25 提升至 0.95）。BENCHMARKS.md 中的完整细分数据包含 95% 置信区间、候选池大小和各类别得分——一分钟即可重新运行：python3 eval/ygg_eval.py --report。

语料库大小也是指标的一部分。 在一个包含 4,799 条记忆的真实存储库中，默认的多语言嵌入器会退化至词法基线（recall@1 为 0.55）；bge-m3 在此规模下仍能达到 0.775。如果你的存储库增长到数千条，请选择 bge-m3——详情见 BENCHMARKS.md。

🆚 Yggdrasil 与其他方案对比

其他方案要么自动捕获对话记录，要么向你兜售云服务。Yggdrasil 的选择是：只保留少量重要内容，经过整理去重，以你拥有的纯文本行存储，并在所有工具和项目之间共享。

最接近的同类方案——claude-mem： 捕获所有内容的记忆系统，会记录并由 AI 压缩每次会话（需要 Node 20+ 和 Bun、持久运行的 worker 守护进程；Chroma 可选）。Yggdrasil 选择了相反的方向：小而精、信号密集的存储库，而不是不断扩大的信息洪流。mem0 是一套 SDK 加托管平台，用于构建能记住用户的应用——即使自托管，也需要大模型 API 密钥。内置记忆确实很有用——但在结构上受限于单一供应商、单个代码仓库和单台机器，且只能进行字面 grep。Yggdrasil 是它们之上的一层（而且 ygg seed 可以从相同的对话记录中为自身建立初始数据）。它们处于完全不同的层级：context-mode（实时上下文窗口）和 Context7（最新库文档）都能与 Yggdrasil 良好配合。

🧰 命令

Agent 可以使用六个 MCP 工具：ygg_health、ygg_bootstrap、ygg_search、ygg_recall、ygg_remember、ygg_materialize——由插件或 ygg install 自动注册。

{ "name": "Jarvis", "persona": "concise, proactive, dry wit", "user_facts": ["prefers TypeScript", "ships small PRs"] }

🚦 状态与路线图

Alpha。 主流程和治理循环已通过门禁测试（scripts/run_gates.sh）；目前尚未针对多用户或生产环境进行加固。目前支持 macOS；Linux/Windows 服务安装程序已构建完成，正在进行最终的设备端测试。

近期已交付：🔗 机器间记忆（ygg link）· 关系图（ygg relate：solves / supersedes / contradicts）。

接下来：🛰️ 跨界面支持（在命令行、Web 和手机之间共用一份记忆——HTTP 门面已就绪，详见 docs/cross-surface.md）· 🐧 Linux/Windows 正式发布。

🤝 参与贡献

欢迎提交问题和 PR。提交前请运行 scripts/run_gates.sh 和 python3 -m unittest discover -s tests——所有门禁都必须通过。

📜 许可证

GNU AGPL v3.0——详见 LICENSE。免费开源：可使用、修改、可自托管和再分发。如果你修改了它，或将其作为网络服务提供，则必须以相同许可证发布源代码。