Cogvault

MCP文档知识

提供方 未标注

文档知识 stdio · 本地进程 未标注 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

基于纯Markdown文件的AI代理本地记忆:混合向量+BM25召回(RRF),每个代理目录拥有独立隔离的记忆,完全离线运行,无需LLM参与。

一句话选型结论

按资料字段整理

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

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

工具与能力

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

能力标签

支持客户端

适用场景

记忆

安装与配置

stdio · 本地进程 未标注
客户端在本机拉起子进程,数据不出本机
claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory

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

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

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

  3. 3
    写入客户端配置

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

  4. 4
    验证是否可用

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

典型使用场景

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

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

知识库读写

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

内容整理

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

选择建议

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

值得选的地方

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

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

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

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Cogvault当前 未标注 stdio · 本地进程 本地部署 有 未标注
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

服务器档案

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

详细介绍

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

Get started in 30 seconds

Claude Code plugin — MCP server plus a skill that tells the agent when to recall and
when to record:```text
/plugin install cogvault --marketplace NBibikov/cogvault


Claude Code before 2.1.275: `/plugin marketplace add NBibikov/cogvault`, then
`/plugin install cogvault@cogvault`.

Memory lives in `~/.cogvault/memory` (set `COGVAULT_TENANT` to change it). The plugin
adds `/cogvault:remember`.

**Any MCP client, one line** (needs uv):```bash
claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory

Claude Desktop, Cursor, Windsurf, Cline — JSON config

Add to claude_desktop_config.json, ~/.cursor/mcp.json, or your client's MCP config:```json
{
"mcpServers": {
"cogvault": {
"command": "uvx",
"args": ["cogvault", "mcp", "--tenant", "~/agent/memory"]
}
}
}


**Already have Markdown memory?** Point the tenant at it — nothing to import. Claude
Code's auto-memory works as-is (frontmatter `type`, `[[links]]` and all):```bash
M=~/.claude/projects/<project>/memory
uvx cogvault index  --tenant $M --ignore MEMORY.md   # first pass embeds, later passes are incremental
uvx cogvault search --tenant $M "how do we deploy"

The MCP server indexes on start by itself; the CLI search reads the existing index.
--ignore MEMORY.md keeps the index file from competing with the cards it points to.

Unedited answers from a real session (Sonnet, plugin installed, a demo memory of six
cards); only the waiting time is cut.


Why

Most "AI agent memory" tools want to be an autonomous LLM daemon that summarizes your
work into an opaque database or a graph you can't read. For a fleet of coding agents
that just need to reliably recall a decision, a bug fix, or an infra detail, that's
the wrong trade.

cogvault makes the opposite bet:

  • Your Markdown files are the source of truth. Open them, edit them, git diff
    them. The SQLite index is a derived cache — delete it and it rebuilds from the files.
  • One library, many tenants. Each agent gets an isolated memory namespace via its
    own directory. A process loads each embedding model once and shares it across
    every tenant it touches; with the stdio MCP server that means one small process
    per agent session, not a central daemon.
  • No LLM in the loop. Ingest and retrieval are deterministic. Your agent is the
    LLM — it doesn't need a second one to remember.
  • Local, private, offline. FastEmbed runs
    on-device. Nothing leaves your machine.

Compared to

Checked against each project's README and docs on 2026-10-05.

cogvault basic-memory mem0 Graphiti Letta Code
Source of truth Markdown files Markdown files Vector DB (Qdrant / pgvector) Graph DB (Neo4j, FalkorDB, …) Markdown in a git repo per agent
LLM needed to store or recall No No (optional reranker) Yes by default (add() extracts facts) Yes to ingest Yes — the agent edits its memory
Retrieval Vector + BM25, RRF, decay, MMR Full-text + vector, optional rerank Semantic + BM25 + entities Semantic + BM25 + graph File search; hybrid optional
Infra One process, SQLite file One process, SQLite (Postgres optional) Library, or Docker + Postgres server A graph database Letta backend

Pick something else when: you want an LLM to distil and merge facts for you (mem0),
relationships between entities are the point (Graphiti), you want the agent to manage its
own memory (Letta), or you want a richer notes app around the same Markdown idea, with
Obsidian sync and a hosted option (basic-memory — the closest to cogvault).

