Ctxvault
Local memory infrastructure for AI agents. Store knowledge and skills in isolated vaults you compose, control and query.
Install / Use
/learn @Filippo-Venturini/CtxvaultQuality Score
Category
Development & EngineeringSupported Platforms
README
Installation • Quick Start • Examples • Documentation • API Reference
</div>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. 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.
<div align="center"> <img src="https://raw.githubusercontent.com/Filippo-Venturini/ctxvault/main/assets/ctxvault_schema.svg" alt="CtxVault architecture schema" width="1200" > </div>Core Principles
Typed memory: semantic and procedural
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 — it is the agent's behavioral repertoire. The agent queries one to know what, and reads the other to know how.
Both vault types share the same infrastructure primitives: public or restricted, local or global, composable in any topology. The difference is what they store and how the agent uses it.
<div align="center"> <img src="https://raw.githubusercontent.com/Filippo-Venturini/ctxvault/main/assets/typed_memory_schema.svg" alt="Typed memory: an agent queries a semantic vault for knowledge and reads a skill vault for behavioral instructions, combining both into output" width="1200" > </div>Structural isolation and access control
Isolation enforced through prompt logic or metadata schemas is fragile — it grows harder to reason about as systems scale, and fails silently when it breaks.
In CtxVault, each vault is an independent index. Agents have no shared retrieval path unless one is explicitly defined. Vaults can be declared restricted, with access granted to specific agents directly through the CLI. The boundary is part of the architecture, not a rule written in a config file that someone might later get wrong.
Found 3 vaults
> agent-a-vault [RESTRICTED]
path: ~/.ctxvault/vaults/agent-a-vault
agents: agent-a
> shared-vault [PUBLIC]
path: ~/.ctxvault/vaults/shared-vault
> agent-c-vault [RESTRICTED]
path: ~/.ctxvault/vaults/agent-c-vault
agents: agent-c
Persistent memory across sessions
Agents lose all context when a session ends. CtxVault gives them a knowledge base that persists across conversations, queryable by meaning rather than exact match. Context written in one session is retrievable days later using semantically related language.
<div align="center"> <img src="https://raw.githubusercontent.com/Filippo-Venturini/ctxvault/main/assets/ctxvault-demo.gif" alt="Agent saves context in session one — new chat, new session, memory intact" width="1200" > <p><sub>Persistent memory across sessions — shown with Claude Desktop, works with any MCP-compatible client.</sub></p> </div>Observable and human-controllable
When agents write to memory autonomously, visibility into what they write is not a debugging feature — it is the foundation of a trustworthy system.
Every vault is a plain directory on your machine. You can read it, edit it, and query it directly through the CLI at any point, independent of what any agent is doing. You also contribute to the same memory layer directly: drop documents into a vault, index with one command, and the agent queries that knowledge alongside what it has written on its own.
# Inspect what your agent has written in the vault
ctxvault list my-vault
# Query its knowledge base directly
ctxvault query my-vault "what decisions were made last week?"
# Add your own documents and index them
ctxvault index my-vault
Local-first
No cloud, no telemetry, no external services. Vaults are plain directories on your machine, the storage layer is entirely local. What you connect to that knowledge base is your choice.
Integration Modes
CtxVault exposes the same vault layer through three interfaces. Use whichever fits your context, or combine them freely.
CLI — Human-facing. Monitor vaults, inspect agent-written content, add your own documents, query knowledge bases directly.
HTTP API — Programmatic integration. Connect LangChain, LangGraph, or any custom pipeline to vaults via REST. Full CRUD, semantic search, and agent write support.
MCP server — For autonomous agents. Give any MCP-compatible client direct vault access with no integration code required. The agent handles list_vaults, query, write, and list_docs on its own.
CtxVault vs Alternatives
| | CtxVault | ChromaDB + custom | LangChain Memory | Mem0 | |--|----------|-------------------|------------------|------| | Vault isolation | ✓ | ✗ — you build it | ✗ | ✗ | | Access control | ✓ | ✗ — you build it | ✗ | ✗ | | Typed memory (semantic + procedural) | ✓ | ✗ | ✗ | ✗ | | Agent-written memory | ✓ | ✗ — you build it | Partial | Partial | | Human CLI observability | ✓ | ✗ | ✗ | ✗ | | Local-first | ✓ | ✓ | ✓ | ✗ (cloud) | | MCP server | ✓ | ✗ — you build it | ✗ | ✗ |
Examples
Three scenarios — each with full code and setup instructions.
| | Example | What it shows | |--|---------|---------------| | 🟢 | Personal Research Assistant | Single vault, single agent. Semantic RAG over PDF, MD, TXT, DOCX with source attribution. ~100 lines. | | 🔴 | Multi-Agent Isolation | Two agents, two vaults. Each agent has no retrieval path to the other's vault — isolation enforced at the infrastructure layer, not through metadata filtering. ~200 lines.| | 🔵 | Persistent Memory Agent | An agent that recalls context across sessions using semantic queries. "financial constraints" retrieves "cut cloud costs by 15%" written three days prior. | | 🟡 | Composed Topology | Three agents, five vaults — private, shared between a subset, and public. A tiered support system where access boundaries reflect organizational boundaries. | | 🟣 | Procedural Memory Agent | One agent, two vault types — semantic and skill — integrated via MCP. Retrieves knowledge for what to say and skills for how to say it. | |
Installation
Requirements: Python 3.10+
From PyPI
pip install ctxvault
From source
git clone https://github.com/Filippo-Venturini/ctxvault
cd ctxvault
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
Quick Start
Both CLI and API follow the same workflow: create a vault → add documents → index → query. Choose CLI for manual use, API for programmatic integration.
CLI Usage
# 1. Initialize a vault (run from your project root)
ctxvault init my-vault
# 2. Add your documents to the vault folder
# Default location: .ctxvault/vaults/my-vault/
# Drop your .txt, .md, .pdf or .docx files there
# 3. Index documents
ctxvault index my-vault
# 4. Query semantically
ctxvault query my-vault "transformer architecture"
# 5. List indexed documents
ctxvault docs my-vault
# 6. List all your vaults
ctxvault vaults
# For a machine-wide vault available everywhere
ctxvault init my-vault --global
Agent Integration
Give your agent persistent semantic memory in minutes. Start the server:
uvicorn ctxvault.api.app:app
Then write, store, and recall context across sessions:
import requests
from langchain_openai import ChatOpenAI
API = "http://127.0.0.1:8000/ctx
