Quick start

pip install ctxvault

Five minutes from nothing to an agent that remembers. Run these from your project's root.

1. Create a vault. It is a folder, registered in .ctxvault/config.json next to you, like git init.

ctxvault init notes

2. Give it something to know. Drop .md, .txt, .pdf or .docx files into .ctxvault/vaults/notes/ and index them.

ctxvault index notes

3. Ask it. Retrieval is by meaning, so the words do not have to match.

ctxvault query notes "what did we decide about pricing?"

4. Give it to your agent. The quickest way is MCP: add the server to your client's config (Claude Desktop, Cursor, any MCP client) and restart it. With uv installed nothing else is needed:

{
  "mcpServers": {
    "ctxvault": { "command": "uvx", "args": ["ctxvault", "mcp"] }
  }
}

Or uv tool install ctxvault once, and use { "command": "ctxvault-mcp" } instead.

The agent can now list your vaults, query them, and write what it learns back. From your own code instead, use the Python client in-process or the HTTP server.

5. See what it holds.

ctxvault ui

Next: a skill vault for procedures (ctxvault init procedures --type skill), an episodic vault for facts that change (ctxvault init facts --type episodic), and restricted vaults so each agent reaches only its own.

Install from source

With uv:

git clone https://github.com/Filippo-Venturini/ctxvault
cd ctxvault
uv sync            # creates .venv and installs all dependencies
uv run ctxvault    # run the CLI

With pip:

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 .