title: Core Features description: A complete reference for every capability built into phorvec.

Core Features

phorvec ships with a broad set of capabilities designed to cover the full memory lifecycle of an AI agent — from first write through long-term consolidation, cross-agent collaboration, and code-aware retrieval. This page describes every feature in detail.

One File Per Agent

Every agent in phorvec is backed by a single .avdb file. That file contains the agent's HNSW vector index, BM25 full-text index, knowledge graph, context branches, memory store, skill library, and audit log — everything in one place.

Why this matters:

• Portability. Copy or move an .avdb file to transfer an agent's entire memory to another machine.
• Isolation. Agents cannot accidentally share or overwrite each other's state. Each file is opened through its own database handle.
• Simplicity. Backup, restore, and archive workflows reduce to ordinary file operations.
• No shared-state bugs. Because there is no central mutable store shared across agents, corruption in one agent's database cannot cascade to others.

Agents are identified by a string ID (e.g., coding-agent, research-agent). phorvec maps each ID to a file like {PHORVEC_DATA_DIR}/{agent_id}.avdb.

Hybrid Search

phorvec combines three retrieval signals and fuses them using Reciprocal Rank Fusion (RRF) to produce results that are more robust than any single method alone.

The Three Signals

Alpha Parameter

The alpha parameter controls the blend between vector and keyword scores before fusion:

• alpha = 1.0 — pure vector search
• alpha = 0.0 — pure BM25 keyword search
• alpha = 0.5 — equal weighting (default)

Tune alpha at query time to match the retrieval task. Exact identifier lookups benefit from lower alpha; conceptual similarity queries benefit from higher alpha.

Debug Output

Pass debug: true in a hybrid_search call to receive a per-result breakdown showing the raw vector score, raw BM25 score, and the fused RRF rank. This is useful for understanding why a particular result ranked where it did.

Knowledge Graphs

phorvec maintains a typed property graph alongside the vector index. Entities and relationships extracted from stored content form a navigable semantic network that complements pure vector retrieval.

Entity Extraction

When content is stored, phorvec can automatically identify named entities (people, organizations, concepts, code symbols) and add them as nodes in the graph. Custom entities can also be added directly via graph_entity_add_custom.

Graph Tools

Relationship Types

Relationships are typed strings. Common types include RELATED_TO, DEPENDS_ON, IMPLEMENTS, AUTHORED_BY, REFERENCES, and CONTRADICTS. You can define any relationship type that fits your domain.

Combining graph traversal with vector search enables queries like "find all concepts related to authentication that are semantically similar to this design note."

Context Management

The context system is a first-class session memory layer. It is distinct from the long-term memory store: context is designed for the working set of an ongoing task, with tools for branching, snapshotting, and automatic decay.

Store and Retrieve

context_store writes a piece of content to the active context branch with an optional tag and priority. context_retrieve fetches relevant context items using the same hybrid search engine.

Branching

Context branches let an agent maintain parallel working sets — for example, one branch per open task or one branch per hypothesis being explored.

Snapshots (.vlbrain)

context_snapshot_save exports the current context branch (or the entire context store) to a .vlbrain bundle — a portable binary file that can be shared, archived, or restored. context_snapshot_list enumerates saved snapshots; context_snapshot_restore loads a bundle back into any agent's context; context_snapshot_delete removes a saved snapshot.

.vlbrain files are self-contained: they include embeddings, metadata, and the branch structure, so they can be transferred to an air-gapped environment and restored without re-embedding. Skill libraries also serialize to the same .vlbrain format for cross-team distribution.

Timeline

context_timeline returns a chronological view of context writes and retrievals on the current branch. Useful for understanding what an agent has been working on and when.

Decay

Context items decay in importance over time according to a configurable half-life formula:

importance(t) = initial_importance × 0.5^(t / half_life)

Where t is the age of the item in hours and half_life is set in config.toml under [context]. Items that decay below a threshold are candidates for archival or deletion.

