title: Tool Reference description: Complete reference for the 100+ 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 with `role`, optional `metadata` (tags, file references), and `project`. Auto-deduplicates within a 5-minute window.
`context_retrieve`	Hybrid search (vector + BM25 + RRF) over a project's context. Returns ranked items with `metadata._item_id` matching the store ID.
`context_clear`	Delete the project's context agent and all its items.
`context_compress`	Merge semantically similar items to reduce item count.
`context_snapshot_save`	Export the current context branch (or full store) to a `.vlbrain` bundle file.
`context_snapshot_list`	List saved snapshots for the project.
`context_snapshot_restore`	Load a `.vlbrain` bundle back into the agent's context store.
`context_snapshot_delete`	Permanently delete a saved snapshot.
`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 new named memory block — durable, cross-agent content (preferences, style guides, stable facts).
`memory_block_read`	Read a block's content by name.
`memory_block_write`	Update an existing block's content. Auto re-embeds for vector search.
`memory_block_list`	List blocks in a project or agent.
`memory_block_delete`	Permanently delete a memory block.
`memory_block_share`	Grant another agent read access to a block — no copy, just access.

Search & RAG

Hybrid search (vector + BM25 + RRF fusion) is the default retrieval mode for context_retrieve and rag_search. Each takes an optional mode (hybrid, vector, keyword) and alpha (vector/keyword blend, 0.0–1.0).

Tool	Description
`rag_index_file`	Index a single file. Language-aware chunking respects functions, classes, headings. Stored in the project's `code_*` agent.
`rag_index_directory`	Recursively index a directory, respecting `.gitignore` rules and skipping binaries.
`rag_refresh`	Re-index files whose modification time has changed since the last run.
`rag_search`	Search indexed code chunks by query. Returns chunks with `file_path`, `score`, and surrounding context.

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.

Skill Library

The skill library stores reusable procedures, prompt templates, and task strategies as named, searchable artifacts.

Tool	Tier	Description
`skill_search`	Community	Vector-search the local and synced library by query — finds skills even when you don't know the exact name.
`skill_get`	Community	Read a skill by name.
`skill_list`	Community	Enumerate skills in a scope.
`skill_store`	Community	Save a new skill to the local library.
`skill_publish`	MCP Pro	Publish a tuned skill into the shared library so other agents can discover it.
`skill_deprecate`	MCP Pro	Mark a published skill as deprecated; consumers see a warning but it remains callable.
`skill_library_sync`	MCP Pro	Push/pull local changes against the shared library.
`skill_library_status`	MCP Pro	Report sync state, pending changes, and last sync timestamp.
`skill_ingest`	MCP Pro	Bulk-import skills from a `.vlbrain` bundle.
`skill_export_bundle` / `skill_import_bundle`	Community	Move skill collections between machines as `.vlbrain` files.

Conflict Detection

Tool	Tier	Description
`conflict_check`	MCP Max	Scan a team or project for contradictory decisions across agents. Uses regex-based negation detection plus semantic similarity — no LLM call. Returns conflicts with severity (`low`, `medium`, `critical`).
`conflict_dismiss`	MCP Max	Mark a detected conflict as reviewed; recorded in the audit log and suppressed from future scans.