vexp Documentation

Introduction

vexp is a local-first context engine with session memory that reduces token consumption by 65–70% for any AI coding agent. Instead of passing entire files to the model, vexp analyzes your codebase with tree-sitter, builds an AST dependency graph, and returns only the relevant pivot nodes plus compact skeletons of supporting files. It also remembers what the agent explored, decided, and learned — across sessions, linked to the code graph.

The VS Code extension is the primary distribution. A standalone CLI (npm install -g vexp-cli) and a direct binary mode (vexp-core mcp --workspace .) are also available for terminal-only workflows. The extension is fully self-contained: the Rust daemon (vexp-core) and the MCP server (vexp-mcp) are bundled inside the package — no external dependencies required.

How it works

Installation

vexp is available as a VS Code extension (for VS Code, Cursor, Windsurf, and any Electron fork) or as a standalone CLI for terminal-only workflows. Both include the same Rust daemon and MCP server — choose the distribution that fits your setup.

First Run

Configuration

{
  "vexp.maxContextTokens": 16000,
  "vexp.skeletonDetail": "detailed",
  "vexp.autoCommitIndex": true,
  "vexp.logLevel": "warn"
}

Commands

Supported Languages

vexp uses tree-sitter grammars bundled directly in the binary — no downloads at runtime.

Supported Agents

When you run vexp: Setup Workspace, the extension scans for known AI agents in your workspace and automatically writes or patches their configuration files to register vexp as an MCP server.

Manual configuration

vexp auto-configures your agents when you run vexp: Setup Workspace (VS Code) or vexp setup (CLI). If auto-detection doesn't work, you can create configuration files manually.

# VS Code
ls ~/.vscode/extensions/vexp.vexp-vscode-*/dist/mcp-server.cjs

# Cursor
ls ~/.cursor/extensions/vexp.vexp-vscode-*/dist/mcp-server.cjs

# Windsurf
ls ~/.windsurf/extensions/vexp.vexp-vscode-*/dist/mcp-server.cjs

{
  "mcpServers": {
    "vexp": {
      "command": "node",
      "args": ["<path>/mcp-server.cjs"]
    }
  }
}

{
  "mcpServers": {
    "vexp": {
      "command": "node",
      "args": ["<path>/mcp-server.cjs"]
    }
  }
}

{
  "mcpServers": {
    "vexp": {
      "command": "node",
      "args": ["<path>/mcp-server.cjs"],
      "alwaysAllow": [
        "run_pipeline", "get_context_capsule",
        "get_impact_graph", "search_logic_flow",
        "get_skeleton", "index_status",
        "workspace_setup", "submit_lsp_edges",
        "get_session_context", "search_memory",
        "save_observation"
      ]
    }
  }
}

{
  "servers": {
    "vexp": {
      "type": "stdio",
      "command": "node",
      "args": ["<path>/mcp-server.cjs"]
    }
  }
}

{
  "context_servers": {
    "vexp": {
      "command": {
        "path": "node",
        "args": ["<path>/mcp-server.cjs"]
      }
    }
  }
}

{
  "mcpServers": [
    {
      "name": "vexp",
      "command": "node",
      "args": ["<path>/mcp-server.cjs"],
      "type": "stdio"
    }
  ]
}

MCP Tools

vexp exposes 11 MCP tools. Your AI agent calls them automatically based on the instructions in the generated config file. You can also call them directly from the Command Palette for debugging.

Primary Tool

Specialized Tools

Session Memory Tools (Free Tier)

The following 3 tools are available on all plans, including Starter. They provide session memory linked to the code dependency graph.

Session Memory

vexp automatically captures what the agent explores, decides, and learns — across sessions, across repos, linked to the code dependency graph. When code changes, linked memories are marked stale automatically. Both run_pipeline and get_context_capsule auto-surface relevant memories from previous sessions.

Auto-capture

Every MCP tool call (except index_status, workspace_setup, and save_observation) is automatically recorded as a compact observation. Per-tool extraction captures the most relevant data: get_context_capsule records intent + pivots + file paths, get_impact_graph records the symbol FQN, and so on.

