git:20260709.f2fff26 to git:20260709.e71d1e0

1 added, 1 removed. Audit A to A.

---

name: fulcra-vault

description: "Read and write the user's shared markdown knowledge vault in Fulcra — durable prose memory for projects, people, decisions, and domain notes, linked with [[wikilinks]]. Routes by agent capability: CLI (preferred), raw HTTP, or MCP read-only."

homepage: "https://github.com/ashfulcra/fulcra-tools/tree/main/packages/fulcra-vault"

license: "MIT"

user-invocable: true

metadata: { "openclaw": { "emoji": "📓" } }

---

# 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**:

|---|---|---|---|

| 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 <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

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 "<note>"` (add `--with-backlinks` to see

what links to it).

- Find related notes: `fulcra-vault backlinks "<note>"`, or

`fulcra-vault map --check` to 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 reindex` then `fulcra-vault map` to refresh the

link index and MAP/HOT.

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

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

API).

3. **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 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.