Ctxvault

MCP文档知识

提供方 未标注

文档知识 未标注 会话登录 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

AI 代理的本地记忆:以磁盘上的普通文件夹形式存储语义、技能和情景记忆库。

一句话选型结论

按资料字段整理

Ctxvault 属于文档知识类 MCP 服务器,传输方式未标注,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式未标注 鉴权会话登录 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

记忆

安装与配置

未标注 会话登录
上游未给出传输方式
{ "mcpServers": { "ctxvault": { "command": "uvx", "args": ["ctxvault", "mcp"] } } }

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Ctxvault当前 未标注 未标注 未标注 有 2026-11-20
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-11-20上游最后核验时间

详细介绍

12.9 KB
来自项目仓库与上游目录的原文,未做删改

Local memory infrastructure for AI agents

Isolated vaults. Typed memory. Agent-autonomous. Human-observable.


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, one for each kind of memory an agent has. 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: what it knows, how it acts, and what happened. Most agent frameworks ignore the distinction and store everything in a single vector index. In CtxVault each kind of memory is a vault type:

Vault Memory What it holds How the agent reads it
Semantic Semantic: what the agent knows Documents (PDF, DOCX, MD, TXT), chunked and embedded into a local vector index By meaning: a query returns the closest chunks, with their source
Skill Procedural: how the agent acts Procedures in markdown, each with a name and a description By name: the agent lists the skills and reads the one it needs
Episodic Episodic: when something was true Statements with two timelines: when they hold in the world, and when the vault learned it By entity, validity and source, as of today or any past instant

All three types share the same primitives: public or restricted, local or global, composable in any topology. How each type works →

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.

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

### 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. Whatever an agent wrote, through any interface, you can look at it three ways, and add to it yourself.

**On disk.** Every vault is a plain directory on your machine, readable and editable with any tool. Drop a document into a semantic vault or a skill into a skill vault, index it, and the agent sees it next to what it wrote on its own.```
.ctxvault/
├── config.json              # the registry: every vault, its type, who can reach it
└── vaults/
    ├── product-sheets/      # semantic: your documents, and the chroma/ index
    ├── counter-procedures/  # skill: one markdown file per skill
    └── store-facts/         # episodic: episodes.db, a SQLite file

From the CLI. The same vaults, queried directly, independent of what any agent is doing.```bash
ctxvault docs my-vault # what the agent has written
ctxvault query my-vault "what decisions were made last week?"
ctxvault index my-vault # add your own documents
ctxvault episodes my-vault --all # an episodic vault's statements


**In the browser.** `ctxvault ui` opens the memory viewer: a map of every vault, its type and the agents that can reach it, and a page per vault. Semantic documents show their chunks as the agent receives them, skills are rendered from their markdown, and an episodic vault has a time cursor that rewinds it to any past day. It is read-only and entirely local, and `--export` writes it to one self-contained HTML file. Try the live demo, no install needed: the bakery of example 07, three agents, six vaults, a year of facts.

The map of the live demo: three memory types, three agents, and what each agent can reach.

### 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 four interfaces. Use whichever fits your context, or combine them freely.

**Python client**: In-process. Import `Client`, open a vault by name and call it directly, with no server to start: for scripts, tests, pipelines and agents that own their memory.

**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_doc`, and `list_docs` on its own, and on an episodic vault it records and corrects facts with `write_episode`, `query_episodes`, `supersede_episode` and `invalidate_episode`, brings a close back with `reopen_episode`, counts repetitions with `confirm_episode`, holds contradictions open with `dispute_episodes`, and discovers what the vault is about with `list_entities`.

Whichever door wrote it, `ctxvault ui` shows it: the viewer reads the same vaults, so what an agent recorded over MCP is on the page next to what you indexed from the CLI.

---

## CtxVault vs Alternatives

| | CtxVault | Chroma + your code | LangChain Memory | Mem0 | Graphiti (Zep) |
|--|----------|--------------------|------------------|------|----------------|
| Runs without cloud services | ✓ | ✓ | ✓ | self-hosted | self-hosted, plus a graph database |
| MCP server | ✓ | you build it | ✗ | ✓ | ✓ |
| Automatic fact extraction from conversations | ✗ (the agent decides what to write) | you build it | ✗ | ✓ | ✓ |
| Distinct memory types (semantic, procedural, episodic) | ✓ | you build it | ✗ | ✗ | ✗ |
| Bi-temporal facts (valid time and transaction time) | ✓ | you build it | ✗ | partial | ✓ |
| Graph-structured memory (entities and relations) | ✗ (planned) | you build it | ✗ | ✓ | ✓ |
| Per-agent access control | ✓ | you build it | ✗ | ✗ | ✗ |
| Storage as plain files on disk | ✓ | ✓ | ✗ | ✗ | ✗ (graph database) |
| Inspection UI | local | ✗ | ✗ | hosted | ✗ |

The ✗ in the CtxVault column are real: there is no graph layer and it does not extract facts for you. The ✓ are what it was built for: memory types, time, access control, and storage you can open as a folder.

---

## Examples

Seven scenarios, each with full code and setup instructions.

| # | Example | What it shows |
|---|---------|---------------|
| 01 | **Single-Vault RAG** | Single vault, single agent. Semantic RAG over PDF, MD, TXT, DOCX with source attribution. ~100 lines. |
| 02 | **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. |
| 03 | **Persistent Memory** | An agent that recalls context across sessions using semantic queries. "financial constraints" retrieves "cut cloud costs by 15%" written three days prior. |
| 04 | **Access Control** | Three agents, five vaults: private, shared between a subset, and public. A tiered support system where access boundaries reflect organizational boundaries. |
| 05 | **Procedural Memory** | One agent, two vault types, semantic and skill, integrated via MCP. Retrieves knowledge for *what* to say and skills for *how* to say it. |
| 06 | **Episodic Memory** | One account followed across six months. Facts are superseded instead of overwritten, so the briefing uses only what holds today while April is still reconstructable. |
| 07 | **Full Memory Topology** | Everything in one place: three agents, six vaults, all three memory types, access rules, a year of facts replayed with their dates. The capstone example, a small bakery, and the dataset behind the live demo. |

---

## Installation

**Requirements:** Python 3.10+```bash
pip install ctxvault

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


---

## Quick Start

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`.```bash
ctxvault init notes

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


**3. Ask it.** Retrieval is by meaning, so the words do not have to match.```bash
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:```json
{
"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.**```bash
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.


Documentation

The full reference lives on the documentation site:

  • Quick start: from nothing to an agent that remembers.
  • Connect an agent from Python, over HTTP or through MCP: the three setups, each with its own configuration.
  • How it works: memory types, local and global vaults and access control.
  • Memory viewer: what ctxvault ui shows, snapshots, and who can open it.
  • Reference: the CLI, the HTTP API and the MCP tools.

Roadmap

  • [x] CLI MVP
  • [x] FastAPI server
  • [x] Multi-vault support
  • [x] Agent write API
  • [x] MCP server support
  • [x] Access control
  • [x] Typed memory (semantic + procedural vaults)
  • [x] Episodic memory (bi-temporal statements, supersession, time travel)
  • [ ] Graph-backed semantic memory
  • [ ] File watcher / auto-sync
  • [ ] Context pruning

Contributing

Contributions welcome! Please check the issues for open tasks.

Development setup:```bash
git clone https://github.com/Filippo-Venturini/ctxvault
cd ctxvault

With uv (recommended)

uv sync --extra dev
uv run pytest

With pip

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:```bibtex
@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.


Security


Acknowledgments

Built on Chroma for vector storage, Sentence Transformers for embeddings, FastAPI for the HTTP API, the MCP Python SDK for the MCP server and Typer for the CLI. The memory viewer is built with Preact and htm, and the documentation with Material for MkDocs. The examples use LangChain.


Made by Filippo Venturini · Report an issue

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
Ctxvault 怎么安装?

在客户端按下面的安装命令接入:{ "mcpServers": { "ctxvault": { "command": "uvx", "args": ["ctxvault", "mcp"] } } }。装完在客户端配置里引用同一个包或端点。

Ctxvault 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Ctxvault 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Ctxvault 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Ctxvault 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Gemini CLI、Codex;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Ctxvault 能提供哪些能力?

资料显示能力标签包括 记忆。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-11-20。