grok-bot-obsidian

Folder-first Obsidian access for Grok Bot: local Markdown vault as durable ops truth. Obsidian UI optional. Local REST API not required.

Not a second always-on HQ agent stack.
Not a cloud dump of your notes.
A local-computer + Markdown source-of-truth pattern you can copy.

Built from a live multi-agent HQ setup (Aug 2026): Hermes ops agent + Grok Bot teammate sharing one human-readable Command Vault.

Why this exists

Problem	Reality
Chat memory is not durable	Sessions rot; decisions vanish
Cloud-only agent computers ≠ your vault	Grok Bot’s default workspace is a cloud computer at /workspace
Local Mac files need explicit permission	Local exec is separate: Settings → General → Agent → Execution on Local Computer
Agents invent structure	Without a bootstrap note, every Bot rebuilds a different “memory system”
Scratch gets mistaken for the ledger	Grok home / /workspace scratch ≠ ops vault (split-sot.md)

Obsidian is just a folder of Markdown. That makes it the best inspectable ops ledger for humans + agents: open it in the app, cat it in a terminal, diff it in git if you want.

Access modes

Mode	Required?	Notes
Folder / filesystem via Grok local-exec	Primary	VAULT_PATH + read/write Markdown
Obsidian desktop UI	Optional	Nice for humans
Obsidian CLI	Optional	obsidian vault checks
Local REST API plugin	Optional	localhost + key in env — local-rest-api.md

What you get

• Plain-English model: vault = durable truth; chat = control surface
• macOS local-computer setup for Grok Bot.app (local-exec daemon)
• Stable vault path pattern (symlink without spaces)
• Split-SoT labels (ops vault vs Grok scratch vs session logs)
• Copy-paste vault templates/ (00 - READ FIRST, command center, projects, decisions, handoffs)
• Security rules: no tokens in notes, fail-closed habits
• Smoke scripts to verify read access without printing private note bodies
• .env.example path placeholders only

Quick start

1) Put your vault somewhere the Mac user can read

Example:

~/Notes/My Command Vault/

Open it once in Obsidian desktop so the app knows the vault.

2) Make a stable agent path (recommended)

mkdir -p "$HOME/Vaults"
ln -sfn "$HOME/Notes/My Command Vault" "$HOME/Vaults/command-vault"
ls -la "$HOME/Vaults/command-vault"

Or:

./scripts/link-vault.sh "$HOME/Notes/My Command Vault"

Spaces in the real folder name are fine; agents should prefer the symlink.

3) Enable Grok Bot local computer execution

In Grok Bot.app:

1. Settings → General → Agent → Execution on Local Computer
2. Start with Ask every time (safest) or carefully scoped Always allow rules later
3. Confirm the app is running and the local-exec daemon is healthy
   (on macOS you should see a local-exec-daemon child under Grok Bot)

Official docs:

• Use the computer and apps — cloud computer vs local computer
• Approvals, security, and privacy — local execution policy

4) Drop the bootstrap templates into your vault

cp templates/*.md "/path/to/your/vault/"
# or merge selectively — do not overwrite your real notes blindly

Edit names/paths. Keep secrets out.

5) First task to give your Bot

You have LOCAL computer access on this Mac (not only the cloud /workspace).

Vault (stable path):
  ~/Vaults/command-vault

1) List top-level files and folders.
2) Read ONLY: 00 - READ FIRST - Agent Bootstrap.md
3) Summarize in plain English:
   - what the vault is
   - memory stack (what goes where)
   - capture commands
   - safety gates
4) Do NOT open finance, credentials, customer PII, or .env files.
5) Do NOT modify notes until I say "vault this" or explicitly ask for a write.
6) Grok /workspace scratch is NOT the ops vault.

6) Verify from a normal shell (operator check)

./scripts/verify-local-access.sh ~/Vaults/command-vault
./scripts/smoke-read-vault.sh ~/Vaults/command-vault

These scripts only print structure + bootstrap headings — not private note bodies.

Mental model (print this on the wall)

Obsidian vault     = durable, human-readable source of truth
Chat / Discord     = control surface (not the archive)
Agent session DB   = transcript evidence
Tiny always-on mem = preferences only
Grok scratch       = /workspace + Grok home — NOT the ops vault
Secrets            = env/keychain — NEVER the vault

Core rule: If it should matter next week, promote it to the vault.

Repo map

Path	Purpose
docs/why-obsidian-for-agents.md	Why Markdown beats hidden memory
docs/local-computer-access.md	Grok Bot local exec + macOS notes
docs/local-rest-api.md	Optional REST plugin (not required)
docs/split-sot.md	Ops vault vs logs vs Grok scratch
docs/vault-layout.md	Folder conventions that scale
docs/security.md	What never goes in notes
docs/multi-agent.md	Hermes / peer bots coexistence pointers
templates/	Bootstrap + ops skeleton notes (fake/empty)
scripts/	link-vault / verify-local-access / smoke-read-vault
examples/first-bot-prompt.md	Copy-paste onboarding prompt
.env.example	VAULT_PATH / OBSIDIAN_VAULT_PATH placeholders

Public-safe checklist

• no real private vault path required in git
• no API keys
• no real note bodies
• Grok scratch memory labeled as not the ops vault
• .env and local Obsidian workspace noise gitignored
• templates are empty/fake hubs only

Related

• Discord multi-agent bridge (online presence + @ wake for Grok Bot identities):
  https://github.com/davefmurray/grok-bot-discord
• Obsidian: https://obsidian.md
• Grok Bot docs: https://docs.x.ai/grok-bot/overview

What this is not

• Not an Obsidian plugin
• Not a hosted sync service
• Not permission to scrape your whole home folder
• Not a replacement for backups
• Not legal/compliance advice

License

MIT — see LICENSE.

Security

See SECURITY.md. Report token leaks; do not open issues that paste secrets.