yadgar

<div align="center"> <img src="docs/assets/yadgar.svg" alt="yadgar logo" width="320"> [](https://www.python.org/) [](LICENSE) </div> [更新日志](docs/CHANGELOG.md) · [性能基准](#benchmark) · [架构](#architecture) · [路线图](#roadmap) · [JS/TS SDK](docs/reference/sdk-js.md) · [代理指南](AGENTS.md) > **AI 编程代理：** 操作指南位于 [`AGENTS.md`](AGENTS.md) — 设置命令、开发环境、测试运行器、代码风格、拉取请求规则、安全门控。本 README 是人类概述。 > **为什么该仓库存放在 GitHub（从 Codeberg 迁移，2026 年）：** Codeberg 的 [更新使用条款](https://codeberg.org/Codeberg/org/commit/71149c7fc95ccfeae36109b5cddca339e4aa1473) — § 2 (1) 7，在 *"提案集会 2026：禁止 LLM-外延"* （2026-06-29）中添加 — 现要求人们 **不** 托管主要由“生成式 AI”工具编写的项目。Yadgar 使用大量 AI 代理协助构建，并对此保持公开，因此它不再符合 Codeberg 的托管政策，因此迁移到此处。没有恶意 — Codeberg 是人类编写的自由软件的优秀托管平台；这是基于政策的决定，而不是其他原因。 **MCP 客户端的持久记忆引擎。** 告诉它重要的事情，它会跨会话保存 — 衰减你停止关注的内容，促进重复出现的内容，过滤回忆到你所在的 git 分支，并将每个记忆与一个精选的 wiki 配对，后者通过相同的排名管道进行搜索。 > **支持的客户端：** 一个共享的流式 HTTP 守护进程（`http://127.0.0.1:8765/mcp`）为所有 9 个支持的客户端提供记忆和 wiki MCP 接口：`claude-code`、`codex`、`gemini`、`cursor`、`cline`、`windsurf`、`kiro`、`amp`、`opencode`。Claude Code 另外获得完整的综合集成（钩子、任务列表镜像、CLAUDE.md 同步）。所有其他客户端接收 MCP 注册和规则文件（等效于 AGENTS.md）。 > > **多客户端设置：** 使用 `yadgar install` 连接任意客户端。注册单个客户端或一次性探测和注册所有检测到的客户端： > > ```bash > yadgar install --client <name> # 例如 --client opencode > yadgar install --auto-detect # 检测 + 注册所有已安装的客户端 > yadgar install --client <name> --print # 预览：输出 JSON 到 stdout，无文件写入 > ``` > > `--print` 是 nix/home-manager 契约（任务 #67）：它输出完整的配置而不触摸文件系统，适合声明式激活。每个平台的详细信息和标志参考：[`docs/reference/install.md`](docs/reference/install.md)。 *Yadgar*（یادگار）是波斯语中“纪念物，纪念品”的意思。 --- ## 它是什么 Claude Code 在会话结束时、`/clear` 或上下文压缩时忘记所有内容。Yadgar 是记住的层。它作为 [MCP](https://modelcontextprotocol.io/) 服务器与 Claude Code 一起运行，并为其提供两个持久存储： 1. **记忆** — 情节性和语义事实，每个都带有 `heat` 值，该值随时间推移而衰减。访问使内容加热；不使用则衰减；重复出现的情节通过夜间整合循环提升为语义记忆，该循环模拟大脑睡眠模式。 2. **精选的 wiki** — 长期、版本控制、分支范围的页面：约定、模块用途、过去的决策、子系统位置。内容有意编写，而不是偶然捕获。 单个 `recall()` 查询 **同时搜索两个存储**，融合和重新排序结果，按热量加权，过滤掉衰减的条目，并提升当前 git 分支上的匹配。关键上下文可以被 **锚定** 以使其永远不会衰减；整个工作状态可以被 **检查点** 和 **恢复** 跨越 `/compact`。 ### 为什么 - **跨会话生存。** 热量衰减删除不再使用的内容；惊喜门控删除重复内容；锚点固定必须保留的内容。 - **分支感知。** 回忆功能提升当前分支的匹配；wiki 页面按分支优先级解析（当前 → 默认 → 无作用域），因此规范知识可以从功能工作中访问。 - **统一的排名管道用于记忆 + wiki。** 精选知识和情节记忆通过单个排名结果返回，而不是两个独立的搜索。 - **在您睡觉时巩固。** 每晚的大脑循环衰减热量，促进情节提升为语义记忆，发现因果联系，形成关联联系，并合并重复项 — 而不断开 MCP 连接。 - **自我记录。** 架构决策记录、可重用的代理提示库、综合任务列表镜像和交互式 3D 知识图谱都生活在同一个存储中。 --- ## 主要功能 ### 记忆 - **热量衰减生命周期** — 每个记忆携带 `heat ∈ [0,1]`，指数衰减；访问使内容加热，不使用则衰减，最终过期并被清除。 - **惊喜门控写入** — 相似性门控拒绝近似重复的写入（拒绝进入 DLQ，可通过 `dlq_inspect` 检查）。 - **写入时矛盾检测** — 轻量级否定 + 动作分歧启发式标记矛盾记忆并衰减其置信度，而不阻止写入。 - **锚点** — 保护的记忆永远不会衰减；`audit_anchors()` 查找冗余、超大、过期或近似重复（余弦 ≥ 0.95）的锚点。 - **检查点 / 恢复** — `checkpoint(directory)` 快照工作状态，然后 `/compact`；`restore(directory)` 通过海马体重演混合检查点 + 锚点 + 热点记忆 + 预测上下文重建它。使用 `restore` 而不是 `recall` 来恢复 `/clear` 或 `/compact` 后的状态。 - **记忆块** — 类似 Letta 的命名、作用域、字符限制的核心记忆容器（`block_*`），始终在上下文中。 ### 精选的 wiki - **版本控制页面** — 完整的历史记录（`wiki_history`、`wiki_diff`、`wiki_read_version`、`wiki_restore`）；`wiki_add` 直接提交（无草稿步骤）。 - **分支范围解析** — `wiki_read(slug)` 解析当前分支 → 默认分支 → 无作用域。 - **外科编辑** — 锚文本和位置编辑工具（`wiki_replace_text`、`wiki_insert_before/after`、`wiki_append_section`、`wiki_replace_markdown_block`），以便页面在原地修改，而不是重写。 - **自动链接** — `wiki_autolink` 通过匹配页面标题插入 `[[slug]]` 跨引用；验证后不会制造损坏的引用。 - **仓库 wiki** — `repo_wiki_generate` 通过 AST 扫描（无 LLM）从 Python 仓库构建代码结构页面，直接写入 wiki 存储，并具有 SHA256-奇偶校验陈旧检测。同步助手：`wiki_refresh_stale`、`wiki_cleanup_merged_branches`、`wiki_coverage`、`wiki_lint`。 - **代码图** （可选，默认关闭）— `yadgar code-graph` 调用主机侧到 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) 静态二进制文件（158 种语言树解析器，离线）索引最新的 `origin/<default-branch>` 并将架构 **摘要** 渲染到始终注入的记忆块（无需回忆）。通过 DB 支持的运行时配置存储启用：`yadgar setup --code-graph`（交互式 `[y/N]`，当未传递 `--code-graph`/`--no-code-graph` 时）安装二进制文件并持续 `code_graph.enabled=true`，或随时设置：`config_set("code_graph.enabled", true, scope="global")`；使用 `config_set("code_graph.enabled", false, scope="project", directory=<repo>)` 选择退出单个仓库 — 目录下的 `false` 覆盖全局 `true`。参见 ADR-0162/0163。 - **书签** — 在 viz UI 中固定 wiki 页面（`bookmark_*`）；拖动排序，密集整数位置。 ### 统一回忆 - 单个 `recall()` 查询 **同时检索记忆 + wiki**，通过 WRRF 融合、交叉编码器重新排序、NLI 和 MMR 过滤，并通过规则引擎 — 热量加权、衰减门控、分支范围。按 `type=` 过滤（`"memory"`、`"wiki"` 或两者）。`wiki_query` 仍用于仅 wiki 搜索。 ### 综合任务列表镜像 - `wiki_write_task_list(project, content, directory)` 将 Claude Code 综合任务列表（TaskCreate/TaskList）持久化到 wiki 存储中，以便其在 `/clear` 和会话退出时生存。停止钩子检查点步骤写入它；SessionStart 恢复提示重新注入打开的任务。规范写入路径结构化绑定到 `{project}-task-list` slug。 ### 架构决策记录（ADR） - `adr_add(...)` 编写 ADR wiki 页面（`yadgar-adr-NNNN`），强制执行 11 个字段的模式，具有自动递增的 ID。每个 ADR 都有自己的页面，索引在薄 `yadgar-adr-index` 中；`recall()` 是读取路径（页面可见且永存 — 无衰减）。`adr_get(directory, adr_id)` 获取单个 ADR；`adr_list(directory, status=)` 读取索引并可选地过滤状态。停止钩子提示在会话结束时捕获决策。Yadgar 使用 138 个真实 ADR 来测试其系统。 ### 代理提示库 - 可重用的子代理调度提示，存储为标记的 wiki 页面（`agent-prompt-<pattern>`），随时间推移版本化和改进。`agent_prompt_save(pattern, content, purpose)` 更新单个页面；`agent_dispatch_prelude(pattern)` 构建一个前缀添加到子代理提示 — 回忆优先合同 + 强制 `## Yadgar 发现` 页脚。`seed_agent_prompts()` 播种起始模式。通过标记回忆（`recall(type="wiki", tags=["agent-prompt"])`)查找，保持正常的回忆噪音。 ### 知识图谱可视化（星系） - `yadgar viz` 在 **http://localhost:42069** 提供交互式 3D **星系布局**，包含记忆、wiki 页面、实体和关系。星系空间排列节点：松散的低热量记忆形成外晕，重复的语义簇呈螺旋状形成臂，核心/锚节点形成中央隆起。热量编码亮度。已移除强制定向 / 2D 引擎（ADR-0138）— 星系是唯一的渲染器。 - 功能：可拖动节点弹出窗口、适合/重置星系相机、按节点类型过滤、热量滑块、悬停邻域高亮、搜索、**轨迹重放**（重放 Tempo 的工具轨迹）和**浏览器内配置面板**（系统 → 配置）。 - **预计算服务器端布局**（无条件）：夜间/完整周期计算 3D 节点位置，签名缓存它们，`/api/graph` 提供预计算的坐标。在种子丢失时，客户端运行冷布局。 - UI 组织成四个菜单：**图谱** · **书签** · **系统** {配置、健康、统计} · **帮助** {指南、配置参考、关于、调试}。 ### 只读 DB 检查（`db_inspect`） - `db_inspect(query, params, limit)` 对只读查看器客户端（`YADGAR_RO_PASS`）执行 SurrealQL SELECT， 由 `YADGAR_DEBUG_APIS_ENABLED` 控制。不能从此界面进行写入（ADR-0132）。核心转发到后端 `/api/debug/read_query` 端点。 ### 夜间整合（“大脑循环”） 在维护模式下（无 MCP 重新连接）时夜间运行。阶段： `apply_decay → process_episodes → merge_duplicates → link_similar → detect_causality → memify → cls_consolidation` 加上梦/睡眠阶段。 - **CLS 提升** — 重复出现的情节模式提升为语义记忆（补充学习系统）。 - **因果发现** — PC 算法因果-DAG 推理超过共现记忆。 - **梦境重放** — 联想 `co_occurrence` 链接 + 洞察生成；洞察上限 21 天如果未访问。 - **社区检测** — 图谱聚类显示为星系中的集群。 - 过时记忆重新嵌入；预计算星系图谱布局。 ### 配置系统 - [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)，优先级 **环境变量（`YADGAR_*`）> `~/.config/yadgar/config.yaml` > 默认值**。 - **系统 → 配置** 是浏览器内的编辑器（viz UI 的一部分）：分类分组的旋钮、按字母排序、悬停提示、`ⓘ` 深入链接到配置参考页面，以及显示环境变量 / 配置文件 / 默认来源的 SOURCE 徽章。写入由 bearer-auth 保护。 ### 安全性和可观察性 - **Bearer-token MCP 身份验证** 在 `/api/*`、`/hooks/*`、`/mcp` — 默认拒绝 CORS、时间安全比较、仅限环回，默认情况下。`/health` 和 `/metrics` 在环回时豁免。 - **始终开启的秘密门控** 阻止 AWS / GCP / Stripe / Slack / OpenAI / Anthropic 密钥、JWT、GitHub PAT、私钥和 DB URI 在到达存储之前（无法禁用；上下文感知白名单用于已知-good 夹具）。 - **自动捕获净化** 在动作日志插入前剥离 ANSI 转义、控制字符和 Unicode 双向覆盖。 - **Prometheus `/metrics`** + OpenTelemetry 分布式跟踪跨核心 + 后端（核心→后端 W3C traceparent 加入一个跟踪 Tempo）；结构化 JSON 日志；每个阶段的整合持续时间标记。**三信号标准**（v5.101，ADR-0034）：范围内每个函数通过 `@observe` 装饰器发出 span+metric+log，I33 覆盖率检查。 - **异步写入队列** （文件队列，ADR-0075）带有重试/退避、死信队列永久失败和 DLQ 检查工具（`dlq_inspect`、`dlq_requeue`、`dlq_dismiss`）。 --- ## 架构 ``` ┌──────────────┐ MCP（流式 HTTP / stdio） ┌──────────────────────────────┐ │ Claude Code │ ◄────────────────────────────────────────── ►│ yadgar/core (:8765) │ │ + 钩子 │ 记忆 / 回忆 / wiki_* / 检查点 … │ MCP 服务器（薄路由器） │ └──────────────┘ │ 认证 · 规则 · 钩子 · 可视化 │ └────────────┬─────────────────┘ │ HTTP + 文件队列 ┌────────────▼─────────────────┐ │ yadgar/_shared │ │ 配置 · 存储契约 │ │ 可观察性 · 安全 │ └────────────┬─────────────────┘ │ HTTP ┌────────────▼─────────────────┐ │ yadgar/backend │ │ SurrealDB 存储 (:8000) │ │ 嵌入 + 重新排序 (:8001) │ │ 检索管道（POST /recall） │ │ 整合计算 │ └──────────────────────────────┘ ``` 三个物理层（ADR-0056 / ADR-0060 / ADR-0062）： - **yadgar/core** — MCP 服务器（FastAPI）。路由工具调用；通过 `POST /recall` 将回忆转发到后端。无重计算。 - **yadgar/_shared** — 契约、配置（pydantic-settings）、存储客户端、可观察性（`@observe`）、安全门控。无直接 MCP 工具代码。 - **yadgar/backend** — SurrealDB（`:8000`）+ 嵌入/重新排序服务（`:8001`）。拥有完整的检索管道、整合计算和异步写入排水器。ML 模型被烘焙到后端镜像（ADR-0101）。 **写入路径（ADR-0075）：** MCP 工具 → 核心 → 文件队列（`YADGAR_QUEUE_BASE=/data/queue`）→ 后端排水器 → SurrealDB。默认情况下写入是异步的；`wait=True` 阻塞直到排水器提交。 **回忆路径（ADR-0044）：** `recall()` 在核心中是一个薄转发器 → 后端 `POST /recall` 运行完整管道（FTS + KNN + PPR + 扩散激活 → WRRF 融合 → Ettin-32m CE 重新排序 → NLI → MMR →对抗 → 规则）。分支过滤器（`branch IN (current, default, NULL)`）和当前分支提升在获取后应用。 更详细：[docs/reference/architecture.md](docs/reference/architecture.md) · [docs/reference/retrieval.md](docs/reference/retrieval.md) · [docs/reference/memory-lifecycle.md](docs/reference/memory-lifecycle.md)。 **层文档（树内）：** 每个层根目录都带有 `README.md`（子系统映射）和 `AGENTS.md`（编码代理放置律） — [`yadgar/_shared/`](yadgar/_shared/README.md) · [`yadgar/backend/`](yadgar/backend/README.md) · [`yadgar/core/`](yadgar/core/README.md）。 ## 安装 在主机上安装Python 3.14+（或使用Docker/Compose路径，主机Python为零）。所有路径都达到相同的`yadgar setup`安装后步骤。 **pipx（推荐独立安装）：** ```bash pipx install yadgar yadgar setup ``` **Nix flake：** ```bash nix profile install github:m-agahi/yadgar yadgar setup ``` **普通pip：** ```bash pip install yadgar yadgar setup ``` **仓库检查（开发）：** ```bash git clone https://github.com/m-agahi/yadgar.git cd yadgar make setup # 安装 + 钩子 + 代理 + 单元 + 种子锚点 ``` `yadgar setup`写入`~/.config/yadgar/config.yaml`，生成`~/.config/yadgar/secrets.env`（chmod 600）并包含随机`YADGAR_MCP_AUTH_TOKEN` + `SURREAL_PASS` + `YADGAR_RW_PASS` + `YADGAR_RO_PASS`，安装Claude Code钩子和子代理模板 + 规则，种子锚点，并准备systemd（Linux）或launchd（macOS）用户单元。幂等 - 升级后重新运行。 然后启动守护进程并将其注册到Claude Code： ```bash set -a && . ~/.config/yadgar/secrets.env && set +a yadgar daemon start yadgar daemon configure-mcp # 写入 ~/.claude.json 并包含 Authorization: Bearer 头 ``` 重启Claude Code，然后验证： ```bash yadgar daemon status yadgar stats ``` 平台详细信息：[`docs/reference/install.md`](docs/reference/install.md). ### 仅限stdio（无守护进程，无Docker） 单会话使用。跳过`yadgar setup`。添加到`~/.claude.json`： ```json { "mcpServers": { "yadgar": { "command": "yadgar", "args": [] } } } ``` 重启Claude Code。无承载身份验证；嵌入/重新排序在无后端的情况下优雅地降级。注意：已安装的守护进程默认使用可流式HTTP传输；stdio模式用于单会话/无Docker使用。 ### Docker Compose（生产推荐） 两个容器 - 后端（SurrealDB + 嵌入/重新排序服务）和核心（MCP服务器）。独立版本跟踪。 ```bash # 源秘密 set -a && . ~/.config/yadgar/secrets.env && set +a docker compose up -d ``` docker-compose文件（`docker-compose.yml`）定义： - **`yadgar-backend`** - `openfantasy/yadgar-backend:5.55.0`，SurrealDB在`:8000` + 嵌入/重新排序在`:8001`。挂载`yadgar-db-data`（只读）和`yadgar-queue-data`（文件队列，`YADGAR_QUEUE_BASE=/queue-data`）。 - **`yadgar-core`** - `openfantasy/yadgar:5.149.0`，MCP服务器在`:8765`。在`/data`处挂载`yadgar-queue-data`（共享文件队列）。依赖后端健康检查启动。 知识图可视化UI **不是** compose服务的一部分。在主机上运行`yadgar viz`以启动`http://localhost:42069`的可视化服务器 - 它反向代理`/api/*`到`:8765`的守护进程。 然后注册到Claude Code： ```bash yadgar daemon configure-mcp ``` > 注意：有关手动`docker run`路径或基于systemd的生产部署，请参见[`docs/reference/install.md`](docs/reference/install.md)。上面的docker-compose文件是推荐的开发/生产路径。 ### 更新 ```bash yadgar update --check # 探测PyPI；打印升级命令；退出0 ``` 对于`pipx`，建议的命令是`pipx upgrade yadgar`；然后重新运行`yadgar setup`（幂等）以刷新钩子和单元。可选的更新编排器（`yadgar update --install`，默认关闭，通过`update.install_enabled: false`）协调快照→镜像拉取→温和排空→重启→健康检查→CLI升级，并具有自动回滚（`yadgar update --rollback`）。参见`MIGRATION_NOTES.md`. --- ## 常用命令 ### 设置/安装 ```bash yadgar setup # 首次运行：配置、秘密、钩子、单元 yadgar install-hooks # （重新）连接Claude Code钩子 + 承载令牌 yadgar install-subagents # 安装子代理模板 yadgar daemon configure-mcp # 写入 ~/.claude.json 并包含流式HTTP + 承载头 yadgar seed <directory> # 为现有项目引导内存 ``` ### 日常使用 ```bash yadgar daemon start|stop|status|logs|health # 管理后台守护进程 yadgar viz # 在 http://localhost:42069 启动知识图可视化界面 yadgar stats [--project /path] # 内存计数 + 健康状况 yadgar daemon restart # 配置更改后重启 ``` ### 维护/备份 ```bash yadgar vacuum # 紧凑的SurrealKV存储 yadgar export duckdb --output snap.duckdb # 分析快照（需要yadgar[analytics]） yadgar config set <key> <value> # 更改配置旋钮（也可以在viz System→Config中编辑） yadgar config list # 显示所有配置旋钮及其当前值 yadgar update --check # 检查PyPI的新版本 yadgar update --install # 协调升级（快照→拉取→重启→验证） ``` ### 调试 ```bash yadgar daemon logs # 尾随守护进程容器日志 yadgar daemon health # 检查 /health 端点 yadgar --version # 核心 + 后端 + 守护进程版本 yadgar config get YADGAR_LOG_FORMAT # 检查单个旋钮 # MCP级别：dlq_inspect() · audit_anchors() · check_invariants() · db_inspect("SELECT ...") ``` --- ## CLI ``` yadgar # MCP服务器（默认流式HTTP）；--transport {sse,streamable-http} yadgar daemon start|stop|logs|health|status|restart yadgar daemon configure-mcp # 写入 ~/.claude.json 并包含承载头 + 流式HTTP传输 yadgar daemon install-service # 安装systemd / launchd单元 yadgar setup # 首次配置 + 秘密 + MCP代码段 yadgar stats [--project /path] # 内存统计 yadgar viz # 知识图在 http://localhost:42069 yadgar vacuum # 紧凑的SurrealKV存储 yadgar seed <directory> # 为现有项目引导内存 yadgar repo-wiki <directory> # 生成代码结构wiki页面 yadgar code-graph index|query|refresh <repo> # 主机端多语言代码结构（可选；MCP config_set code_graph.enabled=true） yadgar rules export|import # 策略规则 yadgar config init|list|get|set # 配置 yadgar update --check|--install|--rollback yadgar export duckdb --output snap.duckdb # 分析快照（pip install yadgar[analytics]） yadgar install-hooks|install-subagents # 连接Claude Code钩子 + 代理模板 yadgar restore <directory> # （钩子内部）恢复上下文后压缩 yadgar capture # （钩子内部）轻量级动作捕获 yadgar drain # （钩子内部）刷新文件队列 yadgar context # （钩子内部）会话启动上下文注入 ``` --- ## MCP工具 Yadgar公开了**约79个MCP工具**（不包括仅限测试的存根）。⚡️标记`power=True`工具（在最小MCP配置文件中 gated）。 <details><summary><b>内存</b></summary> | 工具 | 权力 | 目的 | |---|:---:|---| | `memorize(content, context, tags)` | | 存储记忆；自动捕获分支 + 惊喜门 | | `recall(query, type, max_results)` | | 统一的分支感知搜索，涵盖内存 **和** 维基 | | `recent_memories()` | | 最新列表，无分类器依赖 | | `memory_get(id)` | | 按数字ID获取 | | `memory_update(id, fields)` | ⚡️ | 补丁`content` / `tags` / 标志 | | `forget(id)` | | 标记为删除 | | `anchor(content, context, reason)` | ⚡️ | 保护记忆；永不衰减 | | `checkpoint(directory, …)` | ⚡️ | 快照预压缩 | | `restore(directory)` | ⚡️ | 重建后压缩（海马体重放） | | `memory_stats()` | | 健康 + 计数 | | `validate_memory()` | ⚡️ | 检查当前文件状态的有效性 | </details> <details><summary><b>维基</b>（核心 + 编辑 + 维护）</summary> 核心：`wiki_add` · `wiki_read` ⚡️ · `wiki_query` · `wiki_list` ⚡️ · `wiki_get` · `wiki_update` ⚡️ · `wiki_delete` ⚡️ · `wiki_history` · `wiki_diff` · `wiki_read_version` · `wiki_restore` ⚡️ · `wiki_check_duplicate` · `wiki_lint` ⚡️ 编辑：`wiki_append_section` ⚡️ · `wiki_replace_text` ⚡️ · `wiki_delete_text` ⚡️ · `wiki_insert_before/after` ⚡️ · `wiki_replace_at` / `wiki_delete_at` / `wiki_insert_at` ⚡️ · `wiki_replace_markdown_block` ⚡️ · `wiki_autolink` ⚡️ · `wiki_set_metadata` ⚡️ 维护：`wiki_coverage` · `wiki_refresh_stale` ⚡️ · `wiki_cleanup_merged_branches` ⚡️ · `repo_wiki_generate` **任务列表镜像：** `wiki_write_task_list(project, content, directory)` — 规范写入限定为 `{project}-task-list` slug；由 stop-hook checkpoint（步骤 4）使用。 > `wiki_add` 直接提交 - 没有草稿/批准工作流。草稿工作流工具（`wiki_drafts`、`wiki_approve`、`wiki_discard`）已在 v5.157.0 中删除（修复 #76）；没有生产路径曾经产生草稿。 </details> <details><summary><b>书签和区块</b></summary> 书签：`bookmark_add` · `bookmark_remove` · `bookmark_list` · `bookmark_reorder` 区块（Letta-style核心内存，均 ⚡️）：`block_create` · `block_get` · `block_update` · `block_delete` · `block_list` · `block_replace` · `block_append` </details> <details><summary><b>项目状态</b></summary> | 工具 | 权力 | 目的 | |---|:---:|---| | `project_brief(directory, mode)` | | 分层引导 — `signals`（<100 tok），`restore`（~800 tok），`catalog`（~500 tok），`full`（~1050 tok） | | `bootstrap_project(directory, content)` | ⚡️ | 设置 `_project_init` | | `update_active_work(directory, content)` | ⚡️ | 原子替换 `_active_work` | | `seed_project(directory)` | ⚡️ | 从README + 顶级文档引导内存 | | `install_hooks(scope)` | ⚡️ | 连接Claude Code钩子；注入承载令牌 | `get_project_context()` 是 `project_brief(mode="catalog")` 的废弃别名。 </details> <details><summary><b>ADR系统</b></summary> | 工具 | 权力 | 目的 | |---|:---:|---| | `adr_add(directory, title, context, decision, …)` | ⚡️ | 将11字段ADR追加到每个项目的索引；写入 `{project}-adr-NNNN` 维基页面 | | `adr_get(directory, adr_id)` | ⚡️ | 通过ID获取单个ADR页面（例如 `"ADR-0042"`） | | `adr_list(directory, status=)` | ⚡️ | 读取索引；可选状态过滤器（`"open"`、`"accepted"`等） | </details> <details><summary><b>代理提示库</b></summary> | 工具 | 权力 | 目的 | |---|:---:|---| | `agent_dispatch_prelude(pattern, task_topic)` | | 从保存的提示库构建子代理提示前奏 | | `agent_prompt_save(pattern, content, purpose)` | ⚡️ | 插入可重用调度模式页面 | | `seed_agent_prompts()` | ⚡️ | 将启动模式种子到库中 | 模式是标记为`["agent-prompt"]`的维基页面；查找：`recall(type="wiki", tags=["agent-prompt"])`。 </details> <details><summary><b>数据库检查</b></summary> | 工具 | 权力 | 目的 | |---|:---:|---| | `db_inspect(query, params, limit)` | | 只读SurrealQL SELECT；由`YADGAR_DEBUG_APIS_ENABLED`（ADR-0132）控制 | </details> <details><summary><b>整合与运维</b></summary> `consolidate_now()` ⚡️ · `vacuum_now()` ⚡️ · `vacuum_checkpoints()` ⚡️ · `reembed_all()` ⚡️ · `check_invariants(repair)` ⚡️ · `sync_instructions()` ⚡️ · `archive_purge()` ⚡️ · `add_rule(...)` ⚡️ · `get_rules(...)` ⚡️ · `audit_anchors()` ⚡️ </details> <details><summary><b>死信队列</b></summary> `dlq_inspect(filter)` · `dlq_requeue(id)` ⚡️ · `dlq_dismiss(id)` ⚡️ </details> 类型化的 **JavaScript / TypeScript SDK** 包装工具表面为异步方法（Node.js，Vercel Edge，Cloudflare Workers，Deno）- 参见 [`docs/reference/sdk-js.md`](docs/reference/sdk-js.md). --- ## 配置 ```bash yadgar config init # 写入 ~/.config/yadgar/config.yaml yadgar config set retrieval_profile fast ``` 优先级：环境变量（`YADGAR_*`）> `~/.config/yadgar/config.yaml` > 默认值。旋钮也可以通过 **System → Config** 在viz UI中编辑。关键变量（完整参考见 [docs/reference/configuration.md](docs/reference/configuration.md)）： | 变量 | 默认值 | 目的 | |---|---|---| | `YADGAR_REQUIRE_AUTH` | `1` | 在 `/api/*` `/hooks/*` `/mcp` 上启用 Bearer 身份验证。仅在初始部署期间设置为 `0`。 | | `YADGAR_MCP_AUTH_TOKEN` | （必填） | Bearer令牌。`yadgar setup` 生成一个。 | | `YADGAR_DB_PASS` | （必填） | SurrealDB密码。无 `root:root` 回退。 | | `YADGAR_HOST` | `127.0.0.1` | 绑定接口。默认环回。 | | `YADGAR_ALLOWED_ORIGINS` | 环回 | CORS允许列表。 | | `YADGAR_METRICS_ENABLED` | `1` | 暴露Prometheus `/metrics`（环回，无身份验证）。 | | `YADGAR_LOG_FORMAT` | `human` | 设置 `json` 以获取结构化日志。 | | `YADGAR_VIZ_MAX_MEMORIES` / `_WIKI` / `_ENTITIES` | `0`（无限） | 星系节点上限（`0`/`-1` = 无限）。 | | `YADGAR_MODEL_IDLE_EVICTION_SECONDS` | `0` | 在空闲秒后卸载沉重的ML模型（`0` = 保持加载）。 | | `GTE_RERANKER_MODEL` | `cross-encoder/ettin-reranker-32m-v1` | 主要CE重新排序器（Train 4；ADR-0104）。回滚：`Alibaba-NLP/gte-reranker-modernbert-base`。 | | `YADGAR_DEBUG_APIS_ENABLED` | `0` | 启用 `/api/logs/*` + `db_inspect` 接口。 | --- ## 子代理集成 Yadgar 配备了一个 `SubagentStop` 钩子，用于捕获Claude Code子代理的内存发现结果：当子代理完成时，其最终报告会被扫描以获取 `## Yadgar findings` 部分，并且每个项目都会使用 `provenance_agent` 设置为代理类型。 要选择您的子代理进入协议，请将 [`docs/reference/claude-subagent-contract.md`](docs/reference/claude-subagent-contract.md) 粘贴到您的 `~/.claude/CLAUDE.md`，然后运行 `yadgar install-hooks --scope global`。该协议是可选的 - Yadgar 无需它即可工作。 **代理提示库** (`agent_prompt_save` / `agent_dispatch_prelude`) 为子代理调度提示提供了一个有版本控制的家园：保存一个好的提示一次，随时间改进它，并且每次调度都会自动提取最新版本。`agent_dispatch_prelude(pattern, task_topic)` 从存储的模式中构建一个兼容的前奏（recall-first 合同 + `## Yadgar findings` 页脚）。 --- ## 基准 Yadgar 在 [**LongMemEval**](https://arxiv.org/abs/2410.10813)（ICLR 2025）上进行评估，这是标准的长时记忆对话内存学术基准测试。`longmemeval_s` 变体针对 ~50 会话的合成历史记录运行 500 个问题，涵盖 6 个类别，并根据 **第 1 阶段检索**（内存层是否在 top-k 中显示黄金上下文会话？）和 **第 2 阶段 QA 准确性**（阅读器是否产生黄金答案，由 LLM 评分器判断？）进行评分。 **标语（v5.26.0，完整 500q，Sonnet 4.6 读取器 + 评估者 - 最新完整运行；后续版本针对基础设施、viz、wiki 和召回统一进行了优化，而不是检索质量）：** | 系统 | 读取器 | LongMemEval-s QA | vs yadgar | |---|---|---|---| | **yadgar v5.26.0** | **Sonnet 4.6** | **69.4%** (347/500) | — | | mem0 V3 | GPT-4o | 94.4% | +25.0 pp | | Zep / Graphiti | GPT-4o | 63.8% | **-5.6 pp** | Yadgar 以 5.6 pp 的优势击败 Zep。mem0 通过 LLM 提取入库领先 25 pp。**第 1 阶段检索：** MRR 0.928，Recall@10 0.906，NDCG@10 0.863 — 内存层为 ~91% 的查询提供黄金上下文，因此剩余的 QA 差距主要是读取器合成，而不是检索。 完整方法论和每种类型细分：[`docs/benchmark-results/BENCHMARK_RESULTS.md`](docs/benchmark-results/BENCHMARK_RESULTS.md). ### 召回速度 **Ettin-32m @ --cpus 3 （ADR-0106 立式配置），温暖稳态 p50 ~2.6s / 平均 ~2.3s （n=30，受控 2026-07-15）。** 交叉编码器重新排序器交换（GTE-ModernBERT → Ettin-32m，v5.132.0/5.43.0）提供了测量的 **2.44× 端到端召回加速** 在相同硬件上（相同镜像，相同 CPU A/B，柱状图-δ 方法按 ADR-0098）。3-CPU 立式配置（ADR-0106）通过 `gather_budget=2` 添加并行批量评分（~24% 进一步降低 vs 2-CPU）。CE 约占冷召回墙的 25% （ADR-0105）- 主要增益来自模型交换。 受控重新测量 2026-07-15（v5.143.0/5.50.0，n=30 每组，CE-miss 门限 PASS）：温暖稳态平均 **2,332ms** / p50 **2,644ms** / p95 **3,064ms**；冷（重启后）平均 **2,594ms** / p50 **2,682ms** / p95 **3,148ms**。 完整的累计延迟历史、测量协议、兼容性注意事项和每个里程碑的裁决：[`docs/benchmark-results/RECALL_SPEED.md`](docs/benchmark-results/RECALL_SPEED.md). --- ## 路线图 ### 已发布功能亮点（v5.78 → 当前版本） - **统一检索**（v5.78–v5.81）— 内存 + 维基合并为一个排名的、热度加权、分支范围的结果；现已成为默认功能。 - **ADR 工具**（`adr_add` / `adr_get` / `adr_list`，v5.85+）+ 首次捕获的停止钩子提示。每个 ADR 的维基页面，带有薄索引；`recall()` 是读取路径。138 个实际 ADR 被 dogfooded。 - **代理提示库**（v5.85，ADR-0007）— 维基支持的、标签检索的查找；`agent_dispatch_prelude` 构建符合要求的子代理前提。 - **任务列表镜像** — `wiki_write_task_list`（停止钩子输出）+ 会话启动恢复提示（输入）；在 `/clear` 期间持久化 Claude Code 任务列表。 - **星系可视化**（#52 后，ADR-0134/0138）— 星系是唯一的渲染器（强制有向/2D 引擎已删除）；星系布局（松散/核心/臂），轨迹重放，浏览器内配置面板。 - **只读数据库检查**（`db_inspect`，ADR-0132）— SurrealQL SELECT 接口的受限表面。 - **维基自动链接 + 仓库-维基存储桥**（v5.85）。 - **可视化大修 + 预计算服务器端布局 + 系统 → 配置编辑器**（v5.86–v5.88）。 - **核心/_shared/后端层分离**（ADR-0056/0060/0062/0063）— 导入限制强制的三层架构；具有完整后端管道的单向检索（ADR-0044）。 - **检索性能 + 会计**（v5.97–v5.104）— WRRF N+1 批次，扩散激活 N+1 批次；CE 约为冷检索墙的 25%（ADR-0105 已纠正）。 - **Ettin-32m CE 重排序器**（训练 4，ADR-0104）— 2.44 倍端到端检索加速；3-CPU 立式配置（ADR-0106）。 - **三信号可观察性标准**（v5.100–v5.101，ADR-0034）— 每个函数的 span+metric+log，I33 覆盖率检查，核心→后端 W3C traceparent，OTLP → Tempo。 - **测试速度训练**（v5.104，ADR-0036）— CI 分片速度提升约 2 倍。 - **文件队列写入路径**（ADR-0075）— 共享卷上的异步写入队列；两个容器共享 `yadgar-queue-data`。 - **依赖现代化**（ADR-0100）— transformers 5.x；optimum-onnx 已移除。 - **模块标准化**（ADR-0128/0130）— 主要子系统升级为包目录；导入限制强制执行；性能中立（ADR-0129）。 ### 开放前景 - **v6 — 每夜 LLM 管理员。** 一个本地代理（Ollama；两层 deepseek-r1 + qwen3:8b）每晚运行，以检测过时、注释矛盾、查找共现之外的语义相关性、提出合并/遗忘，并对维基页面进行重复数据清理。 - **v7 — 实时合成。** `recall(synthesize=True)` / `ask()` 工具；依赖于一个小于 10 秒的本地合成模型。 - **开放工作：** 改进训练 A1+C4 · 每个区域的全可观察性滚动 (#I33) · ci-velocity 剩余 (#83/#79) · cpu-burst 第 2 部分 · 任务路由修复 · 融合 tiebreak 确定性 · 观察速度完成。 完整历史：[CHANGELOG.md](docs/CHANGELOG.md)。 --- ## 文档 - [AGENTS.md](AGENTS.md) — AI 编码代理的操作指南（设置、开发环境、测试、代码风格、PR 规则） - [架构](docs/reference/architecture.md) — 组件映射、检索、安全性和可观察性 - [内存生命周期](docs/reference/memory-lifecycle.md) — 热度、存档、修剪、合并阶段 - [检索](docs/reference/retrieval.md) — 融合、重排序、分支过滤、管道阶段 - [配置](docs/reference/configuration.md) — 配置参考（环境变量、优先级、关键旋钮） - [安装](docs/reference/install.md) — 每个平台的设置 + `yadgar setup --doctor` 探针 - [JS/TS SDK](docs/reference/sdk-js.md) — MCP 工具表面的类型化客户端 - [发布手册](docs/reference/release.md) · [迁移说明](MIGRATION_NOTES.md) · [子代理合约](docs/reference/claude-subagent-contract.md) --- ## 贡献 `yadgar/**` 的每个更改都必须在同一个 PR 中更新 `README.md` 和 `docs/`。 Conventional Commits 格式。不允许 `Co-Authored-By:` 追踪器。AI 编码代理在此仓库工作：阅读 [`AGENTS.md`](AGENTS.md) 以获取完整的开发/测试/PR 合约。 ## 相关项目 - **[ccpm](https://codeberg.org/maxagahi/ccpm)** — Claude Code 插件市场。提供 `code-review`、`confluence-rfc`、`git-flow`、`repo-wiki`、`tf-naming-check` 和 `update-jira` 插件，这些插件与 yadgar 组合使用。 ## 致谢 灵感来自 [@amanhij](https://github.com/amanhij) 的 [Zikkaron](https://github.com/amanhij/Zikkaron)。不同的架构，相同的北极星。 Yadgar 建立在大量的开源工作基础上 — 模型、数据库、框架和工具。完整的致谢和认可（包括 [Tom Aarsen](https://github.com/tomaarsen) 的句子转换器 + Ettin 重排序器支撑我们的检索）：**[docs/reference/tributes.md](docs/reference/tributes.md)**。 ## 许可证 Apache 2.0。查看 [LICENSE](LICENSE)。 ### 第三方许可证（关键依赖） - **SurrealDB**（默认存储后端）— [Business Source License 1.1](https://github.com/surrealdb/surrealdb/blob/main/LICENSE) （BSL）。附加使用许可允许嵌入式使用；yadgar 捆绑并操作 SurrealDB 作为单个租户的部署存储，这属于该许可。**不合规触发器：** 提供托管的多租户托管 yadgar 服务，直接向第三方客户公开 SurrealDB API — 获取商业 SurrealDB 许可或迁移到 Postgres + pgvector 如果这成为目标。 - **`surrealdb` Python SDK** — Apache 2.0（与服务器分开许可）。 - **嵌入/重排序模型** — `sentence-transformers/all-MiniLM-L6-v2`，`cross-encoder/ettin-reranker-32m-v1`（CE 主），`cross-encoder/ettin-reranker-68m-v1`（备用），`Alibaba-NLP/gte-reranker-modernbert-base`（回滚），`cross-encoder/ms-marco-MiniLM-L-6-v2`，`cross-encoder/nli-deberta-v3-small`：通过 Hugging Face 的 Apache 2.0 权重。 - **基准测试** (`benchmarks/`)：脚本 Apache 2.0，但数据集带有自己的许可证 — **LoCoMo 是 CC BY-NC 4.0（仅限非商业）**；LongMemEval 是 MIT。查看 `benchmarks/README.md`。 完整依赖审计：`docs/reports/audits/license-compliance-audit-2026-05-30.md`。