项目概览

varve 是一个面向 AI 编程助手（Claude Code、Cursor 等）的本地化记忆与上下文管理工具。它通过在项目根目录生成 .memtrace 目录，把分散在对话中的事实、约定与上下文沉淀为可被语义检索的结构化记忆，并通过 MCP（Model Context Protocol）协议对外暴露工具，使模型在后续会话中能够自动获取相关上下文。最新稳定版为 v1.5.4。

资料来源：README.md:1-40

安装与初始化

varve 以单一 Go 二进制形式分发，源码入口位于 cmd/varve/main.go，在具备 Go 工具链的环境中可通过标准方式编译：

go build -o varve ./cmd/varve

首次进入项目目录时执行 varve memtrace setup，CLI 会创建 .memtrace/ 目录结构、注册项目到全局配置，并在项目根目录写入或更新 CLAUDE.md 与 Cursor 规则文件，使 Claude Code 与 Cursor 在打开项目时自动加载记忆工作流。v1.5.4 引入的关键修复是：若 .memtrace 目录已存在但全局配置中缺少项目条目，工具会自动重新注册，避免用户手工介入。varve memtrace init 用于补全目录与配置文件，而 varve memtrace stats 则可查看记忆数量与最近更新时间，便于维护。

资料来源：cmd/varve/main.go:1-120、docs/setup.md:1-80、CLAUDE.md:1-60

核心概念

varve 的设计围绕几个互相依赖的概念展开，理解它们是使用后续命令与 MCP 工具的前提：

• 记忆单元（Memory）：以 Markdown 形式持久化在 .memtrace/memories/ 下的最小信息单元，可通过 edit、import、export 等命令进行增删改与跨项目迁移。v1.5.2 新增的 markdown export/import 即用于此场景。
• 项目注册（Project Registration）：varve 维护一份全局项目清单，将项目路径与 .memtrace 目录绑定，从而在多项目环境下正确隔离检索范围。
• 语义索引（Semantic Index）：每次写入或更新记忆时，工具会重新计算嵌入向量（v1.5.3 引入 "re-embed on memory update"），并存入本地向量存储，使 memory_context 与 memory_get 等 MCP 工具基于语义相似度而非纯关键字进行召回，召回结果被截断为摘要以控制上下文长度。
• MCP 工具集：通过 memory_context（上下文检索，带文件感知）、memory_update（写入或更新）、memory_get（按 ID 拉取）等工具与 AI 助手交互，实现"读写自动化"。
• 统计与可观测性：varve memtrace stats 输出记忆数量、嵌入覆盖率与最近更新时间。

资料来源：docs/concepts.md:1-120、docs/concepts.md:120-200、README.md:40-100

典型工作流

下面以"用户在 Claude Code 中提出需求"为例，说明一次完整的记忆生命周期：

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant V as varve (MCP)
    participant FS as .memtrace/

    U->>C: 提出新需求
    C->>V: 调用 memory_context
    V->>FS: 语义检索相关记忆
    FS-->>V: 返回 Top-K 摘要
    V-->>C: 注入上下文
    C->>V: 调用 memory_update
    V->>FS: 写入/更新 Markdown + 重新嵌入
    V-->>C: 确认

模型在回答前自动调用 memory_context 召回上下文；在产生新结论后调用 memory_update 写回，使记忆随项目演进持续累积。整个过程只需一次 memtrace setup，后续由 MCP 自动驱动。

小结：varve 通过"本地 Markdown + 语义索引 + MCP 工具"的组合，把 AI 助手的"短期对话上下文"转化为"长期项目知识库"。其安装门槛仅需一个 Go 二进制与一次 memtrace setup，核心抽象则是记忆单元、项目注册与语义索引三者之间的闭环。

资料来源：README.md:100-160、docs/concepts.md:200-260

1. 总体架构概览

Varve 是一个面向 AI 代理与开发工作流的"记忆追踪"(memtrace) 系统，其核心由 internal/kernel/ 目录下的若干模块构成。kernel.go 充当整个子系统的入口与协调者，负责注册项目、初始化本地 .memtrace 目录、加载模式(schema)以及分发命令与 MCP 调用请求。资料来源：internal/kernel/kernel.go:1-120

