Working with files
Your notes can live as plain markdown on your own disk. Sync moves them into your graph — and you decide which side is the source of truth.
Why keep a vault at all
A vault is a folder of markdown files. One file per node, one subfolder per lens, and a _lens.md that declares the taxonomy. That is the whole format — no database to install, nothing proprietary.
The filename is the slug. wg-nixon.md is the node wg-nixon, which is why the vault lane never has the slug problem the paste lane does — there is nowhere for the name to be invented.
The point is that it survives us. You can read a vault in any text editor, grep it, put it in git, or open it in another tool entirely. An export button that produces JSON is a promise; a folder you already have is a fact.
Get the tool
Sync runs on your machine, not on our servers, so there is something to install. You need Node and a terminal.
git clone https://github.com/jdejonge206/Nodemancy-Public.git cd Nodemancy-Public/backend npm install
Then create backend/.env with three lines. The anon key is public — it is the same key this website ships to your browser — and you can copy it from your project settings.
SUPABASE_URL=https://YOUR-PROJECT.supabase.co SUPABASE_ANON_KEY=your-anon-public-key LEXICON_DIR=/absolute/path/to/your/lexicon
npx command; until then, the four steps above are the honest cost and we would rather say so than describe a shortcut that does not exist.Sign in, once
The first sync asks for your email and a one-time code we send you. There is no password to store, and it works the same whether you signed up with a password or with Google.
$ npm run sync email: you@example.com · code sent to you@example.com code: 123456 · mode: user (you@example.com)
After that it stays signed in. The session is kept in ~/.nodemancy/session.json, readable only by you, and deliberately outside the project folder — so copying or sharing the folder never carries your credentials with it. Delete that file to sign out.
The four commands
All of them run from backend/, and all of them work on the one vault named by LEXICON_DIR.
npm run check # what would change, and in which direction — writes nothing npm run sync # push: vault → graph npm run pull # pull: graph → vault, as markdown files npm run sync:watch # push on every save
Start with check. It prints a drift report — what is in sync, what is new locally, what changed in the app since you last synced — and it never writes anything, so there is no way to get it wrong.
sync:watch is the one to leave running while you write. It pushes on every save, which means the graph is never more than a keystroke behind the file you are editing — and it only ever pushes, so it cannot surprise you by pulling something down mid-sentence.
What goes in a node file
Frontmatter, then prose. Only the keys below are read; anything else you write is passed through untouched, which is the vault lane's covenant and the main way it differs from pasting.
--- title: "Sam Dash" group: congress kind: person --- # Sam Dash **Definition.** Chief counsel to the Senate Watergate Committee, who led the questioning that drew out Dean's and Butterfield's testimony. **See also.** [[wg-ervin-committee|Senate Watergate Committee]], [[wg-the-tapes::investigated|The White House Tapes]]
No slug: — the filename already said it. The full key list, the link syntax and the normalisation rules are in the paste format, which describes the same markdown from the other lane's side.
synced_hash yourself, and strip it if you copy a node from another vault. It is sync's own bookkeeping: a node that carries one is a node sync believes it has already pushed, so it will skip the file silently and forever. Nothing is reported, because from the tool's side nothing is wrong.What goes in _lens.md
The lens's own vocabulary — the thing that makes it a lens rather than a folder. Three sections, each a list of |-separated fields:
--- title: Watergate authority: vault --- ## Families <!-- key | Label | #color --> - investigators | The Investigators | #2dcca0 ## Groups <!-- key | Label | #color | familyKey --> - congress | Congress | #2dd4c8 | investigators ## Relations <!-- value | Label | directed|symmetric | #color --> - investigated | Investigated | directed | #3ea6ff
## Facet: block with meaningful row order — nothing reads it. Write one and it is inert: no error, no effect. Kinds and other facets come from what your entries actually use, never from a declaration.Which side wins
Every lens carries an authority: either the app or the vault. It is the answer to “if these two disagree, which one is right?” and you set it per lens in lens settings, or with the authority: line above.
| Authority | What it means |
|---|---|
vault | Your files win. Edit _lens.md, run sync, and the app takes the change — including the palette and the relation list. Edits made in the app to those fields are replaced on the next sync, which is the point rather than a bug. |
web | The app wins, and the lens has no vault copy unless you pull one. Lenses you create in the browser start this way, and hand-authoring a file for one is wasted work — the sync will ignore it. |
No _lens.md at all means web by default.
check lists them by name so you can decide. Nothing is destroyed while you make up your mind.What sync does not carry
The vault is the human artifact, and a markdown file has nowhere sensible to put an SM-2 interval or a per-lens grant. So sync moves text and taxonomy, and leaves the rest in your account:
- Attachments — the files themselves stay in the app.
- Flashcards and review history — account data, not content.
- Themes, handles, friendships, sharing grants — likewise.
- Graph layout — never anywhere but your own browser.
If you want everything, including the parts sync leaves behind, use Download everything in your account menu's Data section. It hands you one .zip holding the same vault tree, a data.json with every row verbatim, and your uploaded files — so the archive is complete twice over, readable as prose and exact as data. Getting your data out covers it.
A note on backups
A vault is a genuinely good backup — it is plain text on your own disk, and npm run pull refreshes it whenever you like. But it is a backup of your notes, not of your account. If that distinction matters to you, take an export as well; it is one click and no setup.
Next
- The paste format — the same markdown, pasted straight into the app when you would rather not use a terminal at all.
- Getting your data out, and deleting it — the archive, and the one action here that cannot be undone.