chatvault
README.md
# 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`:
```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
```bash
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
```bash
npx -y @reneturcios/chatvault mcp
```
MCP client config:
```json
{
"mcpServers": {
"chatvault": {
"command": "npx",
"args": ["-y", "@reneturcios/chatvault", "mcp"],
"env": {
"CHATVAULT_CORPUS_DIR": "/path/to/corpus"
}
}
}
}
```
## Docker
```bash
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
```bash
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
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data