ashfulcra fulcra-vault
The vault is the user's durable prose memory, stored as ordinary markdown in their Fulcra account: projects, people, decisions, corrections, domain notes, and the links between them. Your job: LOAD what's hot at session start, READ the relevant notes, and WRITE durable context back as you learn it.
HOT.md is the compact session-start summary; MAP.md is the full index;
each note carries flat frontmatter, agent-owned sections, and an append-only
## Log.
Where to start — the re-entrancy probes
Before loading anything, probe how far this user already got. Enter at the first row whose probe fails:
| Probe (run in order) | Command | Passes when | If it fails, enter at |
|---|---|---|---|
| Authed? | fulcra user-info |
exits 0 and prints valid JSON | Pick your path — install, then fulcra auth login |
| Vault initialized? | fulcra-vault map --check |
exits 0 (MAP/HOT render check passed); exit 2 naming /vault/meta.json means no vault yet |
Onboarding a new user — fulcra-vault init |
| Content present? | fulcra-vault read HOT |
non-empty stdout (HOT.md renders notes) | Pick your path tier-1 write — vault is empty; start writing durable context |
| Hooks installed? | grep -q fulcra-vault-hooks ~/.claude/settings.json (or ~/.codex/hooks.json; custom --target-dir installs won't match this grep) |
exits 0 — SessionStart injects HOT.md |
Onboarding a new user — fulcra-vault install-hooks --platform <claude-code|codex> |
First failure wins. Hooks are optional: without them you just read HOT
yourself; everything else works the same. All four pass → HOT.md is auto-injected
at session start; read the relevant notes and write durable context back as you learn it.
Pick your path
- You can run shell commands → use the CLI. Setup once:
uv tool install "git+https://github.com/ashfulcra/fulcra-tools.git#subdirectory=packages/fulcra-vault"(andfulcra auth loginif not authed).- Load: if the SessionStart hook is installed,
HOT.mdis already in your context. Otherwisefulcra-vault read HOTand read it. Empty output = no vault yet; see onboarding. - Read a note:
fulcra-vault read "<note>"(add--with-backlinksto see what links to it). - Find related notes:
fulcra-vault backlinks "<note>", orfulcra-vault map --checkto render the index without writing. - Write durable context:
fulcra-vault write-section "<note>" --section <slug> --agent <you>(body on stdin). This replaces only your owned section, never the rest of the note. See references/fulcra-vault-write.md. - Log a decision/correction:
fulcra-vault append-log "<note>" --entry "<text>" --agent <you>— append-only, never rewrites history. - After writes:
fulcra-vault reindexthenfulcra-vault mapto refresh the link index and MAP/HOT.
- Load: if the SessionStart hook is installed,
- You can make HTTP requests but not run commands → follow references/fulcra-vault-tier2-http.md (device-flow auth + the Fulcra Files API).
- You only have the Fulcra MCP → you can read user data the MCP exposes, but the vault's read/write surface is not available via MCP today. Ask the user to run onboarding from a CLI-capable agent.
Onboarding a new user
If read HOT reports not onboarded: run fulcra-vault init (requires
fulcra auth login first). That scaffolds meta.json, MAP.md, HOT.md,
LOG.md, and seed notes from a default structure (projects, people, decisions,
domain). Pass --spec <file> to supply your own StructureSpec.
To get HOT.md injected at the top of every session automatically:
fulcra-vault install-hooks --platform <claude-code|codex>.
Rules
- The markdown is the source of truth;
MAP.md/HOT.md/.index/are derived and rebuildable withreindex/map. - Edit only your owned section of a note; the shared
## Logis append-only. - Link notes with
[[wikilinks]]so they show up in backlinks and the map. - Excluded paths in
meta.jsonrefuse writes — respect them. - NEVER print or store the user's access token.