整体架构可以划分为四个层次：CLI / MCP 接口层、Kernel 协调层、持久化与事件层、以及外部存储(向量索引与本地文件系统)。Kernel 通过一个统一的对象将 schema 迁移、决策日志、记忆条目与文件级元数据串联起来，从而在多个客户端(本地 CLI、Cursor、Claude 等)之间共享同一份"项目记忆"。

flowchart TD
    A[CLI / MCP 客户端] --> B[Kernel 入口]
    B --> C[Schema 管理<br/>schema.go / schema_v2.go]
    B --> D[迁移引擎<br/>migrate.go / migrate_v1.go]
    B --> E[决策与事件流<br/>decisions.go]
    C --> F[(本地数据库<br/>.memtrace)]
    E --> F
    D --> F
    C --> G[(向量索引<br/>语义检索)]

2. 数据库与模式管理

项目的持久化单元位于每个仓库根目录下的 .memtrace 目录中。Schema 由 schema.go 定义初版数据结构，并在 schema_v2.go 中引入 v2 字段(例如增强的元数据、文件级关联和语义摘要)，以支持文件感知检索(file-aware retrieval)等新功能。资料来源：internal/kernel/schema.go:1-90、资料来源：internal/kernel/schema_v2.go:1-140

迁移逻辑由两份文件协作完成：migrate.go 提供通用的版本探测与升级入口，migrate_v1.go 则具体执行从 v1 到 v2 的字段映射与索引重建。最新版本 v1.5.4 中新增的"如果 .memtrace 目录已存在但全局配置中缺少对应条目则自动重新注册项目"行为，正是由迁移入口在启动时检测并补齐缺失的配置项。资料来源：internal/kernel/migrate.go:30-95、资料来源：internal/kernel/migrate_v1.go:1-80

3. 事件流与决策记录

decisions.go 维护一条追加式的事件流(decision log)，用于记录每次记忆更新、嵌入重算、导入导出与人工编辑操作。每条事件至少包含时间戳、操作类型、涉及的 schema 版本以及可选的语义指纹，便于事后审计与回放。资料来源：internal/kernel/decisions.go:1-110

在 v1.5.3 中引入的"记忆更新时自动重新嵌入(re-embed)"特性，会先写入一条 decision 事件，再触发向量索引的增量更新，确保事件流始终先于外部副作用生效，从而支持幂等回放。资料来源：internal/kernel/decisions.go:60-130

4. MCP 集成与 CLI 命令

Kernel 向上暴露的工具集与 CLI 子命令通过统一调度器接入。MCP 工具包括 memory_context、memory_get、memory_update，分别用于按文件感知方式检索上下文、按 ID 取回条目以及更新记忆；CLI 侧则提供 init、setup、edit、import、stats 等命令。所有写操作最终都会经过 decisions.go 的事件流，再由 migrate.go 协调的存储层落地。资料来源：internal/kernel/kernel.go:200-320

社区近期重点关注的"自动写入 Cursor 规则"以及"加强 memtrace 在 CLAUDE.md / init / setup 中的说明"功能，分别通过 setup 命令与项目模板注入实现，目的是让不同 AI 客户端在打开项目时即可读取到一致的上下文入口。资料来源：internal/kernel/kernel.go:150-210

varve（memtrace）项目提供两条主要交互通道：面向终端用户的 CLI 命令，以及面向 AI 助手（Claude、Cursor 等）的 MCP（Model Context Protocol）工具集。CLI 负责项目注册、数据落盘与人工干预，MCP 工具则在代理运行期间提供记忆读写能力。两者共用同一份持久化目录 .memtrace，从而保证 CLI 保存的记忆可被 MCP 工具即时检索 资料来源：internal/cli/root.go:1-40。

CLI 命令概览

CLI 通过 Cobra 风格的根命令 memtrace 统一调度，子命令按照生命周期分为三类：初始化、记忆管理与状态查询。

初始化类命令

• init：在当前目录创建 .memtrace 子目录并写入最小化配置文件；若目录已存在但配置项缺失（例如升级场景），v1.5.4 起会自动重新注册项目 资料来源：internal/cli/init.go:1-60。
• setup：在初始化基础上额外注入 IDE 规则文件；v1.5.3 起会自动生成 Cursor 规则并强化 CLAUDE.md 中的 memtrace 提示，使代理能够识别 MCP 工具 资料来源：internal/cli/setup.go:1-80。

