Everkeep

Everkeep

Stop re-explaining yourself to your AI.

Everkeep keeps your notes, decisions and projects in one folder on your own server. Your AI assistant reads it when a chat starts and writes down what you worked out — so tomorrow's conversation picks up where today's ended. You decide what it may change; it can't delete or overwrite anything you haven't allowed.

Works with Claude and any MCP client · runs on Linux, Docker or Home Assistant

Your documents, too

Drop contracts, invoices, manuals, price lists and exported reports into the folder as they are — PDF, Word, Excel, PowerPoint, e-mails. Your AI reads them as text, searches all of them at once and tells you where it found the answer: *"which contract has a 30-day payment term?"* comes back with the file and the page. No uploading files into every chat, no copy-pasting; a new version of a file is read the next time it is needed. Scanned pages it looks at as images.

Files go into the folder by ordinary copying, like into any other folder: see putting your files in.

Quick start

This gets Everkeep running on your own computer with Docker and connects Claude to it. You need about ten minutes and no programming.

1. Install Docker. On Windows or macOS, install Docker Desktop and start it; wait until it says Docker is running. On Linux, install Docker Engine.

2. Start Everkeep. Open a terminal (on Windows: PowerShell; on macOS: Terminal) and paste the two lines for your system. The first creates the folder everkeep-notes in your home folder; that folder is where your notes will live. The second downloads Everkeep and starts it in the background; it starts again by itself after a reboot.

Windows (PowerShell):

mkdir $HOME\everkeep-notes

docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME\everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.1.0

macOS or Linux:

mkdir -p ~/everkeep-notes

docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME/everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.1.0

On Linux the folder must be writable by user id 1000. If the command id -u prints a different number, follow Docker: who owns the folder instead.

3. Protect your notes. One more line, in the same terminal:

docker exec everkeep everkeep policy set . --mode rev --trash

From now on Claude can create new files in the folder, but it can change an existing file only after reading it, so it never overwrites what it has not seen. Nothing is deleted: a file Claude discards goes into the folder .vault-trash inside everkeep-notes, and you can take it back from there.

4. Get your token. Everkeep made a secret token on its first start. Show it:

docker exec everkeep everkeep token

It prints two lines. The first is the secret path for claude.ai, the second the header for other clients:

/private_<token>/mcp

Authorization: Bearer

Treat both like a password: whoever has them can read and change your notes.

5. Connect Claude.

• Claude Code on the same computer:

  claude mcp add --transport http everkeep http://127.0.0.1:3100/mcp --header "Authorization: Bearer <token>"

• Claude Desktop on the same computer: add the block from Claude Desktop to its config file and restart it.
• claude.ai in the browser, or the Claude apps: they connect from the internet, so Everkeep needs a public HTTPS address. Remote access shows two free ways, step by step. Then, in claude.ai → Settings → Connectors → Add custom connector, paste https:// /private_ /mcp.

6. Try it.

• Ask Claude: *"Use Everkeep to create a file about-me.md with what you know about my current projects."* The file appears in your everkeep-notes folder.
• Open the folder: on Windows, type explorer $HOME\everkeep-notes in the same PowerShell (or go to This PC → Users → your name → everkeep-notes); on macOS, type open ~/everkeep-notes in Terminal (or Finder → your home folder); on Linux, open your home folder in the file manager.
• Copy a contract, an invoice or any PDF or Word file into it, by dragging or copy and paste, as into any folder. Everkeep sees it at once; nothing needs restarting. Folders inside it are fine and useful: contracts/, projects/….
• Ask Claude: *"Use Everkeep: what does the contract in my notes say about payment terms? Give the page."*

To have Claude read your notes at the start of every chat, add a line like this in Settings → Account → Instructions for Claude, or to a project's instructions: *"At the start of a chat, read /vault/about-me.md with Everkeep."* Inside Docker your folder is /vault.

To change the rules for a folder, see Write policies.

What it is

Everkeep is an MCP server. MCP is the way AI clients such as Claude call tools on other machines. Everkeep's tools work on one directory tree, the *vault*: read, search, edit, move and discard files, read documents and PDFs, query SQLite databases read-only. Nothing outside the vault can be reached through it.

