---
name: vault
description: Read and write notes in ginnoir's self-hosted Obsidian vault (CouchDB obsidian-livesync backend at obsidian.ginnoir.com). Use when loading persistent context for a session, saving new context, writing a note, or querying vault contents. The vault is the canonical persistent-context store across Claude sessions.
---

# vault

Obsidian vault backed by CouchDB (obsidian-livesync) at `obsidian.ginnoir.com`.

## Credentials

```
Endpoint : https://obsidian.ginnoir.com
DB       : obsidian
User     : admin
Password : couchdb_obs_p4ss_7x9k   (also in stacks/notes/stack.env)
```

## Document format

Each note is a CouchDB document:

| Field  | Meaning |
|--------|---------|
| `_id`  | Vault-relative path, e.g. `claude/Context.md` or `Projects/homelab.md` |
| `data` | Raw markdown content |
| `type` | `"plain"` for regular notes |
| `ctime`/`mtime` | Unix ms timestamps |
| `size` | Byte length of `data` |

Slashes in `_id` must be URL-encoded as `%2F` in requests.

## Read all notes

```powershell
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/_all_docs?include_docs=true"'
```

Returns JSON with `rows[].doc.data` = markdown for each note.

## Read one note

```powershell
# e.g. claude/Context.md
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"'
```

## Write / update a note

Shell escaping inside SSH is treacherous with JSON. The reliable pattern is:

1. Write JSON to `/tmp/note.json` on valhalla
2. `docker cp` it into the container
3. `curl -d @/tmp/note.json` from inside the container

```powershell
# Step 1 — get current _rev
$rev = (ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"' | python -c "import sys,json; print(json.load(sys.stdin)['_rev'])")

# Step 2 — write JSON to valhalla /tmp
$json = @{_rev=$rev; data="# My Note`n`nContent"; type="plain"; ctime=0; mtime=0; size=10} | ConvertTo-Json
$json | ssh ginnoir@valhalla "cat > /tmp/note.json"

# Step 3 — copy to container and PUT
ssh -o BatchMode=yes ginnoir@valhalla '
  docker cp /tmp/note.json couchdb:/tmp/note.json
  docker exec couchdb curl -sf -X PUT \
    "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md" \
    -H "Content-Type: application/json" -d @/tmp/note.json
'
```

## Load context at session start

```powershell
ssh -o BatchMode=yes ginnoir@valhalla 'docker exec couchdb curl -sf "http://admin:couchdb_obs_p4ss_7x9k@localhost:5984/obsidian/claude%2FContext.md"' | python3 -c "import sys,json; print(json.load(sys.stdin)['data'])"
```

## Key notes

| Path | Purpose |
|------|---------|
| `claude/Context.md` | Claude's persistent context: ongoing projects, preferences, session notes |
| `Home.md` | Vault index / root |

## Notes on valhalla Python

Running `python3` on the valhalla *host* cannot resolve `localhost` (DNS issue in SSH env). Always use `docker exec couchdb curl` (CouchDB's own container) to hit the API — it resolves localhost fine internally.