Ctxvault

Local memory infrastructure for AI agents Isolated vaults. Typed memory. Agent-autonomous. Human-observable.

Installation • Quick Start • Examples • Documentation • API Reference

---

What is CtxVault?

Most agent frameworks treat memory as an afterthought: a shared vector store where isolation depends on configuration staying correct and everything, facts and procedures alike, gets embedded into the same undifferentiated index. The agent cannot tell what it knows from how it should act.

CtxVault is built around a different primitive. Memory is organized into vaults: self-contained, directory-backed units with explicit types. A semantic vault holds documents and a vector index, queryable by meaning: the agent's semantic memory. A skill vault holds skills that shape how the agent behaves: its procedural memory. An episodic vault holds statements with a validity window, so the agent can tell what still holds from what used to: its episodic memory. Isolation is structural, the topology is defined explicitly (one vault per agent, a shared knowledge base, private skills for a specific role, or any combination), with access control that determines exactly which agents can reach which vault.

The result is a memory layer that behaves like real infrastructure: typed, composable, observable, persistent and entirely local.

---

Core Principles

Typed memory: semantic, procedural and episodic

Classical cognitive architectures, from ACT-R (Anderson et al., 2004) to CoALA (Sumers et al., 2024), separate an agent's long-term memory into distinct modules: semantic memory for world knowledge, and procedural memory for skills and behavioral rules. Most agent frameworks ignore this distinction and store everything in a single vector index.

In CtxVault, the separation is structural. A semantic vault holds documents, indexes them into a vector store, and supports retrieval by meaning: it is the agent's knowledge base. A skill vault holds natural-language procedures with explicit names and descriptions, the agent's behavioral repertoire. An episodic vault holds individual statements that have a lifetime: what happened, when, and whether it still holds. The agent queries the first to know what, reads the second to know how, and consults the third to know when.

Episodic memory is the one an agent needs to stay coherent across sessions, and the one a vector index handles worst: similarity cannot tell a fact from the fact that replaced it. So episodes are stored bi-temporally: each one records the window in which it is true in the world (valid_from / valid_to) and the window in which the vault believed it (recorded_at / invalidated_at). Correcting a statement closes the old one exactly where its successor opens, in a single transaction, and links the two. Nothing is deleted: valid_at reconstructs what was true at any past moment, known_at reconstructs what the agent had learned by then, and the supersession chain explains how a belief got where it is.