ZeRi 1.0.5

ZeRi

ZeRi is a lightweight, disk-backed hybrid search and long-term memory engine built in C# (.NET 9). It combines lexical keyword matching (BM25) with dense vector embeddings to give fast, accurate search over local documents and notes without requiring external databases, Docker containers, or heavy background services.

Overview

When building search or retrieval for personal notes, local documents, or AI agents, pure keyword search and pure vector search both have blind spots:

• Keyword search (BM25) is fast and reliable for exact terms, names, numbers, error codes, and identifiers, but cannot understand synonyms or conceptual similarity.
• Dense vector search understands semantic meaning, but often misses exact keywords, numbers, or specific identifiers.

ZeRi combines both approaches using Reciprocal Rank Fusion (RRF). It stores both the inverted index and vector data on disk using memory-mapped files, allowing it to search tens of thousands of documents with a small memory footprint (typically under 200 MB RAM).

Key Features

• Hybrid Search: Evaluates queries through both BM25 and dense vector similarity, combining results with Reciprocal Rank Fusion (RRF).
• Memory-Mapped Storage: Indexes are read directly from disk via the operating system page cache, keeping memory usage minimal.
• Hardware SIMD Acceleration: Vector dot products leverage .NET 9 TensorPrimitives (AVX-512, AVX2, or ARM NEON depending on the processor).
• Vector Quantization: Supports Float32, Float16, and Int8 vector storage to reduce disk usage and memory bandwidth.
• Live File Watching: A built-in watcher monitors directories for new, modified, or deleted files and updates the index automatically.
• Soft Deletions and Compaction: Deletions are tracked instantly with tombstones, and an optional compaction step cleans up disk space when needed.
• Embedded or Standalone: Can be referenced directly as a C# library, used via the command-line tool, or run as a local REST API daemon.

Installation

From NuGet

dotnet add package ZeRi

From Source

Clone the repository and build using the .NET 9 SDK:

dotnet build -c Release

Getting Started

Using the C# Library

Here is a complete example showing how to create an index, ingest a folder of documents, and perform a search:

using ZeRi;
using ZeRi.Models;
using ZeRi.Storage;

// 1. Create or open an on-disk index
using var index = Directory.Exists("./my_index")
    ? ZeRiIndex.Open("./my_index")
    : ZeRiIndex.Create("./my_index", precision: VectorPrecision.Float16);

// 2. Ingest documents from folders or individual files
var report = index.Ingest(new[] { "./notes", "./documents" });
Console.WriteLine($"Indexed {report.NewChunksIndexed} chunks in {report.Elapsed.TotalMilliseconds:F0} ms");

// 3. Perform a hybrid search
var results = index.Search("database connection pooling port 5432", new SearchOptions
{
    TopK = 5,
    Mode = SearchMode.Hybrid
});

foreach (var r in results)
{
    Console.WriteLine($"[{r.Score:F3}] {r.SourcePath}");
    Console.WriteLine($"Snippet: {r.HighlightedSnippet}\n");
}

// 4. Extract token-budgeted facts (useful for LLM prompts)
var context = index.GetAiContext("backup retention policy", limit: 3);
foreach (var fact in context.Results)
{
    Console.WriteLine($"- {fact.Fact}");
}

// 5. Delete an outdated file
index.DeleteSource("./notes/old_notes.txt");

// 6. Compact the index to reclaim disk space from deleted documents
index.Compact();

Command Line Interface

ZeRi includes a CLI tool (zeri) for indexing and querying directly from the terminal:

# Index a directory with float16 vectors
zeri index ./my_index ./notes --precision float16

# Run a search query
zeri search ./my_index "distributed consensus" -k 5 -m hybrid

# Extract context facts for an LLM prompt
zeri context ./my_index "server configuration"

# Watch a directory and re-index changes in real time
zeri watch ./my_index ./notes

# Remove a document from the index
zeri delete ./my_index ./notes/old_file.txt

# Reclaim disk space from deleted documents
zeri compact ./my_index

# Inspect index statistics
zeri info ./my_index

# Run a SIMD vector scan benchmark on your hardware
zeri bench --count 25000

# Launch native Model Context Protocol (MCP) server for AI agents
zeri mcp ./my_index

Model Context Protocol (MCP) for AI Agents & Companions

ZeRi functions as a lightweight, sovereign episodic memory engine for AI agents (Antigravity, Cursor, Claude Desktop, VS Code, Codex, ZCode). It communicates over standard JSON-RPC 2.0 (stdio) without requiring external services or background databases.

