vectors-plugin

A Claude Code / Codex / opencode / Claude Desktop / VS Code / Antigravity plugin that ships a global, local, project-partitioned semantic RAG store — the vector-index skill plus an MCP server exposing it as live tools.

One PostgreSQL + pgvector database holds many projects; each is its own embedded + cross-encoder-reranked index. The active project is auto-resolved from the working directory, so an agent working inside a repo gets that repo's retrieval automatically. You can also search globally across every project at once. Everything runs locally: no API keys, no network at query time, no Python — embeddings and reranking are pure JS/WASM (@xenova/transformers, ONNX), run directly on Bun with no build step.

VINDEX_DSN              one PostgreSQL + pgvector database
  ├── scene/            a project (own documents + chunks + vectors + root)
  ├── portfolio/
  └── rustbook/

It also learns from the conversation: hooks in Claude Code, Codex, and Antigravity record each user intent, how often similar asks recur, the assistant's response, and whether it resolved the intent — then inject prior known resolutions (and failures to avoid) into context before the next reply. Recall is a fast, model-free lexical lookup; grading uses a local Ollama judge with a transcript-heuristic fallback. Toggle off with VINDEX_INTENT_DISABLE=1.

Full specification: spec.md — exhaustive data model, retrieval pipeline, daemon, MCP tools, CLI, and config.

Headline feature: AST + symbol-graph ingestion

Code files are chunked by tree-sitter into one chunk per named declaration — functions/methods become symbol units, classes/interfaces/ types/enums/consts become definition units — each titled by its symbol name (e.g. src/geo.ts › seedMesh). Imports are persisted as reference(kind='file') + mentions link edges, giving you an import graph in the same store. Supported: ts, tsx, js, py, go, rust, java, c, cpp, ruby, php, c#, swift, kotlin, scala, lua (via web-tree-sitter + tree-sitter-wasms, pure JS/WASM). Unsupported languages fall back to the line-window chunker.

Requirements

• Bun ≥ 1.2 (runs the TypeScript directly — no build step)
• PostgreSQL 16 + pgvector ≥ 0.7

setup.sh installs both for you (Homebrew on macOS, apt on Linux) — see Install. No Docker required. If you already run Postgres, just point VINDEX_DSN at it:

export VINDEX_DSN=postgres://localhost:5432/vectors

Install

One command provisions everything — Bun, PostgreSQL 16 + pgvector, the schema, the global vectors CLI, the background daemon, and MCP/skill wiring for every detected editor. No Docker.

bash setup.sh                   # full install (prompts before the daemon)
bash setup.sh --yes             # non-interactive (daemon included)
bash setup.sh --no-daemon       # everything except the daemon
bash setup.sh --no-db           # skip Postgres provisioning (use existing $VINDEX_DSN)
vectors doctor                  # verify Bun, DSN, Postgres, pgvector, schema, daemon
vectors db                      # every table with row counts + size
vectors db chunk --limit 5      # print a table's rows, prettily

It is idempotent; reverse the editor/MCP wiring + daemon with bash setup.sh --uninstall (the Postgres store is left intact). vectors setup on its own just (re)applies the schema + default embedding space to $VINDEX_DSN.

Usage

Index a whole project in one command — it creates the project, attaches the source, and ingests it (incremental, diff-by-hash). The root defaults to the cwd and a Git origin remote becomes the citation-URL template, so the common case needs no flags:

# index the project you're standing in
cd ~/Documents/Projects/scene
vectors index                              # name from package.json/Cargo.toml/… (falls back to the folder name)
vectors index scene                        # or name it explicitly; root = cwd; git remote → blob URLs

# or point at a path with explicit globs; re-run anytime → incremental re-ingest
vectors index scene ~/Documents/Projects/scene \
  --glob '**/*.ts' --glob '**/*.md'
vectors index scene --rebuild              # wipe + rebuild from scratch

# search the current project (hybrid dense+lexical, reranked)
vectors search "deterministic seeded geometry"

# search ACROSS every project (or a subset), merged + reranked
vectors search --global "welded indexed geometry deterministic seed"
vectors search "RRF fusion" --projects scene,rustbook --json
# (an `all:` query prefix also forces global)

# list projects (* = active); pass a name for its config + stats
vectors ls
vectors ls scene

--no-rerank gives raw fused order (faster, skips the cross-encoder); --json emits machine-readable output. The project is auto-resolved from the cwd when omitted.

Interactive shell

