https://github.com/krishpinto/grasp
Passive, local, zero-API memory for AI coding agents — captures Claude Code transcripts, embeds them on-device, and shows them as a 3D memory graph. Rust + Tauri.
https://github.com/krishpinto/grasp
ai-memory claude embeddings local-first mcp rag react rust sqlite tauri
Last synced: about 1 hour ago
JSON representation
Passive, local, zero-API memory for AI coding agents — captures Claude Code transcripts, embeds them on-device, and shows them as a 3D memory graph. Rust + Tauri.
- Host: GitHub
- URL: https://github.com/krishpinto/grasp
- Owner: krishpinto
- License: mit
- Created: 2026-06-19T03:07:41.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-06-25T15:12:33.000Z (12 days ago)
- Last Synced: 2026-06-25T17:07:12.627Z (12 days ago)
- Topics: ai-memory, claude, embeddings, local-first, mcp, rag, react, rust, sqlite, tauri
- Language: Rust
- Size: 6.06 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Grasp
[](https://github.com/krishpinto/grasp/actions/workflows/ci.yml)
[](LICENSE)
> **Passive, local, zero-API memory for AI coding agents — and a 3D app to *see* it.**
Claude Code already writes a transcript of every session to disk. **Grasp reads
those transcripts, keeps only the meaningful moments** — decisions, file changes,
error fixes, summaries — stores them as a searchable database *and* human-readable
Markdown, embeds them locally for semantic search, and gives you a desktop app to
fly through your project's history as a 3D **memory graph**.
The agent never participates in the write path. No hooks, no API keys, no cloud,
no separate database server. If the agent ran, Grasp captured it.
> *"I never tell it to remember anything, and I can open a map of every decision
> my project ever made."*
---
## Why it's different
The "AI memory" space is crowded, so Grasp is deliberate about its niche:
| | Grasp | Typical memory tools |
|---|---|---|
| **Capture** | **Passive** — watches transcript files | Agent must call a tool / you prompt "remember this" |
| **What it stores** | Your **decisions & conversation history** | Often code structure, or verbatim everything |
| **Surface** | **3D decision graph + docs, in a desktop app** | No UI, or a raw database browser |
| **Embeddings** | **On-device** (candle) — no API, ever | Cloud embedding APIs |
| **Footprint** | One Rust engine, SQLite, Markdown | Python + vector DB + cloud, usually |
The wedge: **zero-friction passive capture + a visual decision graph**, entirely local.
---
## How it works
```
Claude Code ──auto-writes──▶ transcripts (~/.claude/projects/*.jsonl)
│
▼
ENGINE (Rust, grasp-core)
parse → extract signal → redact secrets → store BOTH
SQLite + FTS5 (fast search) and Markdown (human source of truth)
→ embed locally (candle) → hybrid search (BM25 + cosine, RRF-fused)
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
grasp CLI MCP server Tauri + React app
(import/search) (agent recalls memory) (search · 3D graph · docs)
```
1. **Capture** — a `notify` watcher reads transcripts the moment they're written. Passive; the agent does nothing.
2. **Extract** — tolerant JSONL parser → keeps decisions (with rationale), file writes (what & why), error fixes, summaries, questions; drops plumbing (compaction summaries, IDE events, search noise).
3. **Redact** — secrets (private keys, JWTs, `sk-…`/`ghp_…`/`AKIA…`, bearer tokens, `KEY=value`) are scrubbed *before* storage.
4. **Store** — SQLite (`chunks` + FTS5) + per-day Markdown, SHA-256 deduped.
5. **Embed** — candle runs `all-MiniLM-L6-v2` (384-dim) on-device; ~90 MB model, downloaded once.
6. **Search** — BM25 keyword **and** cosine semantic, fused with Reciprocal Rank Fusion (k=60); falls back to BM25 if no vectors yet.
---
## The app
> **Download the app installer** — `Grasp-Setup.exe` on the
> [latest release](https://github.com/krishpinto/grasp/releases/latest) — or run it
> from source with `pnpm tauri dev`. The one-line install below sets up the engine
> + Claude Code memory; the app is a separate download.
- **Loading splash** → **Overview**: the whole-system 3D "brain" of every project.
- **Guided spotlight** the first time, pointing you to your memories.
- **Archive**: a clean card per project.
- **Project view**: that project's **3D graph** (orbit / zoom / pan — "spectator mode") + a scoped search.
- **In-app docs**: an illustrated "How it works", with an animated pipeline.
Graph nodes are memories (colored by type) and the **files** they touched; edges are
**session** order, **shared file**, and **semantic similarity** — so related decisions
connect across days, not just within a session.
---
## Features
- ✅ Live **passive capture** (`grasp watch` and the in-app watcher)
- ✅ **Hybrid search** — BM25 (FTS5) + on-device semantic embeddings, RRF-fused
- ✅ **3D memory graph** — orbitable, with file nodes + semantic edges
- ✅ **Secret redaction** before anything is stored
- ✅ **MCP server** — `query_memory` (auto-scoped to the current project) / `save_context` / `list_projects`
- ✅ **Markdown source of truth** — readable, git-committable, survives the DB
- ✅ **Retrieval eval harness** (`grasp eval`) — BM25 vs hybrid hit-rate
---
## Quick start (Windows)
**Install the engine in one line** — downloads a prebuilt build with the
embedding model **bundled in** (no Rust, no build, no separate download),
registers it with Claude Code, and imports your history:
```powershell
irm https://github.com/krishpinto/grasp/releases/latest/download/install.ps1 | iex
```
Then open a Claude Code session and ask about your past work — it'll use Grasp
automatically. That's it.
> **What the one-liner gives you:** the memory **engine** — passive capture,
> hybrid search, and the **MCP server** so Claude Code can recall your history.
> The **desktop app** (the 3D memory graph) ships separately as
> **`Grasp-Setup.exe`** on the [latest release](https://github.com/krishpinto/grasp/releases/latest).
Manual steps
Grasp needs **Rust** and a **C compiler** (for the bundled SQLite). On Windows
without Visual Studio, a portable GNU/MinGW toolchain works with no admin:
```powershell
# 1. Rust — GNU toolchain, no MSVC needed (https://rustup.rs)
rustup default stable-x86_64-pc-windows-gnu
# 2. A portable MinGW gcc on PATH (e.g. WinLibs UCRT), so bundled SQLite compiles.
# 3. Node + pnpm for the UI
pnpm install
```
Run it:
```powershell
pnpm tauri dev # desktop app (Vite + Tauri, hot reload)
# or drive the engine headless:
cargo run -p grasp-cli -- import # ingest ~/.claude/projects
cargo run -p grasp-cli -- embed # generate vectors (semantic search)
cargo run -p grasp-cli -- search candle toolchain
```
Register it with Claude Code (auto-writes the MCP config):
```powershell
cargo run -p grasp-cli -- setup
```
> macOS/Linux ship a C compiler by default, so only Rust + Node/pnpm are needed.
---
## CLI
```
grasp import [--path DIR] ingest transcripts (default ~/.claude/projects)
grasp embed generate embeddings (enables hybrid search)
grasp search hybrid (or keyword) search
grasp watch [--path DIR] ingest live as sessions are written
grasp autostart [--off] run capture in the background at every login
grasp eval run the retrieval eval set
grasp graph [--project SLUG] print the memory graph as JSON
grasp projects | stats registry / totals
grasp setup auto-register the MCP server with Claude Code
grasp mcp run the MCP server over stdio
grasp redact re-scrub stored memories with current secret patterns
grasp forget --project SLUG | grasp reset --yes
```
## Use with Claude Code (MCP)
```powershell
grasp setup # auto-registers the MCP server with Claude Code
```
(or manually: `claude mcp add grasp -s user -- "C:\path\to\grasp.exe" mcp`.)
Then, inside a session, just ask — *"what did we decide about X?"* — and Claude
calls `query_memory` automatically.
---
## Data & privacy
Grasp captures real transcripts, which can contain secrets — so a **redaction
pass runs before anything is stored**: private keys, JWTs, provider API keys
(`sk-…`, `ghp_…`, `AKIA…`), bearer tokens, and `KEY=value` assignments are
replaced with `[REDACTED]` labels. Everything stays on your machine — the SQLite
database and Markdown files live in your local data directory, and the embedding
model runs on-device. Captured something before redaction improved? Run
`grasp redact` to re-scrub the existing database and Markdown in place.
## Platform support
Built and tested on **Windows** (GNU/MinGW toolchain). The engine is written to
be cross-platform — paths are resolved via the `directories` crate, not hardcoded
— so **macOS/Linux should work** with only Rust + Node/pnpm, but they aren't
verified yet (CI builds the engine on Linux). The one-command installer is
Windows-only for now; a `install.sh` and prebuilt release binaries are on the
roadmap.
## Tech stack
Rust · Tauri 2 · React + Vite + TypeScript · SQLite (`rusqlite` + FTS5) ·
`candle` (local embeddings) · `notify` · `react-force-graph-3d` + three.js.
```
crates/grasp-core the engine: parser · extractor · redactor · store · embeddings · search · graph
crates/grasp-cli command-line driver + MCP server
src-tauri Tauri desktop shell + live watcher
src React UI (overview · archive · project graph · docs · note viewer)
```
## Roadmap
- **More agents** — capture is Claude Code-first; Codex & others planned (the MCP read side already works with any MCP client).
- **One-click installer** — so "try it" doesn't mean "compile it".
- **Auto-recall** — a SessionStart hook that injects memory before you ask.
- **Sharper retrieval** — honest eval set + tuned extraction.
## License
MIT — see [LICENSE](LICENSE).