内容
# Grasp
[](https://github.com/krishpinto/grasp/actions/workflows/ci.yml)
[](LICENSE)
> **被动、本地、零-API 的 AI 编程代理内存解决方案，以及一个 3D 应用来可视化它**
Claude Code 已经自动将每次会话的记录写入磁盘。 **Grasp 读取这些记录，只保留有意义的时刻** —— 决策、文件更改、错误修复、摘要 —— 将它们存储为可搜索的数据库和人类可读的 Markdown，本地嵌入以进行语义搜索，并为您提供一个桌面应用程序，以 3D **内存图** 的形式快速浏览项目历史。
代理永远不会参与写入路径。没有钩子，没有 API 密钥，没有云，没有单独的数据库服务器。如果代理运行，Grasp 会捕获它。
> *"我从不告诉它记住任何事情，但我可以打开一个我项目中所有决策的地图。*
<p align="center">
<img src="docs/graph.gif" alt="Grasp 3D 内存图 — 飞速浏览项目决策历史" width="100%">
</p>
---
## 为什么它与众不同
"AI 内存" 空间竞争激烈，因此 Grasp 在其领域内有明确的定位：
| | Grasp | 典型的内存工具 |
|---|---|---|
| **捕获** | **被动** — 监视记录文件 | 代理必须调用工具 / 您提示 "记住这个" |
| **存储内容** | 您的 **决策和对话历史** | 通常存储代码结构，或逐字记录所有内容 |
| **界面** | **3D 决策图 + 文档，在桌面应用程序中** | 没有 UI，或原始数据库浏览器 |
| **嵌入** | **本地** (candle) — 没有 API | 云嵌入 API |
| **占用** | 一个 Rust 引擎，SQLite，Markdown | Python + 矢量数据库 + 云，通常 |
楔形设计：**零摩擦被动捕获 + 视觉决策图**，完全本地。
---
## 工作原理
```
Claude Code ──自动写入──▶ 记录文件 (~/.claude/projects/*.jsonl)
│
▼
引擎 (Rust, grasp-core)
解析 → 提取信号 → 编辑机密 → 存储两者
SQLite + FTS5 (快速搜索) 和 Markdown (人类真实来源)
→ 本地嵌入 (candle) → 混合搜索 (BM25 + 余弦，RRF 融合)
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
Grasp CLI MCP 服务器 Tauri + React 应用
(导入/搜索) (代理回忆内存) (搜索 · 3D 图 · 文档)
```
1. **捕获** — 一个 `notify` 监视器在记录文件写入时读取。被动；代理不执行任何操作。
2. **提取** — 容错 JSONL 解析器 → 保留决策（带理由）、文件写入（内容和原因）、错误修复、摘要、问题；丢弃管道（压缩摘要、IDE 事件、搜索噪音）。
3. **编辑** — 机密（私钥、JWT、 `sk-…`/`ghp_…`/`AKIA…`， bearer tokens， `KEY=value`）在存储前被清除。
4. **存储** — SQLite (`chunks` + FTS5) + 每日 Markdown， SHA-256 deduplicated。
5. **嵌入** — candle 运行 `all-MiniLM-L6-v2` （384-dim）本地；约 90 MB 模型，仅需下载一次。
6. **搜索** — BM25 关键词 **和** 余弦语义，融合 Reciprocal Rank Fusion（k=60）；如果没有向量，则回落到 BM25。
---
## 应用
> **下载应用安装程序** — `Grasp-Setup.exe` 在
> [最新版本](https://github.com/krishpinto/grasp/releases/latest) — 或从源代码运行 `pnpm tauri dev`。以下的一行安装程序设置了引擎
> + Claude Code 内存；应用是一个单独的下载。
- **加载动画** → **概览**：整个系统的 3D "大脑" 每个项目。
- **引导式聚光灯** 首次使用时，指向您的记忆。
- **存档**：每个项目一个干净的卡片。
- **项目视图**：该项目的 **3D 图** （轨道 / 缩放 / 平移 — "观察者模式"）+ 作用域搜索。
- **应用内文档**：一个有动画管道的 "工作原理" 说明。
图节点是记忆（按类型着色）和 **文件** 它们触及；边是
**会话** 顺序，**共享文件**，和 **语义相似性** — 因此相关决策
在几天内连接，不仅仅是在一个会话内。
---
## 功能
- ✅ **实时被动捕获** (`grasp watch` 和应用内监视器)
- ✅ **混合搜索** — BM25 (FTS5) + 本地语义嵌入，RRF 融合
- ✅ **3D 内存图** — 可轨道，具有文件节点 + 语义边
- ✅ **机密编辑** 在存储任何内容之前
- ✅ **MCP 服务器** — `query_memory` （自动作用于当前项目） / `save_context` / `list_projects`
- ✅ **Markdown 真实来源** — 可读，可 git 提交，数据库存活
- ✅ **检索评估工具** (`grasp eval`) — BM25 与混合命中率
---
## 快速入门（Windows）
**一键安装引擎** — 下载预构建的构建并将嵌入模型
**捆绑在一起** （无需 Rust，无需构建，无需单独下载），
注册它与 Claude Code，并导入您的历史记录：
```powershell
irm https://github.com/krishpinto/grasp/releases/latest/download/install.ps1 | iex
```
然后打开一个 Claude Code 会话并询问您的过去工作 — 它将自动使用 Grasp。
就是这样。
> **一键安装程序为您提供的内容：** 内存 **引擎** — 被动捕获，
> 混合搜索，和 **MCP 服务器** 以便 Claude Code 回忆您的历史记录。
> **桌面应用程序** （3D 内存图）作为单独的下载提供
> **`Grasp-Setup.exe`** 在 [最新版本](https://github.com/krishpinto/grasp/releases/latest)。
<details><summary>手动步骤</summary>
Grasp 需要 **Rust** 和 **C 编译器** （用于捆绑的 SQLite）。在 Windows
上没有 Visual Studio，使用便携式 GNU/MinGW 工具链有效，无需管理员权限：
```powershell
# 1. Rust — GNU 工具链，无需 MSVC (https://rustup.rs)
rustup default stable-x86_64-pc-windows-gnu
# 2. 便携式 MinGW gcc 在 PATH 上（例如 WinLibs UCRT），因此捆绑的 SQLite 编译。
# 3. Node + pnpm 用于 UI
pnpm install
```
运行：
```powershell
pnpm tauri dev # 桌面应用程序 (Vite + Tauri, 热重载)
# 或驱动引擎无头：
cargo run -p grasp-cli -- import # 导入 ~/.claude/projects
cargo run -p grasp-cli -- embed # 生成向量（语义搜索）
cargo run -p grasp-cli -- search candle toolchain
```
注册它与 Claude Code （自动写入 MCP 配置）：
```powershell
cargo run -p grasp-cli -- setup
```
> macOS/Linux 默认提供 C 编译器，因此只需要 Rust + Node/pnpm。
</details>
---
## CLI
```
grasp import [--path DIR] 导入记录（默认 ~/.claude/projects）
grasp embed 生成嵌入（启用混合搜索）
grasp search <query…> 混合（或关键词）搜索
grasp watch [--path DIR] 实时导入会话写入
grasp autostart [--off] 在每次登录时在后台运行捕获
grasp eval 运行检索评估集
grasp graph [--project SLUG] 以 JSON 打印内存图
grasp projects | stats 注册表 / 总数
grasp setup 自动将 MCP 服务器注册到 Claude Code
grasp mcp 通过 stdio 运行 MCP 服务器
grasp redact 用当前机密模式重新清除存储的内存
grasp forget --project SLUG | grasp reset --yes
```
## 与 Claude Code （MCP）一起使用
```powershell
grasp setup # 自动将 MCP 服务器注册到 Claude Code
```
（或手动：`claude mcp add grasp -s user -- "C:\path\to\grasp.exe" mcp`。）
然后，在会话内，只需询问 — *"我们对 X 做出了什么决定？"* — 然后 Claude
自动调用 `query_memory`。
---
## 数据和隐私
Grasp 捕获真实的记录，可以包含机密 — 因此在存储任何内容之前会运行一个 **编辑**
过程：私钥、JWT、提供商 API 密钥 (`sk-…`, `ghp_…`, `AKIA…`)， bearer tokens，和 `KEY=value` 赋值被替换为 `[REDACTED]` 标签。所有内容都保留在您的机器上 — SQLite
数据库和 Markdown 文件位于您的本地数据目录中，嵌入模型在设备上运行。捕获到编辑改进之前？运行
`grasp redact` 以重新清除现有的数据库和 Markdown。
## 平台支持
在 **Windows** 上构建和测试（GNU/MinGW 工具链）。引擎编写为
跨平台 — 路径通过 `directories` crate 解析，而不是硬编码
— 因此 **macOS/Linux 应该有效**，只需 Rust + Node/pnpm，但它们尚未验证（CI 在 Linux 上构建引擎）。一键安装程序目前仅适用于 Windows；`install.sh` 和预构建的发布二进制文件正在规划中。
## 技术栈
Rust · Tauri 2 · React + Vite + TypeScript · SQLite (`rusqlite` + FTS5) ·
`candle` （本地嵌入）· `notify` · `react-force-graph-3d` + three.js.
```
crates/grasp-core 引擎：解析器 · 提取器 · 编辑器 · 存储 · 嵌入 · 搜索 · 图
crates/grasp-cli 命令行驱动器 + MCP 服务器
src-tauri Tauri 桌面壳 + 实时监视器
src React UI （概览 · 存档 · 项目图 · 文档 · 笔记查看器）
```
## 路线图
- **更多代理** — 捕获首先是 Claude Code；计划 Codex 及其他（MCP 读取端已经与任何 MCP 客户端一起工作）。
- **一键安装程序** — 因此 "试用" 不意味着 "编译它"。
- **自动回忆** — 一个 SessionStart 钩子，注入内存，然后您再询问。
- **更锐利的检索** — 诚实的评估集 + 调整后的提取。
## 许可证
MIT — 见 [LICENSE](LICENSE)。