context_decay_preview shows the projected importance of current context items at a future time without modifying any data — useful for deciding whether to pin items before they decay.

Tagging and Pinning

context_tagging attaches semantic labels to context items for filtering and retrieval. Tags are free-form strings.

context_pin marks an item as exempt from decay and automatic cleanup. Pinned items remain in context indefinitely until explicitly unpinned or deleted.

Optimizer

context_optimize analyzes the current context branch and suggests (or applies) compaction: merging near-duplicate items, promoting frequently-retrieved items, and archiving low-importance content. Run it periodically to keep working context lean.

Linking and Merging Sessions

context_link creates an explicit cross-reference between two context items, useful for tracking relationships within the working set.

context_merge_sessions combines the context from two separate session IDs into the current branch, resolving duplicates via similarity thresholding.

Memory Management

The memory store is the long-term layer. Items written here survive session boundaries and are subject to consolidation and retention policies.

Store and Recall

memory_store writes a memory item with optional metadata (tags, source, importance weight). memory_recall retrieves relevant memories using hybrid search, optionally filtered by tag or time range.

Consolidation

Consolidation is a four-phase background process that keeps the memory store accurate and compact:

1. Deduplication — Identifies near-duplicate memories (cosine similarity above a configurable threshold) and merges them, preserving the higher-importance version.
2. Compression — Summarizes clusters of related low-importance memories into a single representative item.
3. Association — Builds or updates knowledge graph edges between memories that are semantically linked but not yet explicitly connected.
4. Archival — Moves memories below the importance threshold out of the active zone and into the archived zone (see Retention Policies).

Trigger consolidation explicitly with memory_consolidate, or configure a schedule in config.toml.

Garbage Collection

memory_gc removes memories that are in the purge queue (see Retention Policies), cleans up orphaned graph nodes, and reclaims disk space. It is safe to run at any time.

Export and Import

memory_export serializes the entire memory store (or a filtered subset) to a portable JSON file. memory_import loads a previously exported file, merging it into the current agent's memory with duplicate detection.

Memory Blocks

Memory blocks are named, durable items (with optional embeddings) that can be shared across agents or projects. Use blocks for content that shouldn't decay with conversation turns — user preferences, style guides, stable facts, environment descriptions.

memory_block_share grants another agent read access without copying — ideal for targeted knowledge transfer that doesn't expose the full memory store.

Promotion

memory_promote elevates a context item directly into the long-term memory store, optionally adjusting its importance score. Use this to "lock in" an insight from the current session before context decays.

Team Collaboration

Teams allow multiple agents to share knowledge in a controlled way. Each team has a defined sharing mode that governs how information flows between members.

Setup and Management

team_setup    → Initialize a new team and assign an owner agent
team_manage   → Update team metadata, membership rules, or sharing mode
team_create   → Create a sub-team or project-scoped team
team_add_member → Add an agent to a team with a specified role

Sharing Modes

Choose ISOLATED when agents must not have access to each other's working memories but need to publish discrete knowledge artifacts. Choose FULL for tightly coordinated agents working on the same task.

Workflows, Dispatch, and Feed

team_workflow defines a named multi-step process that routes tasks between team members in a specified order.

team_dispatch sends a task or query to one or more team members, collecting their responses into a unified result set.

team_feed returns a chronological stream of events from the team's shared pool — useful for an orchestrator agent monitoring team activity.

Search, Persona, and Consolidate

team_search queries the shared knowledge pool with the same hybrid search available to individual agents.

team_persona associates a role description and behavioral profile with an agent within the team context, allowing other agents to understand each member's specialty.

team_consolidate runs consolidation across the shared pool, deduplicating and compressing team-level memories using the same four-phase process as individual memory consolidation.

RAG (Retrieval-Augmented Generation)

phorvec includes a first-class RAG pipeline that indexes local files and makes them searchable through the same hybrid search engine used for memory and context.