Pick cogvault when: you run several agents and want each one's memory isolated in its
own directory behind one process; you want recall to be deterministic and offline; and you
want to measure it — cogvault eval scores recall on your agents' real queries and
cogvault analyze lists what they tried to recall and couldn't.

How it works

Anatomy of a recall

Hybrid retrieval fuses semantic (vector) and keyword (BM25/FTS5) ranking with
Reciprocal Rank Fusion,
then applies optional temporal decay (recent memory outranks stale) and MMR
(diverse top results, not five near-duplicates). Each card contributes only its
best chunk, so one long file can't fill the whole result list.

Benchmark

Measured on real recall traffic, not synthetic questions: 66 queries sampled from the
query logs of 6 live agent tenants (58% Ukrainian, the rest English), each judged against
the actual cards — including answers that no configuration returned. One query has no
answer in memory and counts as a gap, so 65 are scored. Every configuration was re-indexed
from scratch on copies of the same tenants with cogvault 0.11.0.

Configuration hit@1 hit@5 MRR@10
multilingual-e5-small, chunk_chars = 700, summary chunk 0.57 0.91 0.70
multilingual-e5-small, chunk_chars = 700, no summary chunk 0.55 0.86 0.69
paraphrase-multilingual-MiniLM-L12-v2 (built-in default) 0.54 0.80 0.66
bge-small-en-v1.5 (English-only) 0.57 0.77 0.65

What the numbers do and don't say:

  • hit@1 is a tie. All four land within 0.54–0.57, and the 95% bootstrap intervals
    overlap almost completely. Real agent queries read like card titles, so the right card
    usually wins on its name alone.
  • The gap is in the top 5. e5-small with the summary chunk puts the answer in the top 5
    for 91% of queries vs. 80% for the default MiniLM and 77% for English-only bge on this
    mixed-language memory. That's what an agent reading 5 results actually feels.
  • 65 queries is still a small sample. Treat differences under ~0.1 as noise. The
    aggregate numbers are in assets/benchmark.json; the queries
    are private and stay in each tenant.

Reranking

A cross-encoder reads the query and each candidate card together, so it can tell which
card answers the question, not only which one is about the same topic. With
rerank = "BAAI/bge-reranker-v2-m3-int8", cogvault scores the hybrid top 10 by the first
800 characters of each card file and reorders them. On the same 65 queries
(cogvault 0.12.0, e5-small + summary chunk):

hit@1 hit@5 MRR@10
hybrid only 0.60 0.88 0.70
hybrid + reranker 0.80 0.91 0.85

The reranker made 17 queries better and 3 worse. The 95% bootstrap interval of the hit@1
gain is +0.09 to +0.34. The cost is ~2 GB RAM and 1–2 s per recall on an Apple M-series
CPU, so it runs only in the shared daemon and in cogvault eval
(--no-rerank scores without it).

Run the same check on your own memory: put judged queries in
/.cogvault-golden.jsonl ({"query": "...", "relevant": ["file.md"]}, empty
relevant = a known gap) and run cogvault eval --tenant DIR.

Choosing an embedding model

Agent memory is often not English-only. The default is multilingual so nothing
is broken out of the box — but pick the model that matches your fleet's language mix
(set COGVAULT_MODEL, or Config(model=...)). Switching models auto-rebuilds the index.

Model (COGVAULT_MODEL) Dim Size Real-query hit@5* Cyrillic / multilingual When
paraphrase-multilingual-MiniLM-L12-v2 (default) 384 0.22 GB 0.80 ✅ works Mixed-language fleets; safe default
BAAI/bge-small-en-v1.5 384 0.13 GB 0.77 ❌ Cyrillic vectors break English-only memory
intfloat/multilingual-e5-small 384 0.47 GB 0.91 ✅ best per GB (512-token window) Mixed-language fleets; use chunk_chars = 700
intfloat/multilingual-e5-large 1024 2.24 GB not measured ✅ best Max quality, RAM to spare

From the benchmark above: 65 real queries over mixed EN/UK memory,
cogvault 0.11.0. On English-only memory bge-small-en is a fine choice; on Ukrainian
content it returns a
negative* relevance margin (a distractor outranks the answer),
so it is unsafe for non-English memory. Run cogvault eval on your own vault to decide.```bash
COGVAULT_MODEL=BAAI/bge-small-en-v1.5 cogvault index --tenant ~/agent/memory


**Pin the model per tenant** so it travels with the data instead of relying on every
command exporting `COGVAULT_MODEL` (forget it once and a model mismatch silently
re-embeds the whole index). Drop a `.cogvault.toml` at the tenant root:```toml
# ~/agent/memory/.cogvault.toml
model = "BAAI/bge-small-en-v1.5"
# optional: recursive = true, strip_frontmatter = true, ignore_globs = ["Templates/*"]