What the assistant may change is set per directory with *write policies*: a directory can be read-only, editable only by someone who has read the current version of a file, open to new files only, or free. There is no delete: discarding moves a file into a trash directory of its zone. The assistant cannot change the policies; you set them on the server.

It runs as one process, over HTTP for remote clients such as claude.ai and over stdio for local ones such as Claude Desktop.

What it looks like

The assistant lists a directory. The first line says what is allowed there:

Policy: overwrite=rev, trash=.vault-trash, auto-purge after 30 d — own marker (/vault/wiki/.vault-policy)

[FILE] .vault-policy [DIR] .vault-trash [FILE] decisions.md [FILE] todo.md

It tries to overwrite todo.md without having read it, and is refused:

Error: Refused — policy "overwrite: rev": changing an existing file requires its current rev, which is 5db20d56. Nothing was written. Repeat the call with rev: "5db20d56".

It searches, gets line numbers and the file's rev, and edits one line:

/vault/wiki/todo.md · rev 5db20d56 · 212 lines

148: - [ ] Check backup-rotation settings on the NAS

— 1 match(es) in 1 file(s) · scanned 37/37 files, 190 KB, 12 ms

Requirements

Installation

Docker

The image ghcr.io/st412m/everkeep runs everkeep serve on port 3100 as user id 1000, with the vault at /vault and its own state (token, document cache) in the volume /data. The Quick start shows docker run; compose.example.yaml does the same with Docker Compose. Folder ownership, updates and building the image yourself: installation.

Linux without Docker

Install poppler-utils and sqlite3 with your package manager, then run it with npx:

npx --yes --package=everkeep everkeep serve --vault /home/me/notes

On first start it prints the token once; everkeep token shows it again. For a permanent everkeep command, a CPU without AVX (some Celeron, Atom and Pentium models) and a systemd service, see installation. Windows and macOS are not supported without Docker.

Home Assistant

Install the ha-filesystem-mcp app. It runs Everkeep with the vault under /media or /share and adds the Vault policies page to the sidebar.

Configuration

Settings come from flags, environment variables and an optional JSON file (EVERKEEP_CONFIG, else ~/.config/everkeep/config.json). The ones to know first:

everkeep check-config prints what is in force and checks the tools Everkeep needs. Every key, the token rules and the request log: configuration.

Connecting

• claude.ai, Claude Desktop connectors, the Claude apps: Settings → Connectors → Add custom connector with https:// /private_ /mcp. The address must be public HTTPS: remote access.
• Claude Code: over HTTP with the Bearer header, or on stdio:

  claude mcp add --transport stdio everkeep -- npx --yes --package=everkeep everkeep --vault /home/me/notes

• Claude Desktop without a public address: Everkeep on stdio through Docker, see Claude Desktop.
• Cursor and other clients: the URL http://127.0.0.1:3100/mcp (or your HTTPS address) with the header Authorization: Bearer , see installation.

There is no OAuth: the token is the only key. A wrong path gets an empty 404, a wrong Bearer token 401.

Tools

20 tools. Parameters and return formats: tools.

Reading

• read_text_file — a whole file, head/tail lines, or an offset/limit range with line count and rev; documents as numbered lines
• read_multiple_files — several whole files in one response
• read_media_file — image or audio as base64
• read_pdf_text — text of a PDF or a page range, numbered like read_text_file
• read_pdf_page — one PDF page rendered as JPEG

Searching

• grep_files — regex search of file contents, documents included; returns path, rev, line count and matching lines
• search_files — find files and directories by name

Writing

• write_file — create or overwrite a file
• edit_file — literal oldText replacement, or line-addressed edits guarded by rev
• create_directory — create a directory and its parents
• move_file — move or rename a file or directory; also restores from the trash
• copy_file — copy a file; the destination follows the rules of write_file
• trash_file — move a file into its zone's trash; there is no delete

Listing

• list_directory — entries of one directory, after the policy line
• list_directory_with_sizes — entries with file sizes, sorted by name or size
• directory_tree — tree view, two levels deep
• get_file_info — size, times and format, plus line count and rev for text files
• `list_allowed_direct