Capsule memory auto-surfacing

get_context_capsule automatically includes relevant memories from previous sessions — no extra tool calls needed. Memories are ranked using a multi-signal scoring formula combining text relevance, semantic similarity, recency, and code-graph proximity — with a staleness penalty for outdated observations.

Passive file change detection

vexp passively monitors every file change in real time via a file watcher. When a change is detected, vexp computes AST-level structural diffs — not just "file modified" but exactly which symbols changed and how:

A background process automatically correlates file changes with recent agent activity and generates observations linked to the affected code symbols.

Anti-pattern detection

vexp automatically detects common agent anti-patterns and generates error-type observations:

• Dead-end exploration — a symbol is added then removed in the same session, indicating wasted effort.
• File thrashing — a file is modified repeatedly in quick succession, suggesting the agent is stuck in a loop.

Progressive nudge system

vexp gently reminds agents to use save_observation for important decisions. The nudge intensity decreases over time: a full explanation on the first tool call, a brief one-liner every 5 calls, and it self-disables entirely once the agent cooperates (calls save_observation at least once in the session).

Staleness detection

Observations linked to code symbols via save_observation are automatically marked stale when those symbols change during incremental sync. Stale observations are penalized in search ranking but not deleted — the reasoning may still be valid even if the code changed.

Progressive disclosure

Observations are returned at 3 detail levels depending on the context:

Session lifecycle

Each MCP connection gets a unique session ID. vexp auto-creates sessions on first request and detects the agent from environment variables (Claude Code, Cursor, Windsurf, Copilot, etc.).

Sessions inactive for more than 2 hours are compressed by a background task: unique file paths, node IDs, type distribution, and key terms are extracted into a structural summary. Ephemeral tool_call observations are deleted after compression; insight, decision, error, and manual observations are preserved permanently. Sessions older than 90 days are fully deleted.

Memory consolidation

When multiple auto-observations are semantically similar, vexp automatically merges them into a single consolidated observation. This reduces noise from repetitive agent actions while preserving information density. Manual observations (insight, decision, error) are never merged.

Project rules

When the passive observation engine detects recurring patterns in your workflow (3+ similar observations in the same scope), it auto-generates scope-aware project rule candidates. Rules are promoted to active after validation, and auto-invalidated when the relevant code changes significantly. Active rules are injected into get_context_capsule responses — your agent learns your project's conventions without manual configuration.

Git Integration

vexp stores the full index in .vexp/index.db (local, gitignored) and commits only a lightweight .vexp/manifest.json with blake3 per-file hashes. When a teammate clones the repo, vexp rebuilds the index incrementally from the manifest — typically under 5 seconds for a 5,000-file codebase.

Directory structure

repo-root/
├── src/
└── .vexp/
    ├── index.db          ← SQLite graph (local, in .gitignore)
    ├── index.db-wal      ← in .gitignore
    ├── index.db-shm      ← in .gitignore
    ├── manifest.json     ← per-file content hashes (git-tracked)
    └── .gitignore        ← excludes index.db and WAL files

Manifest-based workflow

vexp commits only manifest.json — a lightweight JSON file containing content hashes for every source file. The full index.db is never committed to git. When you clone or pull:

1. manifest.json arrives via git.
2. vexp compares the manifest hashes against local files.
3. Only changed files are re-indexed — unchanged files are skipped entirely.

This makes commits instant (no binary blob), clone-to-ready time under 5 seconds, and eliminates merge conflicts on large binary files.

Merge conflicts on manifest.json

manifest.json is a regular JSON file, but simultaneous edits on different branches can create conflicts. vexp installs a custom git merge driver (via .gitattributes) that automatically merges manifest.json by taking the union of all file hashes — no manual resolution needed.

Large repositories

Since only manifest.json is committed (~1 KB per 100 source files), repository bloat is never an issue regardless of codebase size. The local index.db can grow to 100+ MB for large codebases but stays out of git entirely.

