inkvault

<!-- mcp-name: io.github.sandoreclegane/inkvault -->
# InkVault

<p align="center">
  <img src="https://raw.githubusercontent.com/sandoreclegane/inkvault/main/docs/assets/inkvault-logo-horizontal.png" alt="InkVault logo" width="560">
</p>

**Local-first, user-owned persistent memory for your AI conversations, browsing, and work.**

Keep the context behind your work: what you asked, what you learned, and the pages you opened.
InkVault preserves supported AI sessions and the browser history you choose in a local SQLite vault,
so you can find them again after the original tools have cleared their history.

Search your vault yourself in the **Memory Atlas**, or connect an AI tool through **MCP** so it can retrieve
past context when you ask. Optional Windows screen capture adds a timeline of the apps you use and text
from apps you choose. You control the sources, the vault folder, and the backups.

InkVault is free and MIT licensed. No account or telemetry. InkVault itself does not upload your archive.
If you connect an AI client, memories returned to that client may be sent to its model provider under
that client's settings.

## Start your vault

You need [uv](https://docs.astral.sh/uv/getting-started/installation/) and a terminal.
Copy your supported local sessions and chosen browser history into a vault:

```bash
uvx --from git+https://github.com/sandoreclegane/inkvault inkvault sync
```

In a terminal, InkVault greets you, asks which browser profiles are yours before reading their history, shows
progress while it builds search, and ends with a short summary. It downloads the search model on first use
(about 130 MB). When everything saved, the Memory Atlas opens by itself. Add `--no-open` to skip that. For later
visits, `inkvault dashboard` opens the Atlas again:

```bash
uvx --from git+https://github.com/sandoreclegane/inkvault inkvault dashboard
```

Search for something you remember, select a result, and read it in context. Add
[`inkvault schedule`](#keep-it-up-to-date) to refresh and back up your vault nightly, or
[connect your AI tools](#connect-your-ai-tools) to search it from a conversation.

**Have a Pieces archive to save?** See [Rescuing from Pieces](#rescuing-from-pieces).

## What InkVault preserves

With a nightly schedule, InkVault reads the session files Claude Code and Codex already keep on disk, and the history of the
browser profiles you chose, and copies in what's new: what you asked, what the assistant answered, what each session
was called, and which pages you opened. Your AI tools can then search what they helped you with, and what you were
reading, last month or last year, long after the original files are gone.

- **Claude Code**: every project, from `~/.claude/projects`. Synced messages stay in your vault after source cleanup.
- **Codex**: every session it saved, from `~/.codex/sessions`.
- **Claude desktop app** (agent mode, Windows): including prompts only its audit log kept.
- **Your browsers**: Chrome, Edge, Comet, Brave, Arc, Vivaldi, Opera and Firefox, only the profiles you say are yours
  ([how](#your-browser-history)). Kept past the browser's own cleanup.

Only what's new since the last sync is added. Tool output and attachments are left out, and sign-in codes and
tokens are cleaned out of web addresses (see [Privacy](#privacy)).

## What you get

- **A vault you own**: preserved sessions, chosen browser history, optional screen activity, and any rescued
  Pieces records in one local SQLite file, `vault.db`. Keep it independently of the tools that produced it.
- **Search for your AI tools**: an MCP server with `search_memories` (keyword + meaning, merged), `timeline`
  ("what was I doing in March?"), `get_memory`, and `memory_stats`.
- **Memory Atlas**: open it with `inkvault dashboard` (or the **InkVault Atlas** icon from `inkvault dashboard --shortcut`
  on Windows). It shows your year: active hours per day (hover a day for what it was about), when you work, how your
  projects connect, projects and topics over time, top apps and sites. Every chart has a table view. A **Search** view
  finds things across your vault and opens the original in a reader. It runs on this computer only (127.0.0.1, a
  private link, stops when idle) and needs no internet.
- **Daily Light (v0.3.2)**: a daily quotation from 32 curated public-domain passages, chosen by your local date,
  without using your history. Hide it for the current Atlas session. When indexed activity exists on today's date
  in an earlier year, **On this day** opens it in Search. You can also browse any date range by setting both
  From and To without entering a keyword. These date-browsing additions are Atlas-only; MCP tools are unchanged.
- **Your Claude Code, Codex and Claude desktop sessions**: your prompts and the replies, side by side with your
  other preserved history, searchable as chats (named like `Claude Code · project: title`), and part of the timeline, the
  digests and the dashboard.
- **Your browser history**: pages you opened in Chrome, Edge, Comet, Brave, Arc, Vivaldi, Opera or
  Firefox, from the browser profiles you say are yours. Visits already copied stay in the vault after the browser
  removes them. Searchable as `web`, on the timeline, in the digests and on the dashboard.
- **Screen capture** (optional, Windows): a timeline of the windows you used, plus the text of the windows in
  apps you choose. No images are kept. See [Screen capture](#screen-capture-windows).
- **Daily digests** (optional): a 2-3 sentence summary of each day, written by a *local* model through
  [Ollama](https://ollama.com). Summarize your preserved activity without sending it to a hosted model.

## Connect your AI tools

**Claude Code**

```bash
claude mcp add inkvault --scope user -- uvx --from git+https://github.com/sandoreclegane/inkvault inkvault serve
```

**Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.inkvault]
command = "uvx"
args = ["--from", "git+https://github.com/sandoreclegane/inkvault", "inkvault", "serve"]
```

**Hermes, Claude Desktop, and other MCP clients**: run `uvx --from git+https://github.com/sandoreclegane/inkvault inkvault serve` over stdio.

Then ask: *"What was I working on the week of March 10?"*, *"Find that retry helper I saved"*, *"When did I last look at the Stripe dashboard?"*

## Your browser history

A browser profile can belong to someone else, so InkVault reads none until you choose:

```bash
inkvault browsers
```

It lists every profile it finds (browser, name, signed-in email) and asks which are yours. `sync` and `rescue`
ask too when they find a new one; the nightly run never asks, and skips profiles you haven't chosen. If someone
else starts using a browser on this computer, run `inkvault browsers` again: InkVault notices a profile that was
replaced on Windows and macOS, and when a profile's signed-in account changes, but it can't always tell.

- `inkvault browsers --no "chrome/Profile 2" --forget` stops copying a profile and removes what was copied, even
  after the browser is uninstalled.
- `inkvault browsers --skip-site mybank.com` never keeps that site or its subdomains, and removes what's there.

Removing rebuilds search and the dashboard and deletes the digests for each removed visit's day (in UTC) and the day
either side. If it's interrupted, the next `inkvault sync`, `inkvault index` or nightly run finishes it, and search
stays off until then. It can't recall an answer your AI tool already received, or a dashboard tab that's already
open. The nightly backups still hold the removed visits until they rotate out (7 nights).

**What's kept:** each page's address and title, and when you opened it. Before anything is stored, InkVault
removes parts of addresses that carry sign-in codes, tokens, signed links, password-reset tokens, and your email
or username. Searches (`?q=…`) stay. This catches the common shapes, not every possible secret. Copying happens
while the browser runs, so the newest few visits can wait for the next sync.

Safari isn't supported yet (macOS blocks reading it without Full Disk Access).

## Screen capture (Windows)

With `inkvault watch`, you can add a local timeline of foreground windows and read text from apps you choose.
Screen capture stays off until you install the watcher. It's Windows-only for now; on macOS and Linux
`inkvault watch` says so and exits.

**What it records**

- **A timeline, everywhere.** Every foreground window becomes a *stretch*: the app, a cleaned title, and when it
  started and ended. A window you only flick through isn't kept, and time you're away (no input for 5 minutes, or the
  screen is locked) isn't counted.
- **Text, in apps you choose.** After you settle on a window for 30 seconds, InkVault reads its text (Windows' own
  OCR, on your machine) and stores it if it changed. A given window is read at most every 2 minutes.
- **No images, ever.** The window image exists in memory just long enough to read, and is never written to disk.
- Before anything is stored, secrets in titles and text (API keys, tokens, JWTs, `password: ...` values) are masked
  and URLs are cleaned. This catches the common shapes, not every possible secret.

**Which apps get text.** By default: Comet and Edge; Claude, ChatGPT, Perplexity and Codex; Windows Terminal, VS
Code and Cursor; Notion, Obsidian and Notepad; and the Microsoft 365 apps (Word, Excel, PowerPoint, Outlook, new
Outlook, OneNote). Every other app is timeline-only. Two groups are off until you say yes, and `--install` asks:

- **Messaging apps** (Discord, WhatsApp, Telegram, Teams, LinkedIn). Reading them stores other people's messages and
  names, and Discord's title is the name of the person you're talking to. Off unless you answer yes.
- **Chrome.** Its window title is just the page and "Google Chrome", with no profile name, so InkVault can't tell
  your Chrome profiles from anyone else's. Off unless you answer yes.

Without a terminal (for example a scripted install) both stay off. You