Fulcra Vault

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](#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](#onboarding-a-new-user) — fulcra-vault init | | Content present? | fulcra-vault read HOT | non-empty stdout (HOT.md renders notes) | [Pick your path](#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](#onboarding-a-new-user) — fulcra-vault install-hooks --platform |

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

1. 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" (and fulcra auth login if not authed).

• Load: if the SessionStart hook is installed, HOT.md is already in your

context. Otherwise fulcra-vault read HOT and read it. Empty output = no vault yet; see onboarding.

• Read a note: fulcra-vault read "" (add --with-backlinks to see

what links to it).

• Find related notes: fulcra-vault backlinks "", or

fulcra-vault map --check to render the index without writing.

• Write durable context: `fulcra-vault write-section "" --section

--agent ` (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 "" --entry

"" --agent ` — append-only, never rewrites history.

• After writes: fulcra-vault reindex then fulcra-vault map to refresh the

link index and MAP/HOT.

1. You can make HTTP requests but not run commands → follow

references/fulcra-vault-tier2-http.md (device-flow auth + the Fulcra Files API).

1. 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 to supply your own StructureSpec.

To get HOT.md injected at the top of every session automatically: fulcra-vault install-hooks --platform .

Rules

• The markdown is the source of truth; MAP.md/HOT.md/.index/ are derived

and rebuildable with reindex/map.

• Edit only your owned section of a note; the shared ## Log is append-only.
• Link notes with [[wikilinks]] so they show up in backlinks and the map.
• Excluded paths in meta.json refuse writes — respect them.
• NEVER print or store the user's access token.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ashfulcra
• Source: ashfulcra/fulcra-tools
• License: MIT
• Homepage: https://fulcradynamics.com

Install and usage instructions live in the source repository linked above.