Skip to content
Back to search

VESTI-SKILLS

Open agent skills by VESTI: vesti-memory and vesti-handoff

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/firefly-hefeng--vesti-skills/badge.svg)](/listings/firefly-hefeng--vesti-skills)

HTML

<a href="/listings/firefly-hefeng--vesti-skills"><img src="/api/listings/firefly-hefeng--vesti-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "vesti-skills",
  3. "owner": {
  4. "name": "Vesti",
  5. "url": "https://github.com/firefly-hefeng"
  6. },
  7. "plugins": [
  8. {
  9. "name": "vesti-skills",
  10. "source": "./",
  11. "description": "Working-memory skills for coding agents: recall past sessions (vesti-memory, requires local VESTI / @vesti/mcp) and structured handoff (vesti-handoff, standalone).",
  12. "version": "0.1.0",
  13. "license": "MIT",
  14. "homepage": "https://github.com/firefly-hefeng/VESTI-SKILLS"
  15. }
  16. ]
  17. }
README.md · README · 349 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # VESTI Skills
  3. **让本地会话记忆在 Codex、Claude Code、Kimi Code、Cursor、Qoder、WorkBuddy 和 Trae 之间持续复用。**
  4. VESTI 是一套跨 Agent 的本地记忆工具。它在后台整理已有的会话记录,
  5. 让当前使用的编程助手能查到之前的讨论、决策和相关文件,接着往下做。
  6. 采集服务、MCP 和 Skill 可以独立安装和运行。
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  8. [![CI](https://github.com/firefly-hefeng/VESTI-SKILLS/actions/workflows/ci.yml/badge.svg)](https://github.com/firefly-hefeng/VESTI-SKILLS/actions/workflows/ci.yml)
  9. [![Platform](https://img.shields.io/badge/clients-Codex%20%7C%20Claude%20Code%20%7C%20Kimi%20Code%20%7C%20Cursor-green.svg)](#支持的客户端)
  10. </div>
  11. ---
  12. ## 它解决什么问题
  13. 同一个项目经常会在多个会话、多个编程助手之间推进。换工具或新开会话之后,项目背景、
  14. 已经尝试过的方案、文件位置和决策理由往往需要重新说明。
  15. VESTI 把这些分散在本机的历史会话整理成一份共享记忆。安装完成后,支持的客户端可以通过
  16. 同一套 MCP 工具检索历史,`vesti-memory` Skill 则指导客户端先查索引、再按需读取原文,
  17. 避免一次塞入大量无关上下文。
  18. 你可以用它:
  19. - 换一个 Agent 继续同一项目,查清之前确定的方案和未完成的工作。
  20. - 新开会话时复用已有背景,减少反复复制历史对话。
  21. - 根据讨论中的线索定位文件,核对当时为什么这样修改。
  22. - 查找过去用过的信息和约定,并回到原始会话确认。
  23. [开始安装](#快速开始) · [首次使用与验收](#首次使用与验收) · [支持的客户端](#支持的客户端) · [工作原理](#工作原理)
  24. ## 快速开始
  25. 当前使用源码安装。`@vesti/memory` 的 npm 发布方式暂不作为安装入口。
  26. 准备好 Git、Node.js 22.12 或更高版本,以及 Corepack;仓库固定使用 pnpm 10.34.4。
  27. ### 从源码安装
  28. ```bash
  29. git clone --branch main --single-branch https://github.com/firefly-hefeng/VESTI-SKILLS.git
  30. cd VESTI-SKILLS
  31. corepack enable
  32. corepack pnpm install --frozen-lockfile
  33. corepack pnpm build
  34. node packages/vesti-memory/dist/cli.js setup
  35. ```
  36. `setup` 会自动检测已有的受支持客户端,安装 Skill、注册 MCP,并启动后台采集。
  37. 只想配置一个客户端时,可将最后一条命令改为:
  38. ```bash
  39. node packages/vesti-memory/dist/cli.js setup --host codex
  40. ```
  41. 其他客户端的 `--host` 值见[支持的客户端](#支持的客户端)。这个参数只决定写入哪个客户端的配置,
  42. 不限制后台采集的会话来源。
  43. `setup` 可重复执行,只新增或更新 VESTI 的配置项;修改已有配置前会创建备份,并保留其他 MCP 配置。
  44. 完成后重启或重新加载对应客户端,再按下一节检查是否可用。
  45. 安装器会把当前仓库中构建产物的绝对路径写入客户端配置,请把仓库放在长期保留的目录。移动目录或更新 Skill 后,重新运行 `setup`,再重启或重新加载客户端。
  46. 源码更新后先重新执行 `corepack pnpm build`。不要用一次性的 `npx` 缓存路径保存长期配置。
  47. ### 让 Agent 安装配套环境
  48. 也可以把下面这段话发给当前 coding agent,并授权它执行安装命令:
  49. ```text
  50. 请按 https://github.com/firefly-hefeng/VESTI-SKILLS 的 main 分支 README 安装 VESTI。把仓库克隆到长期保留的目录,检查 Node.js 版本,使用固定版本的 pnpm 安装依赖并构建,然后为当前客户端执行 setup、status 和 doctor。保留已有的其他 MCP 配置,完成后告诉我是否需要重启客户端。
  51. ```
  52. English version:
  53. ```text
  54. Install VESTI following the README on the main branch of https://github.com/firefly-hefeng/VESTI-SKILLS. Clone into a permanent directory, check Node.js, install and build with the pinned pnpm version, then run setup for this client, status and doctor. Preserve other MCP settings and tell me whether a client restart is needed.
  55. ```
  56. ## 首次使用与验收
  57. ### 可选:自定义模型 API
  58. 独立 MCP 支持 OpenAI Chat Completions 兼容接口。未配置时仍只使用本地检索;配置后增加
  59. `vesti_summarize`,将通过 `vesti_timeline` 选定的历史轮次发送给模型,总结结果带回来源轮次。
  60. 该工具按需调用,不写入数据库,也不会自动批量生成摘要、embedding 或项目简报。
  61. 在 `~/.vesti/config/llm.json` 中填写(示例中的地址、模型、Key 需替换):
  62. ```json
  63. {
  64. "baseUrl": "https://your-provider.example/v1",
  65. "apiKey": "your-api-key",
  66. "model": "your-model",
  67. "timeoutMs": 30000,
  68. "maxTokens": 1500
  69. }
  70. ```
  71. `baseUrl` 是接口前缀,程序追加 `/chat/completions`,不要填写完整的 chat endpoint。
  72. 支持 HTTP 本地模型服务;无需鉴权时可省略 `apiKey`。仅支持上述兼容协议,不直接支持
  73. Anthropic Messages、Responses 或任意自定义请求格式。
  74. 默认配置目录随 `VESTI_HOME` / `VESTI_DATA_DIR` 变化,也可通过 `VESTI_LLM_CONFIG` 指定 JSON 文件。
  75. 模型配置可由 MCP 进程环境变量覆盖:`VESTI_LLM_BASE_URL`、`VESTI_LLM_API_KEY`、
  76. `VESTI_LLM_MODEL`、`VESTI_LLM_TIMEOUT_MS`、`VESTI_LLM_MAX_TOKENS`。
  77. 设置 `VESTI_LLM_ENABLED=false` 或在文件中设置 `"enabled": false` 可禁用。
  78. 配置文件中的 Key 为明文;可省略它,改由 MCP 进程环境提供 `VESTI_LLM_API_KEY`。
  79. `setup` 不会把当前终端里的模型 Key 复制到各客户端配置中。
  80. 构建后检查配置和连接(`test` 会发送一条简短测试请求,不发送历史):
  81. ```bash
  82. node packages/vesti-memory/dist/cli.js llm status
  83. node packages/vesti-memory/dist/cli.js llm test
  84. ```
  85. `status` 不联网且隐藏 Key。更改配置后重启 MCP/对应客户端。
  86. 如果此前安装指向另一份仓库,需要在本仓库构建后重新执行 `setup` 才会使用这份实现。
  87. 配置无效时 MCP 会在 stderr 报告原因,并继续提供原有本地工具。
  88. 使用时让 Agent 先搜索并定位轮次,再调用:
  89. ```json
  90. {
  91. "name": "vesti_summarize",
  92. "arguments": {
  93. "session_id": "从 vesti_search 获取的会话 ID",
  94. "turn_ids": [1, 3],
  95. "question": "总结这几轮确定的方案和未解决的问题"
  96. }
  97. }
  98. ```
  99. 最多选择 20 个轮次,历史正文受字符预算限制;返回的 `source.truncated` 标记截断。
  100. 模型总结是生成内容,应根据 `source.session_id`、`source.turn_ids` 回查原文确认。
  101. 只有显式调用该工具才会发送所选历史到配置的 API,普通检索工具不会调用模型。
  102. ### 1. 检查安装与采集状态
  103. 在仓库根目录执行:
  104. ```bash
  105. node packages/vesti-memory/dist/cli.js status
  106. node packages/vesti-memory/dist/cli.js sync
  107. node packages/vesti-memory/dist/cli.js doctor
  108. ```
  109. 检查以下结果:
  110. | 检查项 | 应看到什么 |
  111. | --- | --- |
  112. | 目标客户端 | `status` 中对应客户端显示 `Skill=ready, MCP=ready` |
  113. | 数据库 | `Database:` 后有实际路径,而不是 `missing` |
  114. | 采集服务 | 状态包含 `state: running`、`initialSyncComplete: true`(实际输出为 JSON) |
  115. | 安装诊断 | `doctor` 的检查项为 `PASS`,最后显示 `VESTI memory is ready.`,退出码为 0 |
  116. 只需检查你打算使用的客户端;未安装、未配置的其他客户端显示 `missing` 不代表本次安装失败。
  117. `doctor` 至少要求一个客户端配置完整,不能替代逐个客户端的验收。
  118. 采集服务就绪也不代表所有来源均无错误:还要检查同步结果和 `~/.vesti/logs/capture-daemon.log`。
  119. 首次同步可能需要等待历史记录导入。
  120. ### 2. 在客户端确认能够召回
  121. 重启或重新加载客户端,确认它能看到 VESTI MCP 工具和 `vesti-memory` Skill。
  122. 选一段你确实讨论过、且保存在受支持本地来源中的记录,把下面的主题替换成自己的内容:
  123. ```text
  124. 请使用 vesti-memory 查找我之前关于“登录模块”的讨论。
  125. 告诉我当时确定了什么、涉及哪些文件,并给出原始会话来源。先不要修改文件。
  126. ```
  127. 在工具调用记录中确认客户端实际调用了 VESTI 的检索工具,再核对回答中的会话来源和内容。
  128. 能够返回匹配的原始讨论,才说明这次历史召回验证通过;仅仅回答“已安装”不算。
  129. 如果没有结果,先检查来源是否有可读记录、同步是否报错,再换用原讨论中的具体关键词。
  130. 配置显示 `ready`,并不保证每个查询都一定命中。
  131. <details>
  132. <summary>已有 MCP 环境,只安装 Skill</summary>
  133. 远程默认分支也提供插件清单。以下入口安装 Skill,不替代上面的独立采集服务和 MCP 安装;`vesti-handoff` 可独立使用,`vesti-memory` 需要配套 MCP 提供历史检索。
  134. **Kimi Code**(仓库根目录 `kimi.plugin.json`):
  135. ```text
  136. /plugins install https://github.com/firefly-hefeng/VESTI-SKILLS
  137. ```
  138. 安装后运行 `/reload` 或新开会话,也可用 `/skill:vesti-memory` 或 `/skill:vesti-handoff` 调用。
  139. **Claude Code**(`.claude-plugin/marketplace.json`):
  140. ```text
  141. /plugin marketplace add firefly-hefeng/VESTI-SKILLS
  142. /plugin install vesti-skills@vesti-skills
  143. ```
  144. 其他客户端也可手动把 `skills/vesti-memory` 和 `skills/vesti-handoff` 复制到各自的用户级 Skill 目录,然后重新加载客户端。若已经通过 `setup` 安装 `vesti-memory`,无需再重复安装同一 Skill。
  145. </details>
  146. ## 支持的客户端
  147. 安装器支持 Codex、Claude Code、Kimi Code、Cursor、Qoder、WorkBuddy 和 Trae 系列,
  148. 后台默认检查这 7 类本地会话来源。Trae 仅支持旧版可读的 `state.vscdb`,不支持新版加密的
  149. `ModularData/ai-agent/database.db`。
  150. 下表命令是 CLI 子命令;源码安装时请在前面加上 `node packages/vesti-memory/dist/cli.js`。
  151. <details>
  152. <summary>查看各客户端的配置路径与命令</summary>
  153. | 客户端 | 用户级 Skill 位置 | 用户级 MCP 配置 | 单独配置命令 |
  154. |---|---|---|---|
  155. | Codex | `~/.agents/skills/vesti-memory/` | `~/.codex/config.toml` 的 `[mcp_servers.vesti]` | `setup --host codex` |
  156. | Claude Code | `~/.claude/skills/vesti-memory/` | `~/.claude.json` 的 `mcpServers.vesti` | `setup --host claude` |
  157. | Kimi Code | `~/.kimi-code/skills/vesti-memory/` | `~/.kimi-code/mcp.json` 的 `mcpServers.vesti` | `setup --host kimi-code` |
  158. | Cursor | `~/.cursor/skills/vesti-memory/` | `~/.cursor/mcp.json` 的 `mcpServers.vesti` | `setup --host cursor` |
  159. | Qoder 桌面版 | `~/.qoder/skills/vesti-memory/` | `<用户数据根>/Qoder/SharedClientCache/mcp.json` | `setup --host qoder` |
  160. | Qoder CLI | `~/.qoder/skills/vesti-memory/` | `~/.qoder/settings.json` 的 `mcpServers.vesti` | `setup --host qoder-cli` |
  161. | WorkBuddy | `~/.workbuddy/skills/vesti-memory/` | `~/.workbuddy/mcp.json` 的 `mcpServers.vesti` | `setup --host workbuddy` |
  162. | Trae | `~/.trae/skills/vesti-memory/` | `<用户数据根>/Trae/User/mcp.json` | `setup --host trae` |
  163. | Trae CN | `~/.trae-cn/skills/vesti-memory/` | `<用户数据根>/Trae CN/User/mcp.json` | `setup --host trae-cn` |
  164. | TRAE SOLO CN | `~/.trae-cn/skills/vesti-memory/` | `<用户数据根>/TRAE SOLO CN/User/mcp.json` | `setup --host trae-solo-cn` |
  165. 用户数据根在 Windows 为 `%APPDATA%`,macOS 为 `~/Library/Application Support`,Linux 为 `$XDG_CONFIG_HOME`(默认 `~/.config`)。Qoder 桌面版与 CLI 的 MCP 路径不同;安装器按实际存在的用户配置目录识别,不要求用户手填 JSON。Qoder CLI 使用默认 `~/.qoder` 布局,暂不处理 `QODER_CONFIG_DIR` 自定义布局。
  166. 不带 `--host` 等同于 `--host all`:只配置在当前用户目录中检测到的客户端。即使未被自动检测,
  167. 也可以通过显式 `--host` 完成配置。
  168. </details>
  169. ## 如何召回记忆
  170. 安装后可以直接在任一受支持的客户端中描述任务,例如:
  171. ```text
  172. 继续我昨天在登录模块里的工作,先找出改过的文件和还没解决的问题。
  173. ```
  174. 配套 Skill 会根据问题逐层使用 MCP,而不是一次读取全部历史:
  175. ```mermaid
  176. flowchart LR
  177. A["vesti_get_project_context<br/>项目状态包"] --> B["vesti_search<br/>会话级召回"]
  178. A --> C["vesti_search_files<br/>历史文件定位"]
  179. B --> D["vesti_timeline<br/>单会话轮次大纲"]
  180. C -.需要来龙去脉.-> D
  181. D --> E["vesti_get_turns<br/>指定轮次完整内容"]
  182. ```
  183. 常用能力包括:
  184. - 根据主题、项目和时间范围查找历史会话;
  185. - 定位历史工作涉及的文件,并保留支撑结果的会话证据;
  186. - 查看单个会话的大纲,再读取必要轮次的用户问题、过程信息和最终答复;
  187. - 读取数据库中已有的项目状态与未决问题,并从原始会话和工具记录提供活跃文件、跨项目线索;尚未生成的摘要层会为空;
  188. - 查询 deposit、dream、note 等记忆空间内容。
  189. 历史文件结果只表示“这个路径曾在会话中出现”,不保证文件目前仍存在。Skill 会在可访问项目时
  190. 再读取磁盘上的当前文件;低置信度结果只作为线索,不会被表述成确定事实。
  191. ## 工作原理
  192. 后台采集服务读取受支持的本地会话记录,整理后写入同一份 SQLite 数据库。
  193. 当前客户端读取 Skill 指令,根据任务调用 MCP 工具;MCP 查询数据库并把结果返回客户端。
  194. Skill 是调用规则,不是位于 MCP 和客户端之间的独立服务。
  195. ```mermaid
  196. flowchart LR
  197. A["本地会话记录"] --> B["后台采集服务"]
  198. B -->|写入| C["本地 SQLite"]
  199. E["vesti-memory Skill"] -.指导调用.-> F["当前客户端"]
  200. F -->|调用工具| D["只读 MCP"]
  201. D -->|查询| C
  202. C -->|查询结果| D
  203. D -->|返回历史上下文| F
  204. ```
  205. 采集服务会先导入已有记录,再通过文件监听或轮询获取变化,并定期补扫。
  206. 每个目标数据库由一个独立后台进程串行写入;多个客户端可通过 MCP 读取它。
  207. Skill 规定何时检索、如何逐层深入,以及如何处理低置信度结果,本身不采集数据或直接读取数据库。
  208. `setup` 会为当前登录会话启动后台进程,不创建操作系统开机启动项;以后客户端启动 VESTI MCP 时,
  209. 也会检查并按需拉起采集服务。完整的进程、来源差异与降级行为见
  210. [无 App 记忆运行时说明](docs/standalone-memory-runtime.md)。
  211. ## 包与 Skill
  212. | 路径 | 包或 Skill | 职责 |
  213. |---|---|---|
  214. | [`packages/vesti-memory`](packages/vesti-memory/README.md) | `@vesti/memory` | 一体化安装与诊断 CLI;配置七类客户端及版本变体、安装 Skill、注册 MCP、管理 daemon |
  215. | [`packages/vesti-capture-runtime`](packages/vesti-capture-runtime/README.md) | `@vesti/capture-runtime` | 无界面的本地采集引擎、单写者 daemon 和轻量 IPC client |
  216. | [`packages/vesti-mcp`](packages/vesti-mcp/README.md) | `@vesti/mcp` | 只读 stdio MCP server,提供会话、项目、记忆空间与文件检索工具 |
  217. | [`packages/vesti-memory-core`](packages/vesti-memory-core/README.md) | `@vesti/memory-core` | 可复用的 SQLite schema、迁移、记忆整理和检索原语 |
  218. | [`packages/vesti-search-files-core`](packages/vesti-search-files-core/README.md) | `@vesti/search-files-core` | 不依赖数据库或 MCP 的确定性历史文件定位核心 |
  219. | [`skills/vesti-memory`](skills/vesti-memory/SKILL.md) | `vesti-memory` | 指导客户端通过 MCP 渐进召回会话、项目和文件记忆 |
  220. | [`skills/vesti-handoff`](skills/vesti-handoff/SKILL.md) | `vesti-handoff` | 生成可验证的结构化交接包,可独立于 VESTI 使用 |
  221. ## 仓库结构
  222. ```text
  223. VESTI-SKILLS/
  224. ├── skills/
  225. │ ├── vesti-memory/ # MCP 记忆召回策略
  226. │ └── vesti-handoff/ # 跨会话结构化交接
  227. ├── packages/
  228. │ ├── vesti-memory/ # setup / status / sync / doctor CLI
  229. │ ├── vesti-capture-runtime/ # 独立采集 daemon 与 IPC client
  230. │ ├── vesti-mcp/ # 只读 stdio MCP server
  231. │ ├── vesti-memory-core/ # SQLite 记忆核心
  232. │ └── vesti-search-files-core/ # 历史文件定位核心
  233. ├── examples/ # 核心包端到端示例
  234. └── benchmarks/ # 文件检索评测与审计材料
  235. ```
  236. ## 数据目录与环境变量
  237. 默认数据布局:
  238. ```text
  239. ~/.vesti/
  240. ├── db/vesti.db
  241. ├── vault/
  242. ├── logs/capture-daemon.log
  243. └── runtime/
  244. ```
  245. - `VESTI_HOME`:移动整套 VESTI 数据目录。
  246. - `VESTI_DB_PATH`:只覆盖 SQLite 数据库路径。
  247. - `VESTI_CAPTURE_DISABLED=1`:仅在明确需要查询静态数据库快照时禁用自动采集。
  248. ## 可选集成
  249. [VESTI-APP](https://github.com/221250144/VESTI-APP) 提供可选的桌面浏览与管理体验。
  250. 本仓库的采集、MCP 和 Skill 不依赖 App。若要让 App 查看同一数据库,
  251. 不要同时启用 App 的旧捕获器和独立采集服务写入该库。
  252. 另有 [VESTI 浏览器扩展](https://github.com/221250144/VESTI),用于导入网页端对话。
  253. ## License
  254. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.