ctxvault

Local semantic memory infrastructure for AI agents

Isolated vaults. Agent-autonomous. Human-observable.

Installation • Quick Start • Examples • Documentation • API Reference

What is CtxVault?

CtxVault is a local semantic memory layer for LLM applications. It gives agents persistent, queryable knowledge through isolated vaults — independent memory slots that can be assigned per agent, shared across workflows, written autonomously, and monitored manually at any time.

Each vault is self-contained: its own documents, its own vector index, its own history. Run as many as you need — one per agent, one per project, or one shared knowledge base across multiple workflows.

_{Persistent memory across sessions — shown with Claude Desktop, works with any MCP-compatible client.}

100% Local — No API keys, no cloud services. Your data never leaves your machine.

Multi-Vault Architecture — Isolated memory slots for different contexts. One per agent, shared across a team, or split by domain — your call.

Three Integration Modes — CLI for manual use and monitoring. HTTP API for programmatic integration with LangChain, LangGraph, and custom pipelines. MCP server for agents that manage their own memory autonomously, with no code required.

Always Observable — Agents write and query autonomously via MCP or API, while you retain full visibility and control through the CLI.

_{One layer. Multiple agents, apps, and vaults.}

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
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 list my-vault

# 6. List all your vaults
ctxvault vaults

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/ctxvault"

# 1. Create a vault
requests.post(f"{API}/init", json={"vault_name": "agent-memory"})

# 2. Agent writes what it learns to memory
requests.post(f"{API}/write", json={
    "vault_name": "agent-memory",
    "filename": "session_monday.md",
    "content": "Discussed Q2 budget: need to cut cloud costs by 15%. "
               "Competitor pricing is 20% lower than ours."
})

# 3. Days later — query with completely different words
results = requests.post(f"{API}/query", json={
    "vault_name": "agent-memory",
    "query": "financial constraints from last week",  # ← never mentioned in the doc
    "top_k": 3
}).json()["results"]

# 4. Ground your LLM in retrieved memory
context = "\n".join(r["text"] for r in results)
answer = ChatOpenAI().invoke(f"Context:\n{context}\n\nQ: What are our cost targets?")
print(answer.content)
# → "You mentioned a 15% cloud cost reduction target, with competitor pricing 20% lower."

Any LLM works — swap ChatOpenAI for Ollama, Anthropic, or any provider. Ready to go further? See the examples for full RAG pipelines and multi-agent architectures — or browse the API Reference and the interactive docs at http://127.0.0.1:8000/docs.

MCP Integration (Claude Desktop, Cursor, and any MCP-compatible client)

Give any MCP-compatible AI client direct access to your vaults — no code required. The agent handles list_vaults, query, write, and list_docs autonomously.

Install:

uv tool install ctxvault

Add to your mcp.json (Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ctxvault": {
      "command": "ctxvault-mcp"
    }
  }
}

Restart your client. The agent can now query your existing vaults, write new context, and list available knowledge — all locally, all under your control.

Examples

Three production-ready scenarios — each with full code and setup instructions.

CtxVault vs Alternatives

When to use CtxVault:

• You need local-first semantic search
• Multiple isolated knowledge contexts
• Simple setup without external services
• Integration with LangChain/LangGraph workflows

When to use alternatives:

• Cloud-native architecture required
• Already invested in specific cloud ecosystem

Documentation

CLI Commands

All commands require a vault name. Default vault location: ~/.ctxvault/vaults/<name>/

init

Initialize a new vault.

ctxvault init <name> [--path <path>]

Arguments:

• <name> - Vault name (required)
• --path <path> - Custom vault location (optional, default: ~/.ctxvault/vaults/<name>)

Example:

ctxvault init my-vault
ctxvault init my-vault --path /data/vaults

index

Index documents in vault.

ctxvault index <vault> [--path <path>]

Arguments:

• <vault> - Vault name (required)
• --path <path> - Specific file or directory to index (optional, default: entire vault)

Example:

ctxvault index my-vault
ctxvault index my-vault --path docs/papers/

query

Perform semantic search.

ctxvault query <vault> <text>

Arguments:

• <vault> - Vault name (required)
• <text> - Search query (required)

Example:

ctxvault query my-vault "attention mechanisms"

list

List all indexed documents in vault.

ctxvault list <vault>

Arguments:

• <vault> - Vault name (required)

Example:

ctxvault list my-vault

delete

Remove document from vault.

ctxvault delete <vault> --path <path>

Arguments:

• <vault> - Vault name (required)
• --path <path> - File path to delete (required)

Example:

ctxvault delete my-vault --path paper.pdf

reindex

Re-index documents in vault.

ctxvault reindex <vault> [--path <path>]

Arguments:

• <vault> - Vault name (required)
• --path <path> - Specific file or directory to re-index (optional, default: entire vault)

Example:

ctxvault reindex my-vault
ctxvault reindex my-vault --path docs/

vaults

List all vaults and their paths.

ctxvault vaults

Example:

ctxvault vaults

Vault management:

• Default location: ~/.ctxvault/vaults/<vault-name>/
• Vault registry: ~/.ctxvault/config.json tracks all vault names and their paths
• Custom paths: Use --path flag during init to create vault at custom location
• All other commands use vault name (path lookup via config.json)

Multi-vault support:

# Work with specific vault
ctxvault research query "topic"

# Default vault location: ~/.ctxvault/vaults/
# Override with --path for custom locations

API Reference

Base URL: http://127.0.0.1:8000/ctxvault

Interactive documentation: Start the server and visit http://127.0.0.1:8000/docs

Roadmap

• CLI MVP
• FastAPI server
• Multi-vault support
• Agent write API
• MCP server support
• File watcher / auto-sync
• Hybrid search (semantic + keyword)
• Configurable embedding models

Contributing

Contributions welcome! Please check the issues for open tasks.

Development setup:

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 ".[dev]"
pytest

Citation

If you use CtxVault in your research or project, please cite:

@software{ctxvault2026,
  author = {Filippo Venturini},
  title = {CtxVault: Local Semantic Knowledge Vault for AI Agents},
  year = {2026},
  url = {https://github.com/Filippo-Venturini/ctxvault}
}

License

MIT License - see LICENSE for details.

Acknowledgments

Built with ChromaDB, LangChain and FastAPI.