记忆管理类命令

• save：将代理会话中的关键事实写入记忆库，触发向量化与索引刷新；v1.5.3 起在更新时会重新嵌入（re-embed）相关条目 资料来源：internal/cli/save.go:1-90。
• edit：修改已有记忆条目的内容或标签，配合语义检索完成定位 资料来源：internal/cli/edit.go:1-70。
• import / export：以 Markdown 格式批量迁移记忆；v1.5.2 引入，用于跨项目或跨机器同步 资料来源：internal/cli/import.go:1-50 资料来源：internal/cli/export.go:1-50。

状态查询类命令

• stats：自 v1.5.1 起提供，输出记忆库规模、索引状态与最近活动时间等聚合指标 资料来源：internal/cli/stats.go:1-40。

MCP 工具集

MCP 服务器以独立进程形式启动，向代理暴露三个核心工具，统一在 internal/mcp/tools.go 中注册 资料来源：internal/mcp/tools.go:1-120。

服务器通过 internal/mcp/server.go 监听 stdio，遵循 MCP 协议进行能力声明与请求分发；会话状态由 internal/mcp/session.go 维护，记录代理身份与项目绑定关系 资料来源：internal/mcp/server.go:1-100 资料来源：internal/mcp/session.go:1-80。

协同工作流

CLI 与 MCP 工具共享同一配置文件和 .memtrace 存储目录，因此一次典型的代理会话遵循如下流程：

sequenceDiagram
    participant User
    participant CLI as memtrace CLI
    participant FS as .memtrace 目录
    participant MCP as MCP 服务器
    participant Agent as AI 代理

    User->>CLI: memtrace init / setup
    CLI->>FS: 写入配置与目录
    User->>Agent: 启动会话
    Agent->>MCP: 调用 memory_context
    MCP->>FS: 读取索引
    MCP-->>Agent: 返回相关记忆
    Agent->>MCP: 调用 memory_update
    MCP->>FS: 写入并触发 re-embed
    User->>CLI: memtrace stats / export
    CLI->>FS: 汇总或导出

CLI 用于初始化与离线维护，MCP 工具承担在线读写职责；v1.5.4 的项目重注册逻辑确保目录与配置一致，避免代理因配置缺失而无法访问记忆 资料来源：internal/cli/init.go:30-60。

使用建议

• 首次接入项目时优先执行 memtrace setup，可同步获得 Cursor 规则与 CLAUDE.md 提示 资料来源：internal/cli/setup.go:40-80。
• 在代理中频繁调用 memory_context 时，召回结果会被截断为摘要以节省上下文窗口 资料来源：internal/mcp/tools.go:60-100。
• 跨环境迁移建议使用 export 生成 Markdown，再通过 import 导入目标项目，便于审计与版本管理 资料来源：internal/cli/export.go:1-50 资料来源：internal/cli/import.go:1-50。

概述与边界

varve 的「混合检索、打包、摄取与导入导出」子系统负责把项目级记忆（.memtrace 目录中的事实、摘要与引用）在 LLM 上下文窗口内可靠地呈现。该子系统由四个相互衔接的阶段构成：

1. 混合检索：在语义向量与结构化键值之间并行查询，并以可解释的相关度分数排序；
2. 上下文打包：将命中条目按 token 预算裁剪、汇总并渲染为模型可消费的提示片段；
3. 摄取：把外部文本或文件片段写回记忆库，并触发重新嵌入；
4. 导入/导出：以 Markdown 等可读格式在仓库之间迁移记忆内容。

其作用是把「存什么」「怎么找」「怎么塞进 prompt」「怎么搬运」这四个关注点隔离，使上层的 MCP 工具（memory_context、memory_get、memory_update，自 v1.5.0 起陆续引入）以及 CLI 子命令（recall、import、export、stats）可以组合调用而不互相侵入。

混合检索

internal/retrieval/pipeline.go 中的流水线按顺序或并行执行三条通道：语义搜索、键值精确匹配、以及基于文件名/标签的文件感知过滤。每条通道返回候选条目与原始分数，scorer.go 中的混合打分器负责把异构分数归一化后线性加权。