Opting out of git integration

If you prefer not to commit the manifest, set vexp.autoCommitIndex to false in settings and add .vexp/manifest.json to your .gitignore. Each developer will rebuild from scratch on first open — still fast, but without incremental skip.

Multi-Repo Setup

vexp can index multiple repositories simultaneously and query across their boundaries. This is particularly useful for microservices, monorepos split across multiple git repositories, or frontend + backend pairs.

workspace.json format

{
  "name": "my-project",
  "version": "1",
  "repos": [
    {
      "alias": "frontend",
      "path": "/projects/my-project-frontend",
      "languages": ["typescript"],
      "role": "consumer"
    },
    {
      "alias": "backend",
      "path": "/projects/my-project-backend",
      "languages": ["go"],
      "role": "provider"
    }
  ],
  "cross_repo_links": [
    {
      "type": "openapi",
      "source": "backend:src/api/openapi.yaml",
      "consumer": "frontend:src/api/generated/"
    }
  ]
}

Cross-repo query

Once configured, MCP tools automatically traverse repository boundaries. Pass multiple repo aliases to target specific repositories:

get_context_capsule
  query: "Add the roles field to the user API response"
  repos: ["backend", "frontend"]

Cross-repo passive tracking

Every file change and tool call is automatically tagged with its repo_alias. The file watcher runs per-repo with a dedicated channel, and the passive correlator and staleness detection operate across repository boundaries. Observations propagate between repos — an insight discovered in the backend is surfaced when querying the frontend if the symbols are linked.

Bidirectional workspace navigation

Opening a secondary repository from a multi-repo workspace automatically loads the entire workspace context. You do not need to re-register repos or re-run the setup wizard — vexp detects the workspace configuration and activates all repos bidirectionally.

Cross-repo storage

Cross-repo relationship data is stored in a local registry shared across all workspaces on the machine. Per-repo indexes remain in each repository's .vexp/index.db (never committed to git).

Troubleshooting

Extension not activating

vexp activates when the workspace contains supported source files (.ts, .py, .go, .rs, etc.) or an existing .vexp/manifest.json.

• Ensure the workspace folder contains at least one supported source file.
• Check the VS Code Output panel: select vexp from the dropdown.
• Try vexp: Force Re-index from the Command Palette.

Index not updating

• Check the status bar — if it shows indexing…, a full re-index is already running.
• Run vexp: Show Index Status to see the current node count and last indexed commit.
• If the daemon appears stuck, restart it via vexp: Force Re-index.

Port 7821 already in use

Since v1.2.18, vexp automatically tries alternative ports when the default is busy (up to 10 retries) and writes the actual port to .vexp/mcp.port for agent discovery. In most cases, no manual intervention is needed. If you still need to force a specific port, change it in settings:

{
  "vexp.mcpPort": 7822
}

Binary permission denied (macOS / Linux)

On first install, the Rust binary may not be executable. The extension sets the correct permissions automatically, but if you see a permission error:

macOS Gatekeeper warning

vexp binaries are signed with an Apple Developer Certificate and notarized. If Gatekeeper blocks the binary, open System Preferences → Privacy & Security and click Allow next to the vexp entry.

Daemon crashes on startup

• Set vexp.logLevel to "debug" and restart VS Code.
• Check the Output panel for vexp daemon logs.
• On Linux: ensure /tmp is writable (the daemon uses a Unix socket there).
• On Windows: ensure the named pipe namespace is accessible (no restrictive AppContainer policy).

Multiple VS Code windows conflict

Since v1.2.18, vexp automatically shares a single daemon across all VS Code windows opened on the same workspace. The first window to start the daemon becomes the owner; subsequent windows adopt the existing daemon. If you experience connection issues across multiple windows:

• Close all VS Code windows for the workspace.
• Delete .vexp/daemon.sock and .vexp/daemon.pid if they exist.
• Reopen VS Code — the first window will start a fresh daemon.

Stale socket after crash