Now cogvault search --tenant ~/agent/memory "…" uses the right model with no env var.
Precedence: explicit --model / $COGVAULT_MODEL > .cogvault.toml > built-in default.

Install```bash

uv tool install cogvault # CLI on PATH

or

pip install cogvault


Or skip installing and run it on demand with `uvx cogvault …`. The first run downloads
the embedding model (~0.2–0.5 GB, once per machine).

**Add it to Claude Code as an MCP server in one line:**```bash
claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory

Also listed in the official MCP Registry
as io.github.NBibikov/cogvault. Wheels are attached to each
GitHub release.

Quickstart```bash

index a tenant's markdown memory

cogvault index --tenant ~/agent/memory

search (hybrid semantic + keyword)

cogvault search --tenant ~/agent/memory "how do I restart the worker service"

enable temporal decay (recent wins) and tune diversity

cogvault search --tenant ~/agent/memory "deployment steps" --half-life 30 --mmr 0.5

only cards of one frontmatter type (user / feedback / project / reference / …)

cogvault search --tenant ~/agent/memory "hard rules for deploys" --type feedback


### Memory cards

cogvault understands two lightweight Markdown conventions (both optional —
plain files index fine):

- **Frontmatter `type`** — either flat (`type: reference`) or nested
  (`metadata:` → `type: reference`). Parsed at index time and filterable at
  search time (`--type`, MCP `type` param, `search(card_type=...)`). Every hit
  carries a `type` field; cards without frontmatter get `null`.
- **`[[wiki-links]]`** — link targets are indexed, and the top search result
  includes a `related` list of linked cards that exist in the index (ghost
  links are dropped; matching is by exact filename stem).

### As an MCP server (Claude Code, Cursor, any MCP client)```bash
claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory

Exposes two tools:

  • cogvault_recall — natural-language hybrid search over this agent's memory.
    Optional type param filters to one frontmatter card type; the top result
    includes a Related: line built from its [[wiki-links]].
  • cogvault_record — save a fact; it's written as a Markdown card and indexed

Indexing a folder tree (Obsidian vaults, knowledge bases)

By default a tenant is one flat directory of .md files. For a nested vault
(e.g. Obsidian, with 01-Projects/…, frontmatter, and folders to skip), opt in:```bash
cogvault index --tenant ~/vault \
--recursive \
--strip-frontmatter \
--ignore ".obsidian/" --ignore ".trash/" --ignore "Templates/*"


- `--recursive` walks subdirectories; files keep their path relative to the tenant,
  so two notes named `Tasks.md` in different folders never collide.
- `--strip-frontmatter` drops a leading YAML `--- … ---` block so its keys don't
  pollute the embedding.
- `--ignore GLOB` (repeatable) skips paths relative to the tenant root.

Same flags exist on `search` and `mcp`, and as `Config(recursive=True,
strip_frontmatter=True, ignore_globs=(...))` for the library. Indexing is
incremental: the first pass embeds everything, later passes only re-embed changed
files. (Reference: a ~3,500-note vault → ~9,500 chunks, first index ≈ 3–4 min,
then warm recall in single-digit milliseconds.)

### As a library```python
from cogvault import Vault, Config

vault = Vault("~/agent/memory", Config(half_life_days=30))
vault.reindex()
for hit in vault.search("where are credentials stored"):
    print(hit["score"], hit["file"], hit["snippet"])

Keeping a tenant healthy

cogvault doctor --tenant DIR reports what silently degrades recall: cards with
no frontmatter or type, legacy timestamp filenames, frontmatter wrapped inside
frontmatter, duplicate name: slugs, and [[links]] that resolve to nothing.
Links resolve by frontmatter name:, filename stem, either separator style, and
with or without the card-type prefix; links inside code and paths to files outside
the tenant are not counted.

cogvault repair --tenant DIR fixes the mechanical half (dry run by default,
--apply to write): unwraps nested frontmatter, infers a missing type, renames
card--….md to _.md and rewrites every reference to it
(MEMORY.md included), and adds minimal frontmatter to _*.md cards that
lack it. Healthy cards are left alone, and repaired cards keep their mtime so
temporal decay is not reset.

