Hermes Zvec — In-Process Vector Database for AI Agents

A native Hermes Agent tool wrapping alibaba/zvec — a lightweight, embedded C++ vector database with Python bindings. Enables zero-configuration vector search, RAG (Retrieval-Augmented Generation), semantic search, full-text search (FTS), and hybrid search directly within the Hermes AI agent framework.

No external server, no Docker, no API key. Install in one command and start indexing embeddings immediately.

Quick Install

git clone https://github.com/lesterppo/hermes-zvec.git /tmp/hermes-zvec
cd /tmp/hermes-zvec && bash install.sh

Or pipe-to-bash:

curl -fsSL https://raw.githubusercontent.com/lesterppo/hermes-zvec/main/install.sh | bash

Why Zvec for Hermes Agent?

Feature	Benefit
In-process	No server process — the vector DB runs embedded in Python. Zero DevOps.
C++ performance	Searches millions of vectors in milliseconds via HNSW indexing.
Hybrid search	Combine vector similarity + full-text search + metadata filtering in one query.
Durable storage	Write-ahead logging (WAL) guarantees persistence across crashes.
Token-efficient	Compact JSON output keys (ok, r, s, f) minimize LLM token consumption.
Auto-gated	Tool only appears in the Hermes schema when zvec is installed — zero overhead otherwise.

Use Cases

• RAG pipeline — Index local documents (markdown, PDF, wiki) as vector embeddings. Retrieve relevant context for agent sessions.
• Semantic memory — Replace ChromaDB as the vector backend for Hermes session memory or second-brain knowledge base.
• Codebase search — Index function signatures and docstrings for semantic code retrieval across repositories.
• Research literature — Store paper embeddings with metadata (title, abstract, PMID) for fast biomedical literature search.
• Conversation history — Index past agent conversations for similarity-based recall.

Tool Actions (15 total)

Action	Description
create	Create a new collection with schema (fields + vectors)
insert	Insert documents with dense vector embeddings and metadata
query	ANN vector similarity search with optional FTS + filter
search	Pure full-text search on indexed string fields
fetch	Retrieve documents by ID
update	Update document fields or vectors
upsert	Insert or update by ID (idempotent)
delete	Delete documents by ID
delete_by_filter	Delete documents matching SQL-like filter expression
stats	Collection statistics (document count)
index	Create HNSW, Flat, or FTS index on a field
destroy	Permanently delete the collection directory
open	Open existing collection (read-only or read-write)
version	Show installed zvec version
list_collections	List zvec collections under a directory

Schema Example

{
  "name": "my_rag_collection",
  "fields": [
    {"name": "title",    "type": "STRING"},
    {"name": "body",     "type": "STRING"},
    {"name": "category", "type": "STRING"}
  ],
  "vectors": [
    {"name": "embedding", "type": "VECTOR_FP32", "dim": 768}
  ]
}

Supported data types: STRING, INT32, INT64, FLOAT, DOUBLE, BOOL, VECTOR_FP32, VECTOR_FP16, VECTOR_FP64, VECTOR_INT8, SPARSE_VECTOR_FP32, and their ARRAY_* variants.

Usage Flow

# 1. Create collection with schema
zvec(action="create", path="/tmp/my_rag", schema={...})

# 2. Create HNSW index for ANN search + FTS index for text search
zvec(action="index", path="/tmp/my_rag", field_name="embedding",
     index_spec={"type": "hnsw", "metric": "cosine"})
zvec(action="index", path="/tmp/my_rag", field_name="body",
     index_spec={"type": "fts"})

# 3. Insert documents with embeddings
zvec(action="insert", path="/tmp/my_rag", docs=[
    {"id": "1", "vectors": {"embedding": [0.1, 0.2, ...]},
     "fields": {"title": "Attention Is All You Need", "body": "...", "category": "NLP"}}
])

# 4. ANN vector search
zvec(action="query", path="/tmp/my_rag",
     query={"field": "embedding", "vector": [0.15, 0.25, ...]}, topk=10)

# 5. Full-text search
zvec(action="search", path="/tmp/my_rag",
     query={"field": "body", "fts": "attention mechanism"}, topk=5)

# 6. Hybrid: vector + FTS + metadata filter
zvec(action="query", path="/tmp/my_rag",
     query={"field": "embedding", "vector": [...],
            "fts": "transformer", "filter": "category = \"NLP\""}, topk=10)

Architecture

Hermes Agent LLM
    ↓ tool call
zvec_tool.py (545 lines, 15 actions)
    ↓ Python bindings
zvec C++ core (HNSW, FTS, WAL, hybrid search)
    ↓ filesystem
Collection on disk (~/.hermes/zvec_collections/)

• Gating: check_fn on import zvec — schema only included when pip install zvec succeeds
• Token budget: Schema ~1,100 chars (~275 tokens). Output uses compact 1-2 char keys.
• Durability: WAL persists every insert/update/delete. coll.flush() called automatically after writes.
• Concurrency: Multiple processes can read simultaneously; writes are single-process exclusive.

For AI Agents Reading This Repo

See AGENTS.md for full integration instructions. Other Hermes agents, Claude Code instances, or Codex agents can:

1. Clone this repo
2. Run install.sh
3. The zvec tool appears in their schema automatically

Verification

python3 tests/test_zvec.py
# Expected: 20/20 passed — ALL PASSED

Dependencies

• alibaba/zvec >= 0.6.0 (pip install zvec)
• Hermes Agent (any recent version)
• Python 3.10+

License

Apache-2.0 — matching upstream alibaba/zvec.

Author

lesterppo — Hermes Agent contributor and tool developer.