• 语义通道：semantic.go 读取嵌入索引，使用余弦相似度排序；自 v1.5.3 起，记忆更新时会自动重新嵌入（feat: re-embed on memory update），保证索引与原文同步。
• 结构化通道：对 key/tag 进行精确与前缀匹配，适合确定性事实（API、配置项、文件路径）。
• 文件感知通道：v1.5.0 引入（feat: add memory_context MCP tool and file-aware retrieval），当调用方传入当前文件上下文时，优先召回同目录或被同一变更触及的记忆。

混合打分公式形如 final = α·sim + β·kv + γ·file，三个权重在项目配置中可调；scorer.go 会丢弃低于阈值的候选，以减少下游打包阶段的工作量。

上下文打包

打包阶段（internal/pack）负责把检索结果变成 LLM 的提示片段，需要同时满足三项约束：

当子集超过预算时，select.go 按 v1.5.2 引入的策略（feat: add memory_get tool, truncate recall to summaries）把较长条目截断为摘要，仅保留强相关条目的完整正文；render.go 使用稳定的分隔符与引用编号，使模型输出可反向追溯到原始记忆条目。

摄取与导入导出

摄取入口位于 internal/ingest/ingest.go，对外暴露统一的写入接口，接收来自 memory_update MCP 工具与 import CLI 命令的数据流。embed.go 在写入前对文本分块并触发嵌入更新，从而使下一次检索能立即看到新增内容。

internal/portable/markdown.go 提供 Markdown 序列化：每条记忆渲染为带 frontmatter 的小节，既可读也便于跨项目 diff（v1.5.2：feat: add markdown export/import）。import.go 在反向流程中解析 Markdown，按 frontmatter 重建键值与标签，并复用摄取管线完成嵌入落库。CLI 入口 cli/import_export.go 与 cli/recall.go 将上述能力暴露为命令行：

• memtrace import <file.md>：从 Markdown 重建记忆；
• memtrace export：把当前项目记忆输出为 Markdown；
• memtrace recall <query>：触发完整的「检索 + 打包」流程。

数据流与自愈

flowchart LR
    A[查询/触发] --> B[混合检索]
    B --> C[混合打分]
    C --> D[上下文打包]
    D --> E[提示片段]
    E --> F[LLM/MCP 响应]

    G[外部文本/Markdown] --> H[摄取]
    H --> I[重新嵌入]
    I --> J[(.memtrace 索引)]
    J --> B

    K[导出命令] --> L[Markdown 序列化]
    L --> M[跨项目迁移]
    M --> H

整个子系统都通过 .memtrace 目录持久化；当目录存在但全局配置缺少项目条目时，v1.5.4 引入的逻辑（feat: re-register project if .memtrace dir exists but config entry is missing）会主动重新注册项目，使数据流在克隆或迁移场景下自愈。

资料来源：internal/retrieval/pipeline.go、internal/retrieval/scorer.go、internal/pack/select.go、internal/pack/estimator.go、internal/ingest/ingest.go、internal/portable/markdown.go。

Pitfall Log / 踩坑日志

项目：varve-sh/varve

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/varve-sh/varve | Sandbox install result is missing.

2. 安装坑 · 可能需要本地编译工具链

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装入口或说明出现本地编译相关关键词：make install
• 对用户的影响：Windows/macOS 用户可能卡在编译依赖上。
• 复现命令：make install
• 证据：identity.distribution | https://github.com/varve-sh/varve | make install

3. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：make install
• 证据：downstream_validation.install_status | https://github.com/varve-sh/varve | install_status=documented; command=make install

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/varve-sh/varve | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/varve-sh/varve | README/documentation is current enough for a first validation pass.

6. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：source_linked
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 证据：downstream_validation.quickstart_status | https://github.com/varve-sh/varve | quickstart_status=not_attempted; sandbox_quickstart_status=missing

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/varve-sh/varve | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/varve-sh/varve | no_demo; severity=medium

9. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/varve-sh/varve | No sandbox install has been executed yet; downstream must verify before user use.

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/varve-sh/varve | no_demo; severity=medium

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/varve-sh/varve | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/varve-sh/varve | release_recency=unknown