Since v1.2.19, vexp automatically cleans up socket, PID, and port files on shutdown. However, if the daemon was terminated with kill -9, these files may remain. vexp's hook guard detects stale sockets and falls back gracefully, but you can also clean up manually:

AI agent not using vexp tools

• Verify the MCP server is running: vexp: Show Index Status.
• Re-run vexp: Setup Workspace to regenerate the agent config file.
• For Claude Code: ensure the .claude/CLAUDE.md file is in the project root and that Claude Code picks up MCP servers from that file.
• For Cursor/Windsurf: check that the MCP extension is enabled in the editor settings and that the port matches vexp.mcpPort.

Manifest not updating

If manifest.json appears stale, run vexp: Force Re-index (VS Code) or vexp reindex (CLI) to regenerate it.

CLI-specific issues

CLI command not found after install

Ensure the npm global bin directory is in your PATH:

MCP server not responding (CLI)

Check that no other process is using the default port:

vexp-core binary not found (CLI)

The CLI downloads platform binaries on first install. If the download failed, force a reinstall:

Permission denied on CLI binary (macOS / Linux)

Privacy & Security

.vexp_ignore example

# Exclude secrets and environment files
.env*
*.pem
*.key
secrets/

# Exclude generated code
src/generated/
dist/
build/

# Exclude large data directories
data/
fixtures/large/

Plans & Limits

vexp counts indexed nodes — not lines of code or file count. A node is a distinct symbol: function, class, method, interface, variable, or type alias. As a reference: the vexp codebase itself (~50 source files) generates ~500 nodes.

Starter plan paywall behavior

vexp never blocks you or loses data at the node limit. As you approach the limit:

• At 80% (1,600 nodes) — a non-blocking informational notification appears in the status bar.
• At 100% (2,000 nodes) — new files are still indexed but excess nodes are excluded from queries. Upgrade to Pro for 50,000 nodes and all 11 tools.

Daily usage quota (Starter)

Starter plan users get 8 pipeline + skeleton calls per day — enough to explore vexp on real projects. The status bar shows your current usage (e.g. 3/8) with color progression as you approach the limit. The quota resets daily at midnight UTC. Pro and Team plans have no daily limits.

Upgrade flow

To upgrade from Starter to Pro or Team:

1. Click Start Pro or Start Team on the pricing page.
2. Complete payment on Stripe (monthly or annual billing).
3. You are redirected to a success page with your license key.

License activation

License status & upgrade prompts

Run vexp: Show License Status (VS Code) or vexp license status (CLI) at any time to see your current plan, node usage, and license expiry date.

vexp also shows automatic upgrade prompts as you approach your plan limits:

• 80% node usage — a non-blocking notification with an Upgrade to Pro button.
• 100% node usage — a warning that excess nodes are excluded from queries, with an Upgrade to Pro button.
• Multi-repo limit — a modal when you try to add a repository beyond your plan limit, with an Upgrade to Pro button.

License refresh & offline behavior

Both the VS Code extension and the CLI automatically refresh your license every 7 days by contacting vexp.dev. Each refresh extends your license validity by 30 days. No manual action is required.

Account management

To manage your subscription or re-activate your license on a new device:

1. Go to vexp.dev/account.
2. Enter the email associated with your subscription (or your team member email).
3. Click the login link sent to your email (magic link, no password required).
4. On the account page you can:
   • Activate in VS Code — one-click deep link to activate your license instantly.
   • Copy License Key — copy the key for manual activation via Command Palette.
   • Manage Subscription — open the Stripe billing portal (owner only).

Team member management

Team plan owners can add and remove team member emails directly from the account page. Each member can then log in independently at vexp.dev/account and activate their own VS Code instance — no need to share license keys or forward emails.

1. The team owner logs in and sees a Team Members section with a seat counter (e.g. 3/5 seats used).
2. Add a member by entering their email and clicking Add. The member count is limited by the number of seats purchased at checkout.
3. Remove a member by clicking the X button next to their email.
4. Each member logs in with their own email, sees their plan badge, and can activate in VS Code or copy the license key.