How it works — detail
Margins is a Node process that connects Claude Desktop to a folder on your disk. You drop documents into the folder, ask Claude questions, and let Claude build a wiki underneath your originals as you go. The originals never move. The wiki grows file by file, each one accepted by you.
A Margins vault is just a regular folder on your disk. After install and a few compiles, it has this shape. The originals you dropped in stay where you put them. Everything in wiki/ is generated by Claude through Margins, one accepted proposal at a time.
Filesystem is truth. Frontmatter is the contract between source pages and the originals they describe. Margins is a local Node process that reads, suggests, and writes — but every write is staged in proposed/ first. You approve. Then it lands.
When you talk to Claude in Claude Desktop, Claude has tools that read and write to your vault. Here is what happens when you say "compile this PDF" or "what did I learn from those meetings?"
raw/"margins_start runs on every new conversation. Returns vault stats, unprocessed file count, and recent preferences.list_unprocessed returns the PDF you just dropped.read_page on the PDF. Margins extracts text from the binary.propose_compile_from_raw with the path and a summary Claude generates.resolve_proposal with action=accept after your approval.proposed/wiki/sources/...proposed/ into the vault. Append a row to ingest-tracker.md.The magic isn't the source pages themselves. It's that as multiple source pages accumulate, the same names and ideas start to recur. Margins surfaces those patterns. You accept proposals to build entity and concept pages. Those pages become hubs. Connections compound.
Claude has 17 tools in Margins. You never call them directly. You ask Claude things in plain language and Claude picks the right tool. Useful to know what's available so you can ask for it.
| Tool | What you'd ask Claude | What it does |
|---|---|---|
| Read the vault | ||
margins_start | "What's in my vault?" | Called automatically at the start of every conversation. Returns folder stats, unprocessed files, recent preferences, and a vault primer. |
search_vault | "Find the thing I wrote about X" | Full-text and filename search across the entire vault, including binaries via text extraction. |
read_page | "Read the strategy doc" | Pulls one file by path. Extracts text from PDFs, DOCX, and more. |
get_backlinks | "Who mentioned this person?" | Finds every page that wiki-links to a given slug. |
list_recent | "What did I update yesterday?" | Most recently modified files. |
list_unprocessed | "What haven't I filed yet?" | Files in your vault that don't have a source page yet. |
| Build the wiki — propose, then accept | ||
propose_compile_from_raw | "File this PDF as a source" | Reads a file, runs the compiler, stages a structured source page. Idempotent — won't double-stage. |
propose_page | "Draft an entity page for this person" | Stages a new wiki page at the path you choose. |
propose_edit | "Add this fact to that page" | Stages a string-replacement edit on an existing page. |
append_to | "Append this to today's daily note" | Stages an append. Creates the page if it doesn't exist. |
propose_wikilinks | "Link this page to everything it mentions" | Suggests wiki-link additions where plain text matches existing pages. |
| Review staged changes | ||
list_proposals | "Show me what's pending" | Lists every staged proposal with destination path and size. |
resolve_proposal | "Accept that one" | Accept moves the proposal into the live vault and auto-appends a tracker row. Reject deletes it. |
| Preferences and onboarding | ||
record_preference | "Always file my meetings as projects" | Stores a one-line rule Margins re-reads at the start of every conversation. |
recall_preferences | (used by Claude automatically) | Returns your stored preferences so proposals follow them. |
record_telemetry_consent | (asked once at install) | Records whether you want to share anonymous usage data. |
The wiki doesn't appear at install. It grows file by file as you accept proposals. Compounding kicks in around the time you have ~15 source pages and the first entity hubs start naming patterns Claude can see across them.
Point Margins at your folder. Open Claude Desktop. Ask questions about your files. Claude reads and quotes from them. No structure required yet.
Claude offers to file the most substantive files. You accept the first batch one at a time. Each accept adds a structured source page and updates the tracker.
Recurring names start showing up across 3+ sources. Claude proposes entity pages for the load-bearing ones. You accept what matters. Concepts follow the same path.
"What do I know about this topic?" returns the entity page and its source log instead of re-reading raw files. New sources auto-link to existing entities.
proposed/. Nothing lands in your vault until you say accept.raw/ for unprocessed files. Set MARGINS_INGEST_ROOTS to include other folders if you want the inbox spread across your vault.