title: Tool Reference
description: Complete reference for the 140+ MCP tools provided by phorvec.
Tool Reference
phorvec exposes its capabilities as MCP tools. Every tool listed here is available to any MCP-compatible client connected to a running phorvec server. Tools are invoked by name with a JSON arguments object.
Tools are grouped below by functional category.
Context
The context tools manage an agent's short-term working memory. Context items decay over time (configurable), can be organized into branches, and can be promoted to long-term memory.
| Tool | Description |
|---|
context_store | Write a content item to the active context branch. Accepts optional tag, importance (0.0–1.0), and session_id. |
context_retrieve | Search the active context branch using hybrid search. Returns ranked items with scores. |
context_clear | Delete all items from the active context branch, or from a named branch. |
context_compress | Merge semantically similar items in the active branch to reduce item count. |
context_snapshot_create | Export the current context branch (or full store) to a .vlbrain bundle file. |
context_snapshot_restore | Load a .vlbrain bundle back into the agent's context store. |
context_branch_create | Create a new named context branch. |
context_branch_switch | Set a named branch as the active branch for subsequent context operations. |
context_branch_merge | Merge a source branch into the current active branch with deduplication. |
context_branch_delete | Permanently delete a named context branch and all its items. |
context_timeline | Return a chronological event log of context writes and retrievals on the current branch. |
context_decay_preview | Show projected importance scores for current items at a specified future time, without modifying data. |
context_tagging | Add or remove tags on a context item by item ID. |
context_pin | Mark a context item as exempt from decay and automatic cleanup. |
context_optimize | Analyze the current branch and apply or suggest compaction operations (merge duplicates, archive low-importance items). |
context_link | Create an explicit cross-reference between two context items by ID. |
context_merge_sessions | Combine context items from two session IDs into the current active branch. |
Memory
The memory tools manage an agent's long-term memory store. Items here persist across sessions and are subject to consolidation and retention policies.
| Tool | Description |
|---|
memory_store | Write a memory item with optional tags, source, and importance weight. |
memory_recall | Retrieve relevant memories using hybrid search. Supports tag filters and time range filters. |
memory_consolidate | Run the four-phase consolidation process: deduplication, archival, association, and garbage collection. |
memory_gc | Remove purge-queue items, clean up orphaned graph nodes, and reclaim disk space. |
memory_export | Serialize the memory store (or a filtered subset) to a portable JSON file. |
memory_import | Load a previously exported JSON file into the agent's memory with deduplication. |
memory_promote | Elevate a context item into the long-term memory store with an optional importance adjustment. |
memory_block_create | Create a named memory block (a structured collection of related memory items). |
memory_block_get | Retrieve a memory block and its contents by name or ID. |
memory_block_update | Update the metadata or contents of an existing memory block. |
memory_block_delete | Permanently delete a memory block and all its items. |
memory_block_share | Export a memory block as a transferable bundle for import by another agent. |
Search
The search tools query stored content using phorvec's hybrid retrieval engine (vector + BM25 + RRF fusion) and the RAG pipeline.
| Tool | Description |
|---|
hybrid_search | Query the memory store and RAG index simultaneously using hybrid search. Accepts query, alpha (vector/keyword blend), top_k, and debug flag. |
rag_search | Query only the RAG index (indexed files). Supports cursor-based pagination. |
rag_index_file | Index a single file into the RAG pipeline. Language-aware chunking is applied automatically. |
rag_index_directory | Recursively index a directory, respecting .gitignore rules and skipping binary files. |
rag_refresh | Re-index files that have changed since the last indexing run (incremental update). |
Team
The team tools coordinate knowledge sharing and task routing across multiple agents. See Core Features — Team Collaboration for conceptual background.
| Tool | Description |
|---|
team_setup | Initialize a new team, assign an owner agent, and set the sharing mode (FULL, PROTECTED, or ISOLATED). |
team_manage | Update team metadata, sharing mode, or membership rules for an existing team. |
team_create | Create a sub-team or project-scoped team under an existing team. |
team_add_member | Add an agent to a team with a specified role. |
team_search | Query the team's shared knowledge pool using hybrid search. |
team_dispatch | Send a task or query to one or more team members and collect their responses. |
team_consolidate | Run the four-phase consolidation process over the team's shared knowledge pool. |
team_feed | Return a chronological stream of events from the team's shared pool. |
team_persona | Associate a role description and behavioral profile with an agent within the team context. |
team_workflow | Define or execute a named multi-step workflow that routes tasks between team members. |
Quantization
The quantization tools manage vector quantization for the HNSW index. See Core Features — Vector Quantization for background on quantization modes.
| Tool | Description |
|---|
quantization_status | Report the current quantization mode, index size, and size-reduction ratio. |
quantization_migrate | Migrate an existing index from one quantization mode to another (e.g., float32 to int8). |
Graph
The graph tools operate on the knowledge graph stored inside each agent's .avdb file. See Core Features — Knowledge Graphs for background.
| Tool | Description |
|---|
graph_entity_search | Find graph entities by name, type, or property value. |
graph_query | Traverse the graph with a pattern query. Returns matching nodes and the edges between them. |
graph_link | Create a typed relationship edge between two entities by ID. |
graph_entity_add_custom | Manually add a new entity node with arbitrary properties and an optional type label. |
graph_stats | Return aggregate counts of nodes, edges, and unique relationship types in the graph. |
Security
The security tools interact with the audit log and perform compliance-related scans. See Security & Compliance for full documentation.
| Tool | Description |
|---|
security_audit | Query the audit log with filters for time range, agent, operation name, and status. Returns matching JSONL records. |
failure_summary | Aggregate failed operations by type and agent over a configurable time window. Useful for identifying recurring error patterns. |
security_scan | Scan stored content (memory, context, or RAG index) for secrets and PII. Reports matches with severity and location. Does not modify data. |
Testing
The testing tools validate agent memory behavior against known-good baselines and measure retrieval quality. See Enterprise Features — Agent Testing for detailed documentation.
| Tool | Description |
|---|
agent_test | Run a YAML-defined test suite against the agent's memory. Returns a structured pass/fail report with per-case details. |
agent_baseline | Capture a baseline snapshot of the agent's current retrieval performance across a standard query set. |
agent_baselines | List all saved baselines for an agent with timestamps and summary metrics. |
agent_benchmark | Run a full performance benchmark measuring query latency, recall@k, and throughput. |
agent_regression_check | Compare current retrieval performance against a saved baseline. Reports precision, recall, F1 delta, and overall regression score. |
Enterprise
The enterprise tools cover compute governance, health monitoring, and cross-agent insight discovery. See Enterprise Features for full documentation.
| Tool | Description |
|---|
discover_insights | Run the Divergent Reasoning Engine (DRE) to generate cross-agent insights from divergent knowledge pairs. Returns insights with full provenance. |
repair_search | Detect and recover from geometric retrieval failures. Classifies the failure type and applies the appropriate repair strategy. |
set_budget | Assign an energy budget to a specific agent for a given time window. |
allocate_budgets | Distribute a total energy pool across multiple agents according to weights or reliability-based rules. |
get_spend | Return current energy spend, remaining budget, and denial count for an agent or the full fleet. |
agent_health | Return all six EMA health metrics for a single agent, with threshold status and intervention suggestions. |
fleet_health | Return a summary health report for all active agents, sortable by any metric. |
Utility
General-purpose tools for project setup, diagnostics, analytics, and miscellaneous operations.
| Tool | Description |
|---|
project_init | Initialize a phorvec project in the current directory: creates config.toml, sets up the data directory, and optionally indexes an initial file set. |
analytics | Return usage analytics for an agent: operation counts, retrieval frequency, memory growth over time. |
metrics | Return low-level system metrics: handle pool occupancy, index size, cache hit rate, query latency percentiles. |
query_explain | Show how a query will be executed: which indexes will be used, estimated result count, and the fusion plan. |
query_profile | Execute a query with detailed timing instrumentation and return a profiling report. |
cache_clear | Flush the in-memory query and embedding cache for an agent or globally. |
storage_verify | Verify the integrity of an agent's .avdb file. Reports any detected corruption without modifying data. |
storage_repair | Attempt to repair a corrupted .avdb file by rebuilding affected index segments. |
skill_store | Save a named skill (procedure, prompt template, or task strategy) to the agent's skill library. |
skill_search | Search the skill library by semantic query to find relevant skills even without knowing the exact name. |
conflict_check | Scan a scope (team pool, memory block, or full store) for multi-agent decision conflicts. Returns conflicts with severity classifications. |
conflict_dismiss | Mark a detected conflict as reviewed and suppressed. Recorded in the audit log. |
retention_status | Return the current retention zone and policy settings for a specific memory item or agent. Allows setting per-item anchor flags. |
retention_sweep | Process the purge queue, permanently deleting items that have passed their grace period. Respects anchor exemptions. |
REST API
When phorvec is running in server mode, the following HTTP endpoints are available alongside the MCP interface. All endpoints are prefixed with /api/v1 except the health check. Requests must include an Authorization: Bearer <api_key> header.
Agents
| Method | Path | Description |
|---|
POST | /api/v1/agents | Create a new agent |
GET | /api/v1/agents | List all agents |
GET | /api/v1/agents/{id} | Get a single agent by ID |
PATCH | /api/v1/agents/{id} | Update agent metadata |
DELETE | /api/v1/agents/{id} | Delete an agent and its data |
Vectors
| Method | Path | Description |
|---|
POST | /api/v1/agents/{id}/vectors | Insert a single vector |
POST | /api/v1/agents/{id}/vectors/batch | Batch insert vectors |
POST | /api/v1/agents/{id}/search | Similarity search |
DELETE | /api/v1/agents/{id}/vectors/{vector_id} | Delete a vector by ID |
Sync
| Method | Path | Description |
|---|
GET | /api/v1/agents/{id}/sync/compare | Compare local and remote state; returns a delta summary |
POST | /api/v1/agents/{id}/sync/push | Push local changes to a remote instance |
POST | /api/v1/agents/{id}/sync/pull | Pull remote changes into the local instance |
POST | /api/v1/agents/{id}/sync/resolve | Submit a conflict resolution decision |
Audit
| Method | Path | Description |
|---|
GET | /api/v1/audit | Query the audit log with filters (agent, time range, operation, status) |
GET | /api/v1/audit/export | Export audit records as CSV or JSON (Enterprise) |
GET | /api/v1/audit/verify | Verify the cryptographic hash chain integrity (Enterprise) |
API Keys
| Method | Path | Description |
|---|
POST | /api/v1/keys | Create a new API key |
GET | /api/v1/keys | List all API keys (secrets are not returned after creation) |
DELETE | /api/v1/keys/{key_id} | Revoke an API key immediately |
PATCH | /api/v1/keys/{key_id} | Update rate limit on an existing key |
Usage & Health
| Method | Path | Description |
|---|
GET | /api/v1/usage | Usage metrics for an agent or the full fleet |
GET | /health | Server health check; returns 200 OK when the server is ready |