Local-First Agent Memory
Most agent memory stacks assemble themselves out of parts. A hosted vector database for embeddings. Postgres for metadata. A graph database if you want relationships. Redis in front of the whole thing. Each is a good product; together they're four services to provision, four sets of credentials, four failure modes, and a consistency problem nobody owns.
phorvec takes the opposite position: one agent, one file. Everything that agent knows lives in a single .avdb file on disk.
What's in the file
An .avdb is not just a vector index with metadata bolted on. It contains, together:
- The HNSW vector index for semantic search
- The BM25 full-text index for keyword and exact-phrase matching
- The knowledge graph of entities and typed relationships
- Context branches — the working-set layer, with its own branching and decay
- The memory store — the long-term layer
- The skill library of reusable procedures
- The append-only audit log
One file. Copy it and you've moved the agent's entire memory.
What co-location buys you
Hybrid search without a distributed join
If your vectors live in a hosted vector database and your keyword index lives in Elasticsearch, hybrid search means querying two systems over the network, reconciling two result sets, and handling the case where they disagree about what exists because one finished indexing before the other.
When both indexes are in the same file, a hybrid query is two local lookups and a fusion step. No network hop, no cross-service consistency window, no possibility that the keyword index has a document the vector index hasn't seen yet.
The same argument extends to the graph. "Find everything related to authentication that's semantically close to this design note" is a graph traversal feeding a vector search. Across services that's an orchestration problem. In one file it's one query.
Isolation that's structural, not configured
Each agent gets its own file, opened through its own database handle. One agent cannot read or corrupt another's state — not because permissions are configured correctly, but because there is no shared mutable store to get wrong.
In a shared-database design, agent isolation is a namespacing convention enforced by application code. It holds until someone writes a query that forgets the tenant filter. Here the isolation is a property of the storage layout: a bug in one agent's memory handling cannot cascade into another's, because it has no path to that data.
Sharing, when you want it, becomes explicit rather than ambient. memory_block_share grants another agent read access to a specific named block without copying it and without exposing the rest of the store — targeted knowledge transfer instead of a blanket grant.
Backup and portability as file operations
Snapshotting an agent's memory is cp. Archiving it is tar. Versioning it is whatever you already use for files. Moving an agent from your laptop to a server is scp.
Compare the hosted equivalent: an export API, a format that may not round-trip, and an import that hopefully preserves your embeddings rather than recomputing them.
Portability also has a lock-in dimension. .avdb is a documented open format — the wire format, the inline embedding encodings and the integrity rules are all specified. Your memory isn't hostage to phorvec continuing to exist. There's also memory_export for a portable JSON dump, and .vlbrain context snapshots that bundle embeddings, metadata and branch structure so they can be restored in an air-gapped environment without re-embedding anything.
Recall that doesn't depend on the network
A hosted memory service turns every retrieval into a network round-trip. That's latency on the critical path of every single agent turn, and it means your agent's recall has your vendor's uptime as a hard dependency.
Local retrieval is an index lookup. It works on a plane, behind a corporate firewall, in an air-gapped environment, and during your vendor's incident.
Data that doesn't leave
This is usually the deciding factor, and it's worth being precise about what's at stake.
Agent memory is not incidental data. A coding agent's memory accumulates your architecture, your internal conventions, the reasoning behind decisions that never made it into a document, and — if you're not careful — fragments of credentials and customer data that appeared in a session. That's among the most sensitive material your organisation produces, and it's exactly what a hosted memory layer would ship off-machine by design.
phorvec runs entirely on your machine. No cloud account, no data leaving your environment. The binary bundles its ONNX embedding model, so even embedding generation is local — there's no "we only send it to the embedding API" caveat.
For defence in depth, path-based access control restricts which parts of the filesystem the file-touching tools can reach, evaluated before any read or write. Exposing phorvec to an agent doesn't mean exposing ~/.ssh.
The honest trade-offs
Local-first is a real architecture with real costs, not a free win.
You own durability. No managed backups. If the disk dies and you had no copy, the memory is gone. The mitigation is that backup is cp — but you have to actually run it.
Cross-machine sharing is deliberate work. Two developers' agents don't share memory by sitting in the same database. That's the isolation guarantee working as designed, but when you do want shared team memory, it's a thing you set up rather than a thing you get. phorvec's answer is to run one instance the team points at — the same binary served over HTTP or SSE with bearer-token auth, covered in Team Hosting.
Scale is per-agent, not global. One file per agent scales well across many agents and is bounded by disk for any single one. If you need a billion vectors in one index queried by a thousand concurrent clients, a distributed vector database is the right tool and this isn't it.
No managed scaling knobs. What you get instead is quantization: Int8 for roughly 4× smaller vectors, Binary for far more aggressive compression, or Auto to switch modes as a collection crosses configured size thresholds. That covers a lot of ground, but it's a different kind of lever than adding replicas.
Who this fits
Local-first agent memory is the right default when your agents accumulate knowledge about proprietary code or internal systems, when you need memory to work offline or air-gapped, when per-agent isolation is a requirement rather than a nice-to-have, or when you'd rather not add four services to run one feature.
It's the wrong choice if you need a single shared index at internet scale, or if you specifically want someone else to own storage durability.
pip install phorvec
The Getting Started guide covers the architecture in more detail, and Security & Compliance covers audit trails, secret detection and air-gapped operation.