Run vectors with no arguments to open the interactive TUI (built on opentui): command autocomplete over the registry, a project switcher (Ctrl-P), and a query-first prompt — a bare line searches the active project.

vectors                         # autocomplete · Ctrl-P switch · :project NAME · :help · :q

Background daemon

Keeps the store current: a chat feeder (mirrors Claude transcripts — incl. subagent transcripts — the global prompt history ~/.claude/history.jsonl, Codex rollouts, and Gemini/Antigravity chats into session/message), a source feeder (re-ingests changed files), and a digest worker (embeds new content; optional local-Ollama summaries / fact extraction). Install as a service (launchd on macOS, systemd --user on Linux):

vectors daemon start            # install + start the service
vectors daemon stop             # stop + remove it
vectors daemon status | logs

Editors / MCP

bash setup.sh wires the bundled vectors MCP server into every harness it finds (skill + /vectors command + MCP entry). MCP tools:

search, search_global, current_project, list_projects, project_status, ingest, reindex, create_project, add_source, validate_citations, resolve_reference, recall_intents, resolve_intent.

Run the server standalone with vectors mcp (the bundled .mcp.json points plugin installs at bun ${CLAUDE_PLUGIN_ROOT}/src/mcp/server.ts). For a network-reachable endpoint (reverse proxies, remote agents) run vectors mcp http — streamable HTTP on 127.0.0.1:8765 (VINDEX_MCP_HTTP_PORT), serving POST/GET/DELETE /mcp + GET /health.

3D viewer

vectors viewer                  # live server → http://localhost:7341
vectors viewer scene            # serve a specific project
vectors viewer --all            # serve the `*` all-projects scope
vectors viewer --port 9000      # override the port (VINDEX_VIEWER_PORT/PORT)

A three.js "synapse" navigator that PCAs each project's embedding space to 3D and links nearest neighbours; type to search, drag to orbit. Two panels: a left tree (project switcher, search, results/intents/sources▸docs▸chunks, live activity) and a right 3D stage with depth-of-field and a node-detail overlay. three.js is vendored via npm (no CDN); there is no static-export mode — the live server is the only way to run it.

Environment variables

VINDEX_* is canonical; legacy UKDB_* names are accepted as deprecated aliases.

Architecture

src/
  cli/          command registry + dispatch + interactive TUI (tui.ts, opentui)
  db/           pool, schema/migrations, project registry + cwd resolution, ingest
  chunk/        chunker (md/code/text), ast.ts (tree-sitter symbol chunks + import graph), units
  embed/        embedder (mean-pool + L2-norm) + cross-encoder rerank — pure JS/WASM (ONNX)
  search/       hybrid dense+sparse RRF + rerank + confidence; grounding, references, assemble, orchestration
  intents/      Postgres-backed intent memory (record/recall/resolve/grade)
  daemon/       supervisor + chat/source feeders + digest worker
  mcp/          MCP server: stdio + streamable HTTP (13 tools)
  viewer/       3D synapse viewer HTTP + JSON API (PCA) + static asset serving
hooks/          intent-memory hooks (Claude Code + Codex + Antigravity)
references/     unified-knowledge-db.sql (full DDL) + design docs
assets/viewer/  viewer front-end bundle (index.html, viewer.css, ES modules)
skills/vector-index/   SKILL.md, daemon tooling, viewer bundle mirror, reference docs

Pipeline: per-project files → chunk → embed → store (ingest, incremental diff-by-hash), then query → embed → dense+sparse → RRF → cross-encoder rerank (offline). Global search fans out across projects, merges, and applies one rerank so hits are comparable even across embedding models.

Scripts

bun run typecheck     # tsc --noEmit
bun run lint          # eslint (zero warnings enforced)
bun test              # bun test
bun run wire          # bash setup.sh
bun run unwire        # bash setup.sh --uninstall
bun run assets:sync   # mirror assets/viewer/ into skills/vector-index/assets/viewer/

Roadmap

Planned, not yet implemented:

• Daemon remote backup — an opt-in pg_dump -Fc of the whole store on a cadence (VINDEX_BACKUP_PROVIDER, ~daily), pushed to one or more providers: a local folder (point it at a OneDrive / Google Drive sync folder for zero-API cloud backup), an rclone remote, an Obsidian vault, and/or a Notion manifest page — with retention. The store is a single Postgres DB today, so pg_dump/pg_restore already work manually; this would automate it inside the background daemon.

See spec.md for the complete specification and skills/vector-index/SKILL.md for the skill docs. MIT licensed.