Option A: Running with the Global CLI Tool (Zero Config)

Install the global CLI tool:

dotnet tool install -g ZeRi.Tool

Add ZeRi to your agent's MCP configuration (mcpServers):

{
  "mcpServers": {
    "zeri-memory": {
      "command": "zeri",
      "args": ["mcp"]
    }
  }
}

When no path argument is passed, ZeRi automatically stores episodic memory in your operating system's local application data directory (%LOCALAPPDATA%/ZeRi/memory on Windows, ~/.local/share/ZeRi/memory on Linux, ~/Library/Application Support/ZeRi/memory on macOS).

To use a custom directory on any drive (such as C: or D:):

{
  "mcpServers": {
    "zeri-memory": {
      "command": "zeri",
      "args": ["mcp", "C:\\Users\\username\\Documents\\agent_memory"]
    }
  }
}

Option B: Embedded in C# Projects

Add the NuGet package to any .NET project on any platform:

dotnet add package ZeRi

Instantiate the memory index and run the MCP server with one line of initialization:

using ZeRi;
using ZeRi.Mcp;

// Automatically opens or creates the sovereign memory index
using var index = ZeRiIndex.OpenOrCreate();

// Run the MCP server over stdio
var server = new McpServer(index);
await server.RunAsync();

ZeRi automatically exposes three MCP tools to your agent:

• zeri_recall: Recalls relevant facts, decisions, and past dialogue turns using dual-arm hybrid search (BM25 + Dense Vectors) with prompt token budgeting.
• zeri_record: Dynamically logs new conversation turns, user preferences, and agent actions into memory.
• zeri_search: Searches indexed documents, codebases, or local notes.

Python Client

A lightweight Python client is provided for integration with Python-based AI agents, scripts, and local models:

from zeri import ZeRi

# Connect to a local ZeRi server
client = ZeRi(server_url="http://localhost:5000", index_dir="my_index")

# Retrieve formatted context facts ready for a prompt
facts = client.recall_as_prompt("What is the database backup schedule?", limit=3)
print(facts)

# Or perform a structured query
results = client.recall("connection pool size", limit=5)
for item in results:
    print(f"[{item['source']} - {item['confidence']:.3f}] {item['fact']}")

Local Server and Web Interface

To run the local HTTP daemon and browse search results in a browser:

$env:ZERI_INDEX_DIR = "D:\my_index"
dotnet run --project src/ZeRi.Server -c Release --urls "http://localhost:5000"

Once running, open http://localhost:5000 to view the search dashboard.

Storage Architecture

An on-disk index consists of five core files:

• vectors.bin: Contiguous array of floating-point vectors (Float32, Float16, or Int8). Mapped into virtual memory for SIMD dot-product scanning.
• postings.bin: Variable-byte compressed document ID lists for the inverted index.
• terms.idx: Sorted 64-bit term hashes and posting offsets, enabling binary search lookups in O(log M) time.
• docs.bin: Document text, source paths, and metadata.
• tombstones.bin: Bitset of deleted document IDs, checked in O(1) time during search scans.
• manifest.json: Stores index configuration, vector dimension, precision mode, and total chunk count.

Performance and Benchmarks

Measured on a dataset of 10,000 encyclopedic documents (10,960 chunks) on standard desktop hardware:

• Indexing Throughput: ~195 chunks/second (CPU-based batched inference)
• Working Memory (RAM): ~189 MB during indexing
• Total Disk Size: ~30 MB (including vectors, inverted index, terms, and document text)
• Query Latency (P50): 37.5 ms
• Query Latency (P90): 114.7 ms
• Query Latency (P99): 318.7 ms

All 40 unit and adversarial tests verify chunk streaming, BM25 postings seek, AVX2 SIMD operations, quantization precision, tombstone soft-deletions, index compaction, live watcher behavior, dynamic episodic memory recording, 50-thread concurrency, multilingual scripts, injection resistance, and MCP JSON-RPC protocol compliance.

Scaling Approach

• Up to 50,000 chunks: Sequential SIMD scans over memory-mapped vectors take under 5 milliseconds on modern CPUs.
• Up to 1,000,000 chunks: Using Int8 quantization, 1 million 384-dimensional vectors occupy 384 MB on disk. Multi-threaded AVX2 instructions scan this in 20 to 30 ms.
• 100,000,000 chunks: At very large scale, inverted file clustering (IVF) routes queries to the closest centroid clusters, scanning only candidate subsets in under 10 ms.

Author

Aditya Talpade (Slay3rr20)

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.