scrap#

scrap is a memory system for Claude Code: a self-hosted store that Claude searches, reads and writes over MCP (and the /sc-* commands). Capture from your phone in seconds, never waiting on an LLM, then see it all in a PWA: photos, Excalidraw diagrams and rendered markdown. It follows the LLM Wiki pattern, and your words and Claude’s never mix: page text is yours, and everything Claude adds is stored apart, labelled and regenerable.

Status: in daily use, and deployed on Kubernetes.

Goals#

  • Simple: one service, one process, one SQLite file.

  • Off-the-shelf parts wherever they exist: Claude for chat and reasoning, SQLite for storage and search, Tailscale for access and identity, Excalidraw for drawings.

  • Quick capture from a phone that never waits on an LLM.

  • Originals are always kept; what is derived from them can be regenerated (a saved link’s article only while its source is online).

  • Human and model content kept apart: model output is derived, labelled and regenerable, and write-ups are refreshed when you choose.

What Claude adds#

Snap a whiteboard, jot a note or share a link; scrap keeps the original at once, and Claude adds:

  • a reading of each photo: a description, the text on it, and a drawing;

  • a write-up of each whiteboard and diagram;

  • tags and a summary;

  • related pages;

  • topic pages that draw your pages together.

Store health checks then find orphans, dangling links and outdated write-ups.

Claude searches, reads and adds pages over MCP; the PWA is for capturing and looking. See what Claude is asked, per page.

Try it#

printf 'Anthropic API key (Enter to skip): '; read -rs ANTHROPIC_API_KEY; export ANTHROPIC_API_KEY
podman run -d --name scrap --network=host -v scrap-data:/data \
  -e SCRAP_INGEST=${ANTHROPIC_API_KEY:+on} -e ANTHROPIC_API_KEY \
  ghcr.io/gilesknap/scrap:latest serve

Open http://localhost:8000/; podman logs -f scrap to watch it, podman rm -f scrap to stop it (the data stays in the scrap-data volume).

The key is optional: it lets Claude read your photos and tag your notes. Then add scrap to Claude Code and install the sc commands and skill:

claude mcp add --transport http --scope user scrap http://localhost:8000/mcp
curl -fsSL https://github.com/gilesknap/scrap/releases/latest/download/install.sh | sh

Start a new Claude Code session, save a note in the browser, then try

/sc-find <word>

or

search scrap for ...

Connect your phone for quick capture. See use scrap on your phone over Tailscale.

Claude Code in a sandbox? See connecting Claude Code in claude-sandbox.

More: connect Claude Code and the sc commands, MCP reference.

What works today#

  • Capture, with no LLM. Notes, links, photos and files become pages you can list, edit, search, trash, back up and export, from a phone-first PWA with an offline queue and an Android share target. Saving never waits on Claude.

  • Claude reading, opt-in. With SCRAP_INGEST=on and an ANTHROPIC_API_KEY, a background worker sends photos to the Claude Messages API for their text, a description, a kind, tags and an Excalidraw redrawing, and tags, summarises and links text pages. It is off by default, it costs money, and a daily budget (SCRAP_BUDGET_DAY_USD, default 3) pauses the queue when it is spent. See Claude ingest and the settings.

  • Claude over MCP. A Claude Code session can search, read, write, edit, retag and trash pages and redraw a drawing, and undo each change: see Connect a Claude Code session and MCP server.

  • Your data stays yours. The store is one SQLite database and a folder of files. scrap backup and scrap restore copy it, scrap export writes Markdown, scrap import reads it back (or an Obsidian vault), and scrap gc finds files nothing uses and purges the trash (after 30 days by default).

Search is full-text only (SQLite FTS5); semantic search was deferred, see 8. Search is SQLite FTS5 with a shared query syntax; embeddings are deferred. scrap has no login code of its own: access is the network (Tailscale) or an authenticating proxy (Cloudflare Access), with an optional bearer token on /mcp (23. Bearer token on /mcp and an identity-header setting). Never expose it on a public address without one of them.

Choose your install#

scrap is not published on PyPI (the scrap package there is an unrelated project); you run the container image. Each tutorial is one short path from nothing to a running scrap.

What

Where

Source

gilesknap/scrap

Container image

ghcr.io/gilesknap/scrap (arm64 and amd64)

Releases

gilesknap/scrap
Try it on your LAN

One container on a laptop, Pi or home PC, reached from your phone over the LAN or Tailscale. No login, no systemd. The quickest way to try it.

Try scrap on your LAN
One server with Tailscale

A hardened single VPS or home server: dedicated user, Unix socket, systemd and Tailscale Serve for HTTPS. Claude Code on the same box.

Install on a server with Tailscale
Kubernetes with Cloudflare

The Helm chart behind a cloudflared tunnel and Cloudflare Access, with a bearer token on /mcp.

Install scrap on Kubernetes

To read photos with a Claude subscription instead of an API key, add Ingest on a Claude seat instead of an API key to any of them.

How the documentation is structured#

Documentation is split into four categories, also accessible from links in the top bar.

Three install tutorials, from a quick LAN try-out to Kubernetes, and one for ingest on a Claude seat. New users start here.

Practical step-by-step guides for the more experienced user.

Architecture in diagrams (data, capture, Claude jobs, search, MCP, PWA, deployment), the stack, UI design system, and the decision records.

Technical reference material: the HTTP API, CLI and settings, the MCP tools, and release notes.