ctxvault

CtxVault MCP server exposes a local semantic memory vault layer that can be controlled by any MCP-compatible client. The server itself runs a Python-based HTTP API via an ASGI app powered by Uvicorn, which provides CRUD-like access to vaults, semantic querying, and writing of documents. Through the MCP interface you can list available vaults, query a vault semantically, write new content into a vault, and list documents within a vault. This enables autonomous agents to read and write memory in a structured, observable way without embedding memory logic into each agent.

To use it, start the server using your preferred MCP client configuration (as shown in the mcp_config). Once the server is running, your MCP client can send messages like list_vaults, query, write, and list_docs to ctxvault. For example, a client could request a list of vaults, then choose a vault to query for recent decisions, or write new documents into a vault for later retrieval by agents. The exact message shapes depend on your MCP protocol, but you should expect operations that mirror the CLI capabilities described in the project (inspect vaults, perform semantic queries, and index documents programmatically).

Prerequisites:

• Python 3.10+ (or a compatible environment with uvicorn installed)
• Internet access to install dependencies

1. Create and activate a virtual environment (recommended):

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.
\.venv\Scripts\activate

2. Install the ctxvault package and its HTTP API server dependencies:

pip install ctxvault uvicorn

3. Run the MCP server (example using uvicorn as shown in the README):

python -m uvicorn ctxvault.api.app:app

4. If you plan to customize the vault storage path, set the environment variable before starting:

export CTXVAULT_VAULTS_DIR="/path/to/vaults"
# Windows (PowerShell)
$env:CTXVAULT_VAULTS_DIR = "C:\\path\\to\\vaults"

5. Connect an MCP client and begin sending commands like list_vaults, query, write, and list_docs to the ctxvault MCP server.

Tips and caveats:

• By default CtxVault stores vaults under the user’s home directory (e.g., ~/.ctxvault/vaults). You can override this with the CTXVAULT_VAULTS_DIR environment variable.
• Ensure your MCP client uses the same protocol and message shapes as the server expects (list_vaults, query, write, list_docs are the core actions referenced in the docs).
• If you encounter issues starting the server, verify that uvicorn is installed and the module path ctxvault.api.app:app is correct in your environment.
• For local testing, you can also interact with the CLI (ctxvault) to mirror the MCP behavior and validate vault structures before wiring up an MCP client.
• Consider setting access controls at the vault level if your MCP clients require restricted access.