Skip to main content
Glama
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