v1.2.10

Search local knowledge.
Build focused context.

Preindex code, notes, and memories for fast semantic retrieval. Turn coding tasks and current Git changes into one explained implementation map. Everything stays local.

Install ivygrep Source Context Packs Notes & Memory

Terminal - ig

# Retrieve a decision from preindexed notes.
$ ig "what did we decide about cache invalidation?" ~/notes
notes/decisions/cache.md:42
Invalidate on writes; keep reads cache-first.
$ ig context "fix refresh-token races" --since main --budget 8000
Selected: 14 snippets within 8,000-token budget
Roles: primary, definitions, callers, dependents, tests

Task context

One task. One branch. One implementation map.

Not a longer result list. A bounded pack connecting current work to code an agent needs to understand before editing.

Current work becomes retrieval signal

ig context --since main combines task anchors with committed branch changes, staged and dirty files, untracked files, and paths found in an issue or stack trace. It follows dependencies, dependents, definitions, callers, references, tests, configuration, docs, and recent co-changes.

PrimaryDependenciesDependentsDefinitionsCallersReferences TestsConfigDocs

Each item includes exact lines, its role, why it was selected, and how it relates to the task.

$ ig context "fix refresh-token races" --since main --budget 8000

# ivygrep context
...
Budget: 3842 / 8000 estimated tokens
Coverage: 7 files | 2 primary | 1 definitions | 1 dependencies | 1 dependents | 1 callers | 0 references | 1 tests | 0 config | 0 docs
Candidates: 31 retrieved | 14 selected

## Evidence
### 1. src/auth/refresh.rs:42-88 [primary, definition]
Why: task anchor; changed implementation.
Signals: lexical, symbol, git change.

Branch-aware

Committed and uncommitted changes shape selection before graph expansion begins.

Relationship-aware

Owning code, callers, dependencies, tests, configuration, and docs stay connected.

Budget-aware

Selection, deduplication, and trimming produce one pack sized for the receiving agent.

Beyond code

Search notes by meaning

Markdown vaults, research logs, meeting notes, decisions, and agent memories stay local.

Local semantic recall

Index notes once. CLI, MCP, Web, and TUI search them while watcher keeps index current.

74.9% recall@20 at 87.63 ms warm p95 on MemoryQuest.

Benchmark measures retrieval only; answer accuracy is outside scope.

Methodology and results Raw JSON

# Build local semantic index once.
$ ig --add ~/notes --wait-for-enhancement

# Reuse it for memory retrieval.
$ ig -n 20 \
  "what did we decide about cache invalidation?" \
  ~/notes

Local vaults

Search Markdown, text, JSON, and other supported documents without uploading notes or queries.

Live memory

Filesystem watcher updates changed chunks and vectors instead of rebuilding whole collection.

Inspect evidence

Results preserve exact file paths, lines, scores, and previews so retrieved memories stay auditable.

Capabilities

Built for live knowledge, not one-off searches

Task state, repository relationships, notes, and incremental indexes stay connected across CLI, MCP, and Web.

🎯

Task-aware inputs

Combine a task, issue, trace, branch diff, staged files, and dirty worktree before selecting code.

🕸️

Repository relationships

Expand from task anchors through definitions, callers, references, dependencies, dependents, tests, configuration, docs, and recent co-changes.

📦

Bounded evidence

Token-aware selection and deduplication produce one pack with exact paths, lines, roles, reasons, and relationships.

🌿

Thin worktree overlays

Worktrees reuse the repository base index and store only divergent chunks and tombstones across lexical, vector, and relationship stores.

⚡

Incremental availability

Changed chunks update incrementally. Lexical results remain available while hash and neural vectors build in the background.

🧭

Exact and semantic

Move between semantic notes, natural-language code intent, literal text, symbols, references, callers, paths, and project-wide search.

🔁

One context contract

CLI, JSON, MCP, and Web expose the same structured search results and task-context packs.

🔒

Local by design

No hosted inference or telemetry. Code, notes, queries, embeddings, and indexes stay on your machine.

Web interface

Browse indexed workspaces

The local browser UI searches tracked workspaces, scopes results to a folder, and opens indexed files beside the result list.

Result cards show language icons, syntax-highlighted snippets, line markers, and selected-state highlighting. The file viewer highlights focused result lines and previews Markdown with a source toggle.

Loopback stays zero-config. A non-loopback bind prints an authenticated URL. On another device, replace only 127.0.0.1 with the server's LAN or Tailscale address and preserve the complete token=... query string. Open it directly and do not share it: the browser exchanges it for an HttpOnly session cookie, then removes it from the address. Restart the daemon to invalidate access.

Non-loopback serving uses plain HTTP: the token authenticates requests but does not encrypt source or results. Use a trusted network only, preferably Tailscale or an SSH tunnel. Never expose the port directly to the internet or untrusted Wi-Fi.

$ ig --web
$ ig --web "auth flow" .
$ ig --web --host 0.0.0.0 --port 4747

Architecture

How indexing and search fit together

BM25 and literal search are available first; background jobs add hash and neural vectors.

Lexical index

File chunks go into SQLite and Tantivy first, so search works before vector jobs finish.

Hybrid fusion

BM25, literal matches, symbols, paths, and vector hits combine through Reciprocal Rank Fusion.

Local vectors

The daemon adds hash vectors and locally cached 256-dimensional static-retrieval-v1 vectors in the background. macOS releases use Accelerate-backed CPU math; the shell installer can select Apple Silicon Metal or Linux CUDA archives when available.

Git-aware indexing

Worktrees share a base index. Branch switches re-index only changed files.

Worktree overlays

Each worktree references the shared base index. SQLite, lexical, and vector overlays store changed chunks and tombstones.

Branch-switch deltas

Merkle reconciliation re-indexes changed files. Content hashes skip byte-identical files across branches.

System evidence

Context stays practical at repository scale

Three hash-only trials on deterministic synthetic CC0 data measure local indexing, query latency, and footprint at scale.

6.19 ms

Warm CLI p95

150,576 chunks/s

Controlled indexing

0.42 GiB

Final index size

Median of three sequential v1.2.7 trials on deterministic synthetic CC0 data in hash-only mode. These are scale and footprint measurements, not semantic quality or agent outcomes. Hardware, repository shape, index state, and load affect absolute results.

Current-release evidence Public million-chunk benchmark Benchmark dashboard

Language support

45 language/file types, 24 Tree-sitter ASTs

Tree-sitter sources get function/class-level chunks. Other supported files use heuristic chunks.

Tree-sitter AST 24 languages

Rust Python Go JavaScript TypeScript Java C C++ C# Scala Kotlin PHP Ruby Swift Elixir Zig Bash Haskell OCaml Lua Dart Objective-C Perl Starlark macros/targets

Heuristic chunking 21 more

Nim Groovy Erlang Clojure R Julia PowerShell SQL Protobuf Thrift GraphQL Terraform Dockerfile Makefile Markdown HTML CSS XML Config JSON Text

Model Context Protocol

MCP for coding agents

Use MCP search to find code. Set output=context_pack, optional since=main, and a token budget to build the same context pack available from CLI and Web.

One-command setup

The installer preserves existing configuration, verifies MCP, and runs a search.

Claude Code

ig agent install claude

Codex

ig agent install codex

Cursor

ig agent install cursor

ig agent doctor

Manual MCP setup

Claude Code

claude mcp add -s user ig -- ig --mcp

Codex

codex mcp add ig -- ig --mcp

Gemini CLI

gemini mcp add --scope user --transport stdio ig ig --mcp

Cursor

"ig": { "type": "stdio", "command": "ig", "args": ["--mcp"] }

OpenCode

"ig": { "type": "local", "command": ["ig", "--mcp"] }

MCP search settings

Pass the absolute repository or worktree path to ig_search. Use a natural-language query for concepts, literal=true for identifiers, or output=context_pack with since=main and budget_tokens=8000 for implementation context.

The first search creates an index and starts incremental watching. Worktrees reuse one shared base index and store only divergent chunks and tombstones.

Codex guide Claude Code guide Cursor guide Gemini CLI guide OpenCode guide MCP Registry

MCP search flow

🤖

Agent sends query

"find error handling logic"

→

🔍

ig searches index

BM25 + Vector + Literal

→

📄

Returns top chunks

Function bodies, classes, imports

→

✅

Agent gets context

Without loading entire files

Open source

Contributing

Choose a scoped issue, run the relevant checks, and keep the pull request focused.

Start small

Pick a scoped issue with setup and validation guidance.

Good first issues

Discuss larger changes

Use Discussions for questions and designs that affect storage, ranking, or compatibility.

Discussions

Open a pull request

Follow the contributor guide and include the checks that cover the change.

Contributor guide

Get started

Install ivygrep

The installer selects CUDA on compatible NVIDIA Linux hosts and Metal on Apple Silicon. Run ig hardware to inspect the selected build.

Homebrew for macOS and Linux

$ brew install bvolpato/tap/ivygrep

Metal on Apple Silicon. Portable elsewhere.

Shell installer for Linux and macOS

$ curl -fsSL https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.sh | sh

Detects CUDA, Metal, and missing runtime libraries.

Windows PowerShell

irm https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.ps1 | iex

Portable Windows build.

Search once. Build context once.

Find code by intent

ig "where is refresh token rotated?"

Build bounded task context

ig context "fix refresh-token races" --since main --budget 8000