Effectiveness logging

Every recall is logged (one JSONL line) so you can measure whether the memory is
actually helping. cogvault analyze turns the log into a report:```bash
cogvault analyze # recalls, latency, per-tenant hit distance, weakest hits, card writes
cogvault analyze --json # machine-readable
cogvault analyze --since 7 # only the last 7 days (or --since 2026-10-05)


The section that matters is **weakest hits**: each tenant's worst decile by vector
distance — queries where recall returned *something* (hybrid search almost always does)
but probably not the answer. That list is what your agents tried to recall and couldn't,
i.e. the memory gaps to fill. Set `COGVAULT_LOG=off` to disable, or
`COGVAULT_LOG=/path.jsonl` to relocate.

## Multi-tenant fleets

Point one process at many tenants — each directory is an isolated namespace, proven by
the test suite (`test_multi_tenant_isolation`). Agent B can never recall Agent A's
memory unless you point B at A's directory.

### Shared daemon

Each MCP client starts its own `cogvault mcp`. Without a daemon, each of these processes
loads the embedding model (~1 GB), and none can afford the reranker. `cogvault daemon`
loads each model once for all tenants and serves them over a Unix socket
(`~/.cache/cogvault/daemon.sock`, mode 600). `cogvault mcp` and `cogvault search` find it
automatically and forward to it; the MCP process then stays at ~40 MB. When the daemon is
down, they search in-process as before, without the reranker, and log one
`daemon-fallback` event to the query log.```bash
cogvault daemon            # run in the foreground
cogvault daemon --status   # ping it: version, loaded models, tenants served

The daemon unloads a model after 10 minutes without a search or reindex, and loads it
again on the next recall (~1.5 s extra on that call). Set --idle-unload SECONDS or
$COGVAULT_IDLE_UNLOAD (0 keeps the models loaded). Measured with e5-small and the
reranker: ~1.8 GB loaded, ~0.4 GB unloaded. ONNX Runtime uses 4 threads
($COGVAULT_THREADS, 0 = all cores) and no CPU memory arena, so a full reindex peaks
at ~1 GB instead of keeping several GB after it. A shim that booted while the daemon was
down waits up to 60 s for it before it loads a model itself, and drops a model it loaded
as soon as the daemon answers again.

The reranker has its own thread count ($COGVAULT_RERANK_THREADS, default = the
performance cores on Apple silicon, else 4). It runs only at recall time and is most of
the recall latency: on 10 P-cores, recall p50 went from 2.3 s (4 threads) to 1.65 s, and to 1.05 s
with onnxruntime 1.31 (that version also cut 4-thread recall to 1.5 s).

On macOS, run it under launchd with RunAtLoad and KeepAlive (program arguments
cogvault daemon). After you upgrade cogvault, restart the daemon:
launchctl kickstart -k gui/$(id -u)/.

Design notes

Decision Why
Markdown = source of truth Human-readable, git-versionable, editable, never locked in a DB
SQLite + sqlite-vec + FTS5 Zero-infra hybrid search; one portable .db file; rebuildable
FastEmbed (multilingual MiniLM default, 384-d) In-process ONNX, no server, no API key, ~220 MB
Content-hash cache Re-indexing only embeds changed chunks
RRF + decay + MMR Precision, recency, and diversity without a graph DB
One process, many tenants Fleet infra, not a single-user desktop sidecar
WAL + incremental reindex Concurrent agents read while one writes; only changed files re-embed
Optional shared daemon One copy of each model for the fleet; clients fall back in-process when it is down

Roadmap

  • [ ] Importers (migrate existing memory from other stores)
  • [ ] Pluggable embedders (Ollama, OpenAI-compatible endpoint)
  • [ ] valid_until per-card temporal validity
  • [ ] Optional FastMCP transport

License

MIT — your memory, your files, your infrastructure. Forever.

Figures are hand-built SVG from assets/make_graphics.py — python assets/make_graphics.py --png regenerates them.

常见问题

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

在客户端按下面的安装命令接入:claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory。装完在客户端配置里引用同一个包或端点。

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

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Cogvault 收费吗?

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

Cogvault 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

Cogvault 支持哪些客户端?

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

Cogvault 能提供哪些能力?

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

Cogvault 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Cogvault 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

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

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