title: Getting Started description: Persistent vector memory for AI agents. One file per agent, MCP-native, local-first.

Getting Started with phorvec

Persistent vector memory for AI agents. One file per agent, MCP-native, local-first.

phorvec is a Rust-powered vector memory database purpose-built for AI agents. It ships as a single binary that speaks the Model Context Protocol (MCP), stores each agent's memory in a portable .avdb file, and runs entirely on your machine — no cloud account required, no data leaving your environment.

Whether you are building a single coding assistant or coordinating a fleet of specialized agents, phorvec gives you durable, searchable, semantically-aware memory that persists across sessions.

Installation

Phorvec ships exclusively as a pre-built, signed binary. There is no pip, cargo, brew, or other package-manager distribution path — and the source code is not public.

1. Download the binary for your platform from phorvec.com/download (Community is free and requires no account; paid tiers download from /account after sign-in).
2. Move it onto your PATH — typical locations: /usr/local/bin/phorvec on macOS / Linux, C:\Program Files\Phorvec\phorvec.exe on Windows.
3. Mark executable on macOS / Linux: chmod +x phorvec.
4. Verify: phorvec --version should print the release tag.

phorvec --version

The binary bundles an ONNX embedding model — no separate model download. It also self-checksums at startup against an embedded signed value and refuses to run if it has been patched. See Security for the manifest verification procedure.

Quick Start

MCP clients connect to phorvec over stdio. You generally don't run the server manually — your MCP client spawns it. If you want to sanity-check the binary works, run it and press Ctrl-C:

phorvec

This defaults to phorvec serve (stdio transport). For HTTP or SSE transports — useful for testing with curl or a browser — see the Deployment Guide.

Agent databases are stored in ~/.phorvec/data/ by default. Override with PHORVEC_DATA_DIR or edit ~/.phorvec/config.toml — see the Configuration Reference.

Connecting Your AI Editor

phorvec integrates with any MCP-compatible client. Add this snippet to your editor's MCP configuration and every tool in the Tool Reference becomes available to your agent immediately:

{
  "mcpServers": {
    "phorvec": {
      "command": "phorvec",
      "args": []
    }
  }
}

For per-client config file paths and platform-specific details — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, VS Code (Copilot Chat), Zed, Aider, Google Antigravity, OpenAI Codex CLI — see the dedicated MCP Client Setup reference. It also covers per-project data directories and multi-agent scoping.

Or, from the directory where you want phorvec installed, run phorvec init <client> and the binary will write the config for you (claude-code, cursor, windsurf, zed, cline, copilot, aider, antigravity, codex).

Transports

The MCP client setup above uses stdio — the recommended default. The same phorvec binary also speaks SSE and HTTP with bearer-token authentication, useful when you want to run phorvec as a long-running service that multiple clients connect to.

Pick stdio unless you have a specific reason to network the server. See the Deployment Guide for transport configuration, license placement, and air-gapped considerations.

Architecture Overview

phorvec is organized into three layers that work together to give each agent isolated, persistent, and semantically searchable memory.

┌─────────────────────────────────────────────────────┐
│                   MCP Client                        │
│         (Claude Code, Cursor, Windsurf, Cline)      │
└───────────────────────┬─────────────────────────────┘
                        │  MCP (stdio / TCP)
┌───────────────────────▼─────────────────────────────┐
│                     Nexus                           │
│   MCP request router · tool dispatch · auth layer   │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                 HandleManager                       │
│   Per-agent connection pool · lifecycle management  │
│   Opens / closes AgentDB handles on demand          │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                   AgentDB (.avdb)                   │
│   One file per agent · HNSW index · BM25 index      │
│   Knowledge graph · Context store · Audit log       │
└─────────────────────────────────────────────────────┘

Nexus is the top-level server process. It parses incoming MCP requests, enforces security policies (secret scanning, audit logging), and routes each tool call to the correct handler.

HandleManager maintains a pool of open database handles. When an agent makes its first request, HandleManager opens (or creates) that agent's .avdb file. Handles stay open for performance and are released cleanly on shutdown or inactivity timeout.

AgentDB is the on-disk database file. Each agent gets exactly one .avdb file. It contains the HNSW vector index, a BM25 full-text index, the knowledge graph, context branches, the memory store, and the append-only audit log — everything needed for that agent's memory, self-contained in a single portable file.

Environment Variables

Environment variables take precedence over values in config.toml. See the full Configuration Reference for all options.

Next Steps

• Core Features — explore hybrid search, knowledge graphs, memory management, and more
• Tool Reference — complete list of all 100+ MCP tools
• Configuration Reference — full config.toml reference
• Security — audit trails, secret detection, and compliance posture
• Enterprise Features — compute governance, health monitoring, and agent testing