Indexing

rag_index_file indexes a single file. rag_index_directory recursively indexes a directory, respecting .gitignore rules. Binary files are detected and skipped automatically.

rag_refresh re-indexes files that have changed since the last run, making incremental updates efficient.

Language-Aware Chunking

phorvec understands the structure of source code and configuration files. Instead of splitting naively at fixed byte boundaries, it chunks along language-appropriate boundaries:

Language-aware chunking means that function bodies stay together, so a retrieved chunk is always a coherent, usable unit of code.

Cursor Pagination

rag_search supports cursor-based pagination for result sets larger than the page size. Pass the cursor value from a previous response to retrieve the next page, enabling streaming retrieval of large result sets without loading everything into memory at once.

Vector Quantization

phorvec offers multiple vector quantization strategies to reduce the size of the HNSW index while preserving retrieval quality.

Quantization Modes

Auto-Quantization Thresholds

When using Auto mode, phorvec applies thresholds configured in config.toml under [quantization.auto_thresholds]:

[quantization.auto_thresholds]
int8_threshold = 10_000    # Switch to Int8 above this many vectors
binary_threshold = 100_000 # Switch to Binary above this many vectors

Quantization Tools

Conflict Detection

When multiple agents or multiple sessions contribute to the same knowledge pool, contradictions can emerge. phorvec scans for these automatically.

How It Works

conflict_check runs a multi-agent decision conflict scan over a specified scope (a team pool, a memory block, or the full memory store). It uses negation detection — identifying statements that logically oppose each other based on semantic similarity combined with negation pattern matching — and classifies conflicts by severity:

Dismissal

conflict_dismiss marks a detected conflict as reviewed and suppressed. Dismissed conflicts are recorded in the audit log but no longer surface in future scans.

Retention Policies

Retention policies define the lifecycle of memory items from active use through archival to deletion.

Zones

Items flow through three zones:

Active → Archived → PurgeQueue

• Active: In regular use; returned by default search queries.
• Archived: Below the importance threshold or past the retention window; excluded from default search but still accessible with explicit filters.
• PurgeQueue: Scheduled for deletion; not accessible. Items enter this zone after the archive grace period expires.

Sweep

retention_sweep processes the purge queue, permanently deleting items that have passed their grace period. Items with an anchor flag (see below) are exempt from sweeping regardless of age.

Grace Periods

The time an item spends in each zone before advancing is configurable per-agent or globally in config.toml. This allows fine-grained control: a coding agent might archive context after 7 days and purge after 30 days, while a long-term research agent keeps items in the archive for 180 days.

Anchor Exemption

Pinned items (see Context Management) are automatically anchored and will not be swept regardless of retention policy settings. Anchors can also be set directly via retention_status.

Skill Library

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

Store and Search

skill_store saves a skill with a name, description, and content. skill_search retrieves relevant skills by semantic query, making the library searchable even when you do not remember the exact skill name.

Export and Import Bundles

Skills can be packaged into bundles for sharing across agents or teams:

• Export a named set of skills to a bundle file
• Import a bundle into any agent's skill library, with deduplication

This is particularly useful for standardizing agent behavior across a team: define a shared set of skills once, bundle them, and distribute to every team member.

Transports & Authentication

phorvec ships as a single binary that an MCP client spawns over stdio by default. The same binary also serves SSE and HTTP with bearer-token authentication — pick the transport that fits your client.

API keys for SSE and HTTP transports are issued and revoked through apikey.rs machinery. Keys are stored as Argon2 hashes; the plaintext value is shown only once at creation time. Revocation takes effect immediately.

Path-Based Access Control

Independent of transport auth, phorvec enforces path-based access control on tools that touch the filesystem (RAG indexing, file imports). Allowed and denied path globs are configured in config.toml and evaluated before any read or write — useful when you want to expose phorvec to an agent but keep it off your .ssh/ or credential paths.