chatvault

chatvault

Your past AI chats are already on your disk. chatvault lets an MCP client search them, reopen them, and take stock of them — without any of that history leaving the machine. There is no account, no upload and no network call: the server reads a folder of JSON files that you control.

Configuration

• CHATVAULT_CORPUS_DIR (optional) — where the corpus lives. Defaults to ~/.chatvault/corpus.
• CHATVAULT_READ_ONLY (optional) — set to 1 to make the two write tools (save_conversation, save_memory) refuse with an error naming the mode. Reads keep working.

Corpus layout

One JSON file per conversation, plus memories.json:

{
  "id": "abc",
  "platform": "claude",
  "title": "Planning a trip",
  "updatedAt": "2026-10-01T12:00:00.000Z",
  "messages": [
    { "role": "user", "text": "Where should we go?" },
    { "role": "assistant", "text": "Some ideas..." }
  ]
}

A message may also carry formattedText and images ({mime, dataBase64} entries holding retained image bytes). A conversation may carry a localTitle. An empty or missing corpus directory is fine: searches and lists simply come back empty.

Every conversation has a content fingerprint, fp2: followed by a SHA-256 hex digest. The digest covers the title, the local title when set, and every message in order — its index, role, text, formatted text when present, and each image's mime and retained bytes. Timestamps and derived fields are left out, so re-saving the same content keeps the same fingerprint while a rename or an edited message changes it. The exact serialisation (canonical JSON with sorted keys) is a labelled reconstruction.

Tools

• search_conversations — tokenised full-text search over titles and message text. Required: query. Optional: platform (exact match), title (substring), date_from and date_to (against updatedAt), and match_mode — any (default), all, or phrase. Results are ranked by match count, then recency, and carry snippets.
• get_conversation_image — the stored image for a message. Required: conversation_id, message_index, image_index. Returns the mime type and base64 bytes; a missing image is an honest error.
• get_conversation — the full transcript for id, with a contentFingerprint field.
• list_conversations — conversations by updatedAt. Optional order (newest_first default, or oldest_first) and limit.
• list_recent — most recently updated conversations with title, a short summary (an excerpt of the first user message — a reconstruction), and platform. Optional limit.
• conversation_inventory — a snapshot-paged inventory of compact {id, platform, title, fingerprint} items. Call with no arguments to start a scan, then pass each page's nextCursor back as cursor. Pages hold at most 100 items; limit can make them smaller. At most eight snapshots are held, and an unknown or expired cursor is an error asking you to start a new scan.
• corpus_status — {lastReceivedAt, count} for the corpus; lastReceivedAt is null when the corpus is empty.
• save_conversation — add or update a conversation. Required: platform, title, messages. When id is omitted one is assigned (chatvault:<n>). Returns {id, fingerprint}.
• save_memory — store a durable fact from text. The record is appended to memories.json turned off (enabled: false) until you review and enable it, and the stored record is returned.

Search and list results also carry a corpus block — {lastReceivedAt, count} — so a caller can tell how fresh and how large the corpus behind an answer is.

CLI

npx @reneturcios/chatvault corpus_status '{}'
npx @reneturcios/chatvault search_conversations '{"query":"trip"}'
npx @reneturcios/chatvault --version

Output is the tool's result text. Exit codes: 0 on success, 1 on an error result, 2 on a usage error.

MCP server

npx -y @reneturcios/chatvault mcp

MCP client config:

{
  "mcpServers": {
    "chatvault": {
      "command": "npx",
      "args": ["-y", "@reneturcios/chatvault", "mcp"],
      "env": {
        "CHATVAULT_CORPUS_DIR": "/path/to/corpus"
      }
    }
  }
}

Docker

docker run -i -v /path/to/corpus:/corpus -e CHATVAULT_CORPUS_DIR=/corpus ghcr.io/cloudcorprecords/chatvault
docker run --rm ghcr.io/cloudcorprecords/chatvault --version

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (temp corpus dirs, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios