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_create 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. Use context_snapshot_restore to load a bundle back into any agent's context.

.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.

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, structured collections of related memories — similar to a folder. They support full CRUD operations:

memory_block_share exports a block as a transferable bundle that another agent can import, enabling targeted knowledge transfer without exposing 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.

Server & Dashboard

phorvec ships as a self-hosted server that adds a web-based management UI, a full REST API, and optional differential sync — all running inside your own infrastructure.

Memory CMS Dashboard

The Memory CMS is a browser-based interface for viewing and editing agent memories directly, without writing code.

• Search and browse — full-text and semantic search across any agent's memory store from a single UI
• Edit in place — modify memory content directly; phorvec automatically re-embeds the updated text so the vector index stays current
• Delete — remove individual memories or bulk-delete by filter
• Hot-patch hallucinations — fix incorrect agent memories in seconds without a code deploy or model restart; changes take effect on the next retrieval

REST API

phorvec exposes a full HTTP REST API (built on FastAPI) for programmatic access from any language or service.

See Deployment Guide for the full endpoint list.

TypeScript SDK

The @phorvec/sdk package provides a typed, promise-based client for the phorvec REST API.

Capabilities:

• Agent management — create, list, and delete agents
• Vector operations — insert, batch insert, delete vectors
• Search — similarity search with the same hybrid retrieval available via MCP
• API key management — create and revoke keys programmatically

Install with npm install @phorvec/sdk and point it at your phorvec server URL.

Differential Sync

Differential sync is an optional feature that keeps two phorvec instances consistent without transferring full database snapshots.

• Delta-only transfer — only memories that have changed since the last sync are sent over the wire; unchanged vectors are never re-transmitted
• Vector clock conflict detection — each memory carries a vector clock; when two instances diverge, the sync engine identifies the conflicting writes precisely
• 3-way merge — concurrent edits to the same memory are merged automatically where possible; irreconcilable conflicts are surfaced for manual resolution
• Side-by-side diff UI — the dashboard presents conflicting versions side by side so operators can choose which version to keep or compose a merged result

Sync is always opt-in. Local deployments with no sync configuration remain entirely self-contained.

API Key Management

Access to the REST API is controlled through API keys.

• Create and revoke — generate new keys or revoke existing ones at any time; revocation takes effect immediately
• Per-key rate limits — set custom request-per-minute limits on individual keys to prevent any single client from monopolizing the server
• Argon2 storage — key secrets are hashed with Argon2 before storage; the plaintext value is shown only once at creation time
• Key format — live keys use the prefix pv_sk_live_ and test keys use pv_sk_test_, making environment mix-ups immediately visible in logs