Yggdrasil 是一款为 AI 编码智能体提供持久记忆的本地优先工具，通过 MCP（模型上下文协议）向智能体暴露记忆能力。它的目标是解决“每次新会话 AI 都忘掉项目背景，用户要反复解释”的问题。
用途与定位
Yggdrasil 为 Claude Code、Codex、OpenCode 以及其他任何 MCP 宿主的智能体提供一份共有记忆：新会话开启后，无论使用哪个工具、哪个项目，智能体都能知道此前做出的决定、遇到的故障以及仍待处理的事项。它本身不是智能模型，而是“记忆 + 工具”层，负责在合适时机把合适的记忆送到智能体面前，智能仍来自用户所使用的 LLM。
主要能力
- 持久记忆：决策、经验教训与项目状态可跨会话保留。
- 一个大脑多工具共用：Claude Code、Codex、OpenCode 及任意 MCP 宿主共享同一份记忆。
- 跨项目召回：可提示“这看起来像你在项目 B 做过的，要复用吗”。
- 精挑细选而非全量捕获：智能体只保存少数关键内容，治理机制负责去重与归档，从不删除。
- 可选自维护：可选择让一个小型本地模型在后台整合记忆，不消耗 API token。
- 统一身份：可选设置名称与人设，让各智能体表现一致。
- 100% 本地：记忆保存在本机，无云、无账号、无遥测。
使用方式
在 Claude Code 中通过两条命令安装（插件借助 uv 启动）：ygg install 是一次性引导设置，会安装常驻后台服务，向它检测到的每个智能体宿主（Claude Code、Codex、OpenCode）注册 MCP 工具，并在硬件允许时推荐可选的本地模型（也可选择不装以保持零配置）。OpenCode 需先安装再运行 ygg install（若已设置过则用 ygg redeploy），条目会被写入并合并到已有的 opencode.json。若工具没有显示，可运行 ygg doctor 诊断。
引擎首次使用时懒启动并生成自己的本地 token，无需 API key、无需云端、无需配置。也可用一次性数据库试用：uvx --from yggdrasil-memory ygg serve --reset --db /tmp/ygg.sqlite。日常使用中，可对智能体说“recall what we decided about this project”或“remember this decision”，下个会话即可召回。
若已有历史，可据现有 Claude Code 与 Codex 对话记录、Obsidian 库和 CLAUDE.md 仓库在本地提炼种子记忆（ygg seed 等）。从其他记忆工具迁移可用 ygg import --from mcp-memory --path memory.json 导入（自动去重、带密钥保护）。
工作机制
智能体可见六个 MCP 工具：ygg_health、ygg_bootstrap、ygg_search、ygg_recall、ygg_remember、ygg_materialize，由插件或 ygg install 自动注册。
- 常驻守护进程：一个极小的本地服务（约 21 MB 内存），智能体通过 MCP 工具访问。
- 钩子：会话开始时自动注入身份、项目状态与待办（约 300 token）；可选每轮提示钩子自动召回与当前请求相关的记忆。
- 排序：置顶与被频繁召回的记忆优先浮现。
- 治理：重复与冲突进入待审队列，变更非破坏性（归档而非删除）。
- Obsidian：每条记忆同时是一条纯 Markdown 笔记，可读、可编辑、可 grep。
记忆层级与可选模型
默认以 SQLite + FTS5 运行，零依赖、即时关键词搜索，不下载任何模型。可选本地模型提供两个独立层级：嵌入（语义搜索）与后台整合（小 LLM）。运行时只负责计算向量与运行后台模型，所有记忆与向量都保存在同一个本地 SQLite 中。ygg install 会扫描 Ollama、LM Studio 和 llama.cpp，询问是否启动已安装但空闲的服务，并按任务给出菜单（绿色表示已有模型，红色表示需下载），选定后自动写入 embed_backend、embed_url 与 distill_url。ygg recommend 可只扫描与查看目录而不做改动。
也可接入 OpenAI 兼容的 /v1/embeddings 服务（如 llama.cpp 的 llama-server --embeddings、OpenRouter、LM Studio、vLLM），密钥保存在 ~/.yggdrasil/embed_api_key（0600 权限），以文件路径形式传给守护进程，不会出现在 ps、launchd plist 或 systemd unit 中，ygg config list 会对其打码。
文中还给出若干接线注意点：embed_url 用的是 /v1 基址而 distill_url 用主机根地址，两者互换会得到 404；LM Studio 的模型 id 与下载名不同，应询问服务器而非猜测；需开启即时（Just-In-Time）模型加载与登录时启动服务器；OpenRouter 应使用推理 key 而非 provisioning key，并注意隐私设置会过滤模型。
质量取舍上有实测数据：在 232 条记忆、110 条查询的语料上，本地 paraphrase-multilingual 的 recall@1 为 0.964，略高于免费托管模型的 0.946；向量维度更大并不必然更准（mxbai-embed-large 1024 维 0.809，nomic-embed-text 768 维 0.818），真正影响准确性的是模型是否支持你的语言——两款英文模型在跨语言查询上跌至 0.40–0.45，而多语言默认模型保持 0.95。
评测由 eval/ygg_eval.py 产出：项目内检索（常用路径）recall@1 为 0.94，recall@3 为 1.00；全库无过滤检索更难（recall@1 0.72，recall@3 0.87）。零依赖词法模式已能解决关键词与代码标识符查询（1.00），本地模型补充语义与跨语言能力（跨语言 0.25 → 0.95）。完整细节见 BENCHMARKS.md，可用 python3 eval/ygg_eval.py --report . 复跑。
适用场景
- 需要在多个 AI 编码工具间共享项目记忆的开发者。
- 重视数据隐私、希望记忆完全留在本机或局域网的用户。
- 希望长期项目上下文跨会话延续、但不想被全量捕获式记忆污染上下文的场景。
- 需要从既有对话记录、Obsidian 库、CLAUDE.md 仓库提炼种子记忆的用户。
- 需要把精选记忆导出回 AGENTS.md / MEMORY.md，使新克隆或无本工具的协作方也能获得上下文的场景。
限制与状态
项目处于 Alpha 阶段，正常路径与治理循环已有门禁测试（scripts/run_gates.sh），但尚未针对多用户或生产环境加固。目前支持 macOS；Linux/Windows 服务安装器已构建并处于最终真机测试中。未来路线包括跨端同步、关系图（SOLVES / SUPERSEDES / CONTRADICTS）以及 Linux/Windows 正式支持。写入是刻意的：检索自动、写入由智能体显式调用 ygg_remember，不做全量捕获。默认纯词法搜索零依赖即时可用，语义搜索为可选且需本地 Ollama 模型。引擎空闲时约 21 MB 内存、近 0% CPU，磁盘每条记忆数十 KB；会话开始注入约 300 token。记忆会物化为 Obsidian 库中的 Markdown 笔记，可像普通文件一样编辑或删除，引擎从不硬删除而是归档（可逆）。项目采用 GNU AGPL v3.0 许可，免费开源，可自托管、修改与再分发，但修改或作为网络服务提供时须以同一许可发布源码。
关于跨项目召回、身份人设配置、局域网蒸馏服务器、与其他记忆工具（如 claude-mem、mem0、context-mode、Context7）的对比等细节，官方资料均有说明，可参阅仓库文档。
