Rewrite as user-agnostic "quicksilver" plugin

Rename echo-memory/ECHO -> quicksilver/Quicksilver throughout and make the
plugin self-configuring per operator:

- First-run flow: prompt for endpoint FQDN, API key, and operator name/role;
  verify; persist to a local config file (~/.quicksilver/quicksilver-config.json).
- Two-layer setup detection: local config (is this install configured?) +
  in-vault marker (is the vault scaffolded?). Key never stored in the vault.
- Replace hardcoded endpoint/key in all curl examples with $BASE/$AUTH loaded
  from the config file.
- Genericize all "Jason"/"Bryan goldbrain"/MPM/wISP references to "the operator";
  keep Jason as architect credit (README + plugin.json author).
- Personalize memory to the configured operator (name/role seeded into
  operator-preferences and the vault marker).
- Add echo-vault.md -> quicksilver-vault.md rename migration.
- Rebuild packaged quicksilver.plugin; add docs/quicksilver-plan.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
jason
2026-06-07 08:06:51 -05:00
parent 3ba73b2d48
commit d90abde29e
25 changed files with 400 additions and 167 deletions
+140
View File
@@ -0,0 +1,140 @@
# Quicksilver — user-agnostic rewrite + rename plan
## Objective
Turn the plugin (formerly `echo-memory` / "ECHO") into one a coworker can install
cold. On first run it detects it's freshly installed, prompts for the **API endpoint
FQDN**, **API key**, and **operator name/role**, verifies them, persists them to a
**local bootstrap indicator file**, then bootstraps the vault and personalizes memory
to that operator. The system is renamed to **Quicksilver** throughout. Jason stays
credited only as the architect.
## Locked decisions
1. **Credentials** → a dedicated **local bootstrap indicator file** (client-side) holds
FQDN + API key. The in-vault marker stays a pure schema/version flag (no secret).
2. **Operator identity** → prompt for name/role at first run; personalize memory
("Alex prefers X"); seed `operator-preferences.md` + the marker with it.
3. **Attribution** → Jason kept in `plugin.json` `author` + a one-line
"Architecture by Jason Stedwell" credit in the README. Every other operational
mention removed.
4. **Name** → full rename `echo-memory` / `ECHO``quicksilver` / `Quicksilver`
(0 "echo" hits after the pass).
## Core design: two-layer "is this set up?" detection
| Layer | File | Question | Holds |
|---|---|---|---|
| 1. Local indicator (new) | `~/.quicksilver/quicksilver-config.json` (client-side) | "Is *this install* configured?" | FQDN + **API key** + operator name/role |
| 2. Vault marker (existing) | `_agent/quicksilver-vault.md` (in vault) | "Is the *vault* scaffolded?" | schema_version, bootstrap date, operator name — **never the key** |
The secret lives client-side (you need it *before* you can reach the vault, and the
plugin's own safety rule forbids keys in vault notes). The vault marker stays a pure
schema flag. The local indicator file *is* the "freshly installed?" signal — its
absence triggers first-run.
### Local indicator file spec
Path: `~/.quicksilver/quicksilver-config.json` (Windows:
`%USERPROFILE%\.quicksilver\quicksilver-config.json`). Lives in the user home, **not**
the plugin dir, so it survives plugin reinstalls/updates.
```json
{
"schema": 1,
"endpoint": "https://<operator-fqdn>",
"api_key": "<bearer-token>",
"operator": { "name": "Alex Rivera", "role": "Network Engineer" },
"configured_at": "2026-06-07",
"verified_at": "2026-06-07"
}
```
The skill reads this with the Read tool at session start and substitutes
`endpoint``$BASE` and `api_key`→bearer into all curl calls. **No `jq` dependency**
the agent parses the JSON itself, portable across Windows/Mac/Linux shells.
## First-run / session-start algorithm (new Step 0)
1. **Check local indicator** (`~/.quicksilver/quicksilver-config.json`).
- **Absent → FRESH INSTALL.** Tell the operator this looks like a first run and
prompt for: (a) endpoint FQDN, (b) API key, (c) name + role. Verify by probing
`GET $BASE/vault/_agent/quicksilver-vault.md` (200/404 = reachable+authorized;
connection error/401 = re-prompt). Write the indicator file (`chmod 600`).
- **Present →** load `endpoint`, `api_key`, `operator`; continue.
2. **Probe vault marker** `_agent/quicksilver-vault.md` with the known creds.
- **404 →** fresh bootstrap (scaffold), seeding `operator-preferences.md`
`## Operator` with the provided name/role, and writing the marker with
`operator:` set (no key).
- **200 →** check `schema_version`, migrate if stale, proceed to normal loading.
## File-by-file changes (genericize + rename in one pass)
- **`.claude-plugin/plugin.json`** — `name`/`description`/`keywords` → quicksilver;
drop "Jason's personal memory vault"; **keep** `author: Jason Stedwell`; bump
`0.5.0``0.6.0`.
- **`README.md`** — title `# quicksilver`; operator-agnostic intro + one line
"Architecture by Jason Stedwell."; rewrite **Configuration** (no hardcoded
server/key; document first-run flow + indicator file); remove "not for
distribution"; ECHO → Quicksilver.
- **`skills/quicksilver/SKILL.md`** — frontmatter `name: quicksilver`, genericize
`description` (strip Jason / Bryan's goldbrain / MPM / wISP; ECHO → Quicksilver);
replace hardcoded `OBSIDIAN_BASE`/`OBSIDIAN_KEY` block with "load from indicator
file"; delete the `echoapi.alwisp.com`-only / retired-`obsidian-memory` paragraph;
rewrite operator-identity paragraph to read identity dynamically; every curl
`Bearer 2412…``$AUTH`, `https://echoapi.alwisp.com``$BASE`; remove goldbrain/Bryan
cross-write rule; "Jason" → "the operator"; add Step 0 to loading; marker path →
`quicksilver-vault.md`.
- **`references/api-reference.md`** — server/key header lines and every curl →
`$BASE`/`$AUTH`; example prose genericized; marker path.
- **`references/bootstrap.md`** — replace hardcoded `AUTH`/`BASE` with load-from-
indicator preamble; add **Step 0: Client configuration (first run)**; seed
`## Operator` from provided name; marker stores operator + schema only; add the
`echo-vault.md``quicksilver-vault.md` rename migration.
- **`references/vault-layout.md`** — genericize operator-preferences + people example
(`<operator-name>.md`); marker path; ECHO → Quicksilver.
- **`references/operating-contract.md`** — confirm operator-agnostic; ECHO →
Quicksilver.
- **`references/session-log-template.md`** — update illustrative key/decision lines;
example slugs `echo-*``quicksilver-*`.
- **`scaffold/quicksilver-vault.md`** (was `echo-vault.md`) — "Quicksilver Vault
Marker"; add `operator:` frontmatter; `managed_by: quicksilver-plugin`; explicit
"no key here".
- **`scaffold/README.vault.md`** — "Quicksilver Memory Vault"; ECHO → Quicksilver.
- **`scaffold/anchors/operator-preferences.seed.md`** — add `{{OPERATOR}}`/`{{ROLE}}`
substitution tokens for `## Operator`.
- **`scaffold/anchors/inbox.seed.md`** — "quicksilver skill".
## Path / file renames (git mv)
- `echo-memory.plugin.src/``quicksilver.plugin.src/`
- `…/skills/echo-memory/``…/skills/quicksilver/`
- `…/scaffold/echo-vault.md``…/scaffold/quicksilver-vault.md`
- `echo-memory.plugin` (packaged artifact) → rebuilt/renamed `quicksilver.plugin`
## Migration impact (Jason's existing vault)
The marker rename means Jason's current vault has the marker at the old path. Fold into
the schema migration: on probe, if `quicksilver-vault.md` is 404 **but**
`echo-vault.md` is 200, treat as a rename migration — PUT the new marker, DELETE the
old, scrub stale `[[echo-vault]]` links. New coworker vaults are fresh and hit the
clean path.
## Security / hygiene
- **Rotate the live key.** `241265fbe…` is committed in plaintext and in git history.
Even after genericizing, history retains it — rotate it on the backend.
- Indicator file holds a secret → write `0600`; it lives in `$HOME`, outside the repo.
## Validation
- **Grep gate:** `grep -ri "echo"` → 0 hits; `grep -ri "jason\|alwisp\|241265\|goldbrain\|bryan"` → only README architect credit + plugin.json author.
- **Fresh install:** no indicator + empty vault → prompts for FQDN/key/name, file
written, vault scaffolded, `## Operator` seeded.
- **Returning user:** indicator + marker present → loads silently, no prompts.
- **Reinstall:** plugin reinstalled, indicator persists in `$HOME` → no re-prompt.
- **Bad endpoint at first run:** unreachable/401 → graceful re-prompt, nothing written.
## Out of scope (v1)
Multiple operators / multiple vaults per machine (single indicator file assumed).
Binary file not shown.
@@ -1,15 +0,0 @@
{
"name": "echo-memory",
"version": "0.5.0",
"description": "Persistent memory via the ECHO Obsidian vault over the Local REST API. Self-bootstrapping: the plugin carries the full vault scaffold and all control logic (no in-vault routing docs), so it stands up an empty vault and ports cleanly to any other. Reads and writes notes across Claude/CoWork sessions using direct REST calls \u2014 no MCP server required. Jason's personal memory vault.",
"author": {
"name": "Jason"
},
"keywords": [
"memory",
"obsidian",
"notes",
"persistence",
"echo"
]
}
Binary file not shown.
@@ -0,0 +1,15 @@
{
"name": "quicksilver",
"version": "0.6.0",
"description": "Persistent memory via a Quicksilver Obsidian vault over the Local REST API. Self-bootstrapping: the plugin carries the full vault scaffold and all control logic (no in-vault routing docs), so it stands up an empty vault and ports cleanly to any other. On first run it prompts the operator for the API endpoint, key, and identity, stores them in a local config file, and personalizes memory to that operator. Reads and writes notes across Claude/CoWork sessions using direct REST calls — no MCP server required.",
"author": {
"name": "Jason Stedwell"
},
"keywords": [
"memory",
"obsidian",
"notes",
"persistence",
"quicksilver"
]
}
@@ -1,26 +1,49 @@
# echo-memory # quicksilver
Persistent memory for Claude via the **ECHO** Obsidian vault, using the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api). Persistent memory for Claude via a **Quicksilver** Obsidian vault, using the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api).
Reads and writes notes across Claude/CoWork sessions using direct REST calls — no MCP server required. Built for **Jason Stedwell** (Director of Technical Services / Systems Engineer, MPM / ALABAMA wISP), who is both the operator and the architect of this vault. Reads and writes notes across Claude/CoWork sessions using direct REST calls — no MCP server required. The plugin is operator-agnostic: each install is configured at first run for its own vault and operator.
**The plugin is the single source of truth.** All control logic — bootstrap/repair, operating contract, taxonomy, frontmatter conventions, and the canonical note templates — ships inside this plugin under `skills/echo-memory/`. The vault itself holds **data only**: there are no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs in it. This makes ECHO self-bootstrapping (point it at an empty Obsidian vault and it stands up the full structure), easy to update (update the plugin, not the vault), and portable to any other vault. *Architecture by Jason Stedwell.*
**The plugin is the single source of truth.** All control logic — bootstrap/repair, operating contract, taxonomy, frontmatter conventions, and the canonical note templates — ships inside this plugin under `skills/quicksilver/`. The vault itself holds **data only**: there are no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs in it. This makes Quicksilver self-bootstrapping (point it at an empty Obsidian vault and it stands up the full structure), easy to update (update the plugin, not the vault), and portable to any other vault.
## What it does ## What it does
- Loads operator preferences, current context, and relevant project notes at the start of substantive conversations - Loads operator preferences, current context, and relevant project notes at the start of substantive conversations
- Writes facts, preferences, and decisions Jason asks Claude to remember - Writes facts, preferences, and decisions the operator asks Claude to remember
- Logs working sessions so future conversations can pick up where they left off - Logs working sessions so future conversations can pick up where they left off
- **Bootstraps an empty vault from the bundled `scaffold/`** (folders, templates, anchor seeds, marker) and repairs/migrates an existing one — see `skills/echo-memory/references/bootstrap.md` - **Bootstraps an empty vault from the bundled `scaffold/`** (folders, templates, anchor seeds, marker) and repairs/migrates an existing one — see `skills/quicksilver/references/bootstrap.md`
## Configuration ## First-run configuration
The plugin is hardcoded for: The plugin ships with **no endpoint or key baked in**. The first time the skill runs, it detects that this install is unconfigured and asks the operator for:
- **Server:** `https://echoapi.alwisp.com` (reverse proxy → backend Obsidian Local REST API) 1. **API endpoint FQDN** — e.g. `https://obsidian.example.com` (the Obsidian Local REST API, typically behind a reverse proxy)
- **API Key:** stored in the skill (personal plugin, not for distribution) 2. **API key** — the Local REST API bearer token
3. **Operator name + role** — used to personalize memory ("Alex prefers …")
The endpoint presents a **valid TLS certificate**, so `-k` is not required. The bearer key lives only in the plugin — never inside the vault (per the vault's own safety rules). It verifies the endpoint, then writes a **local config file** at:
```
~/.quicksilver/quicksilver-config.json (macOS/Linux)
%USERPROFILE%\.quicksilver\quicksilver-config.json (Windows)
```
```json
{
"schema": 1,
"endpoint": "https://obsidian.example.com",
"api_key": "<bearer-token>",
"operator": { "name": "Alex Rivera", "role": "Network Engineer" },
"configured_at": "YYYY-MM-DD",
"verified_at": "YYYY-MM-DD"
}
```
This file is the install's "is this configured?" signal. It lives in the user home (outside the plugin and the vault), so it survives plugin reinstalls and is never committed. Once it exists, the skill loads silently with no further prompts.
**The API key is never written into the vault** — only into this local config file (per the vault's own safety rules). The in-vault marker `_agent/quicksilver-vault.md` records the schema version, bootstrap date, and operator name only.
## Vault layout (root-addressed) ## Vault layout (root-addressed)
@@ -36,7 +59,7 @@ The endpoint presents a **valid TLS certificate**, so `-k` is not required. The
├── reviews/ (weekly, monthly, quarterly, annual) ├── reviews/ (weekly, monthly, quarterly, annual)
├── archive/ (notes, projects, imports) ├── archive/ (notes, projects, imports)
└── _agent/ └── _agent/
├── echo-vault.md ← bootstrap marker (schema_version + date) ├── quicksilver-vault.md ← bootstrap marker (schema_version + date + operator)
├── context/ ← task-scoped context bundles ├── context/ ← task-scoped context bundles
├── memory/ ← working / episodic / semantic ├── memory/ ← working / episodic / semantic
├── sessions/ ← YYYY-MM-DD-HHMM-<slug>.md ├── sessions/ ← YYYY-MM-DD-HHMM-<slug>.md
@@ -49,16 +72,16 @@ The endpoint presents a **valid TLS certificate**, so `-k` is not required. The
Control logic and the master scaffold live in the plugin, not the vault: Control logic and the master scaffold live in the plugin, not the vault:
``` ```
skills/echo-memory/ skills/quicksilver/
├── SKILL.md ← operating procedure (authoritative) ├── SKILL.md ← operating procedure (authoritative)
├── references/ ├── references/
│ ├── operating-contract.md ← durable principles + safety │ ├── operating-contract.md ← durable principles + safety
│ ├── bootstrap.md ← bootstrap / repair / migrate an empty vault │ ├── bootstrap.md ← first-run config / bootstrap / repair / migrate
│ ├── vault-layout.md ← canonical layout + frontmatter │ ├── vault-layout.md ← canonical layout + frontmatter
│ ├── api-reference.md ← REST endpoint patterns + routing map │ ├── api-reference.md ← REST endpoint patterns + routing map
│ └── session-log-template.md │ └── session-log-template.md
└── scaffold/ ← verbatim files the bootstrap writes into the vault └── scaffold/ ← verbatim files the bootstrap writes into the vault
├── README.vault.md echo-vault.md ├── README.vault.md quicksilver-vault.md
├── templates/ (8 note templates) ├── templates/ (8 note templates)
└── anchors/ (operator-preferences, current-context, inbox seeds) └── anchors/ (operator-preferences, current-context, inbox seeds)
``` ```
@@ -67,9 +90,9 @@ skills/echo-memory/
| Skill | Triggers | | Skill | Triggers |
|-------|----------| |-------|----------|
| `echo-memory` | "remember that", "save to memory", "what do you know about me", "load my profile", "check my notes", "log this decision", "add to my inbox" — and proactively at the start of substantive conversations | | `quicksilver` | "remember that", "save to memory", "what do you know about me", "load my profile", "check my notes", "log this decision", "add to my inbox" — and proactively at the start of substantive conversations |
## Requirements ## Requirements
- Obsidian running on the backend with the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled - Obsidian running on the backend with the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled
- HTTPS access to `https://echoapi.alwisp.com` from the Claude/CoWork session environment - HTTPS access to the configured endpoint from the Claude/CoWork session environment
@@ -1,31 +1,36 @@
--- ---
name: echo-memory name: quicksilver
description: Use the ECHO Obsidian vault as Jason's persistent memory across Claude/CoWork sessions. Use whenever Jason asks to remember, save, note, log, or capture anything durable — facts, preferences, decisions, schedule changes, commitments — or asks what Claude knows about him, what was discussed or decided before, to check his notes, load his memory/profile/context, add to his inbox, or to track a new project. Trigger even without memory phrasing when the request implies recalling or persisting state across sessions ("pick up where we left off", "anything on X before my meeting?"). Also use proactively at the start of substantive work sessions to load context and at the end to log outcomes. Do NOT use for Bryan's goldbrain vault, Obsidian/REST-API development questions, "memory" meaning RAM, timed reminders, email or local-file lookups, generic second-brain advice, or notes Jason routes to a specific other file or app. description: Use the Quicksilver Obsidian vault as the operator's persistent memory across Claude/CoWork sessions. Use whenever the operator asks to remember, save, note, log, or capture anything durable — facts, preferences, decisions, schedule changes, commitments — or asks what Claude knows about them, what was discussed or decided before, to check their notes, load their memory/profile/context, add to their inbox, or to track a new project. Trigger even without memory phrasing when the request implies recalling or persisting state across sessions ("pick up where we left off", "anything on X before my meeting?"). Also use proactively at the start of substantive work sessions to load context and at the end to log outcomes. Do NOT use for a different operator's vault, Obsidian/REST-API development questions, "memory" meaning RAM, timed reminders, email or local-file lookups, generic second-brain advice, or notes the operator routes to a specific other file or app.
--- ---
# ECHO Memory # Quicksilver Memory
Use the **ECHO** Obsidian vault as persistent memory. Read context accumulated across sessions; write things the operator asks to be remembered. Use the **Quicksilver** Obsidian vault as persistent memory. Read context accumulated across sessions; write things the operator asks to be remembered.
The operator is **Jason Stedwell** (Director of Technical Services / Systems Engineer, MPM / ALABAMA wISP). Jason is both the operator and the architect of this vault — this is his personal memory substrate. Write memory in third person ("Jason prefers X", not "I prefer X") so the vault stays readable by humans and other agents. The vault belongs to a single **operator**, whose name and role are captured at first run (stored in the local config file and the vault marker's `operator:` field, and seeded into `operator-preferences.md`). Write memory in third person using the operator's name (e.g. "Alex prefers X", not "I prefer X") so the vault stays readable by humans and other agents.
## API Configuration ## Configuration & First Run
All calls use these constants — hardcoded for this personal plugin: Credentials are **not hardcoded**. They live in a local config file:
``` ```
OBSIDIAN_BASE = https://echoapi.alwisp.com ~/.quicksilver/quicksilver-config.json (macOS/Linux)
OBSIDIAN_KEY = 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab %USERPROFILE%\.quicksilver\quicksilver-config.json (Windows)
``` ```
The endpoint has a **valid TLS certificate**, so `-k` is not needed (add it only if the cert ever changes to self-signed). Always pass the `Authorization: Bearer` header. Paths address the vault **at its root** (e.g. `/vault/_agent/...`). At session start, **read this file** (use the Read tool — no `jq` needed) and set, for every call below:
**`https://echoapi.alwisp.com` is the only valid endpoint for this vault.** Never use local or LAN addresses (anything like `10.x.x.x`, `192.168.x.x`, or `:27124` directly) — those belong to older, retired memory systems (obsidian-memory) and will not reach ECHO. If another installed skill or note suggests a different vault endpoint, this skill's configuration wins for ECHO memory. ```bash
BASE="<endpoint from config>" # e.g. https://obsidian.example.com
AUTH="Authorization: Bearer <api_key from config>"
```
**The plugin is the single source of truth for ECHO.** The vault holds data only — no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs live there. All structure and procedure ship here: **If the config file is absent, this is a fresh install** — run the first-run flow in `references/bootstrap.md` (prompt the operator for endpoint FQDN, API key, and name/role; verify; write the config file) **before** any vault call. Do not invent an endpoint. The endpoint is expected to present a **valid TLS certificate**, so `-k` is not needed (add it only if the operator's endpoint uses a self-signed cert). Always pass the `Authorization: Bearer` header. Paths address the vault **at its root** (e.g. `/vault/_agent/...`).
**The plugin is the single source of truth.** The vault holds data only — no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs live there. All structure and procedure ship here:
- Durable principles, memory model, and safety rules: `references/operating-contract.md` - Durable principles, memory model, and safety rules: `references/operating-contract.md`
- Bootstrapping an empty vault, repair, and schema migrations: `references/bootstrap.md` - First-run config, bootstrapping an empty vault, repair, and schema migrations: `references/bootstrap.md`
- Vault layout and frontmatter conventions: `references/vault-layout.md` - Vault layout and frontmatter conventions: `references/vault-layout.md`
- Full API reference with every endpoint pattern and the memory routing map: `references/api-reference.md` - Full API reference with every endpoint pattern and the memory routing map: `references/api-reference.md`
@@ -36,38 +41,38 @@ The vault is the **system of record** for long-term memory, not a scratchpad. De
- Do not fabricate facts, relationships, or prior decisions. - Do not fabricate facts, relationships, or prior decisions.
- Do not mass-restructure the vault unless explicitly asked. - Do not mass-restructure the vault unless explicitly asked.
- Do not delete notes unless deletion is explicitly requested and clearly safe. - Do not delete notes unless deletion is explicitly requested and clearly safe.
- Never store secrets or API keys inside a vault note. - Never store secrets or API keys inside a vault note. (The API key lives only in the local config file.)
Full contract (principles, agent role, memory model): `references/operating-contract.md`. Full contract (principles, agent role, memory model): `references/operating-contract.md`.
## When to Load Memory ## When to Load Memory
Load at the start of any substantive conversation — anything beyond a single quick factual question. The signal: Jason is starting work, planning, asking for help with something that has state, or referencing prior discussions. Load at the start of any substantive conversation — anything beyond a single quick factual question. The signal: the operator is starting work, planning, asking for help with something that has state, or referencing prior discussions.
### Loading procedure ### Loading procedure
The cold-start reads are independent — **issue them in parallel** (one batch of 45 GETs), not sequentially. Parallel loading is ~3× faster wall-clock for the same call count. **Step 0 — ensure the install is configured.** Read the local config file (above). If it's missing, run the first-run flow in `references/bootstrap.md` first. Otherwise load `$BASE`, the bearer key, and the operator's name.
Then the cold-start reads are independent — **issue them in parallel** (one batch of 45 GETs), not sequentially. Parallel loading is ~3× faster wall-clock for the same call count.
| # | GET | Notes | | # | GET | Notes |
|---|-----|-------| |---|-----|-------|
| 1 | `/vault/_agent/echo-vault.md` | The bootstrap marker. 404 → vault not set up; follow `references/bootstrap.md`. 200 → check its `schema_version` and migrate if older. | | 1 | `/vault/_agent/quicksilver-vault.md` | The bootstrap marker. 404 → vault not set up; follow `references/bootstrap.md`. 200 → check its `schema_version` and migrate if older. |
| 2 | `/vault/_agent/memory/semantic/operator-preferences.md` | Jason's profile | | 2 | `/vault/_agent/memory/semantic/operator-preferences.md` | The operator's profile |
| 3 | `/vault/_agent/context/current-context.md` | Active scope + Scope History | | 3 | `/vault/_agent/context/current-context.md` | Active scope + Scope History |
| 4 | `/vault/_agent/sessions/` (listing) | Pick the ~5 most recent by reverse lex sort (filenames `YYYY-MM-DD-HHMM-<slug>.md`, so lex == chrono); only read the ones whose slugs look relevant | | 4 | `/vault/_agent/sessions/` (listing) | Pick the ~5 most recent by reverse lex sort (filenames `YYYY-MM-DD-HHMM-<slug>.md`, so lex == chrono); only read the ones whose slugs look relevant |
| 5 | `/vault/journal/daily/YYYY-MM-DD.md` | Today's note; 404 is fine — it's created on first agent activity | | 5 | `/vault/journal/daily/YYYY-MM-DD.md` | Today's note; 404 is fine — it's created on first agent activity |
Do not read every session log — older sessions are reachable via `POST /search/simple/?query=...` when needed. Do not read every session log — older sessions are reachable via `POST /search/simple/?query=...` when needed.
**If a specific project is in play**, follow up with a **search across all lifecycle subfolders** (`active/`, `incubating/`, `on-hold/`, `archived/`) — searching one folder at a time misses notes filed elsewhere. Search by **both the slug AND any human title** Jason used in this conversation: **If a specific project is in play**, follow up with a **search across all lifecycle subfolders** (`active/`, `incubating/`, `on-hold/`, `archived/`) — searching one folder at a time misses notes filed elsewhere. Search by **both the slug AND any human title** the operator used in this conversation:
```bash ```bash
# slug # slug
curl -s -X POST -H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<slug>"
"https://echoapi.alwisp.com/search/simple/?query=<slug>"
# human title (avoids missing notes filed under a different name) # human title (avoids missing notes filed under a different name)
curl -s -X POST -H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<human+title>"
"https://echoapi.alwisp.com/search/simple/?query=<human+title>"
``` ```
Then read whichever match lives at `projects/<lifecycle>/<slug>.md`. Then read whichever match lives at `projects/<lifecycle>/<slug>.md`.
@@ -89,7 +94,7 @@ When routing accepted items, send each to its proper home:
- Durable fact → PUT `_agent/memory/semantic/<slug>.md` - Durable fact → PUT `_agent/memory/semantic/<slug>.md`
- Person fact → PUT/PATCH `resources/people/<name>.md` - Person fact → PUT/PATCH `resources/people/<name>.md`
Then record the move in `inbox/processing-log/YYYY-MM-DD.md` (one line per item: `- <original line> → <destination path>`). Don't delete the original capture unless Jason explicitly asks — the processing log is the audit trail. Then record the move in `inbox/processing-log/YYYY-MM-DD.md` (one line per item: `- <original line> → <destination path>`). Don't delete the original capture unless the operator explicitly asks — the processing log is the audit trail.
## Project Lifecycle ## Project Lifecycle
@@ -108,31 +113,29 @@ Projects move through four folders under `projects/`. The folder name and the `s
## When to Write Memory ## When to Write Memory
Write when Jason: Write when the operator:
- States a fact, preference, or commitment worth keeping ("I prefer X", "we use uv not pip", "standup is Tuesday at 10") - States a fact, preference, or commitment worth keeping ("I prefer X", "we use uv not pip", "standup is Tuesday at 10")
- Makes a non-obvious decision worth recording - Makes a non-obvious decision worth recording
- Says "remember that", "save this", "log this", "add to memory", "note that" - Says "remember that", "save this", "log this", "add to memory", "note that"
- Finishes a meaningful working session future sessions should pick up - Finishes a meaningful working session future sessions should pick up
Write in third person about Jason. Every note carries the canonical frontmatter (see below). Agent-generated notes set `agent_written: true`. Write in third person about the operator (by name). Every note carries the canonical frontmatter (see below). Agent-generated notes set `agent_written: true`.
### Before you write — search first (MANDATORY for new notes) ### Before you write — search first (MANDATORY for new notes)
**Before creating any new note at `projects/<lifecycle>/<slug>.md`, `_agent/memory/semantic/<slug>.md`, `resources/people/<name>.md`, or any other slug-addressed location, search the whole vault for that slug.** Listing a single folder (e.g. `projects/active/`) is NOT sufficient — a note with the same slug may exist in `projects/on-hold/`, `projects/incubating/`, `projects/archived/`, or under a different folder entirely. **Before creating any new note at `projects/<lifecycle>/<slug>.md`, `_agent/memory/semantic/<slug>.md`, `resources/people/<name>.md`, or any other slug-addressed location, search the whole vault for that slug.** Listing a single folder (e.g. `projects/active/`) is NOT sufficient — a note with the same slug may exist in `projects/on-hold/`, `projects/incubating/`, `projects/archived/`, or under a different folder entirely.
```bash ```bash
curl -s -X POST \ curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<slug>"
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
"https://echoapi.alwisp.com/search/simple/?query=<slug>"
``` ```
If a match is found: If a match is found:
- In a non-active project subfolder (`on-hold/`, `incubating/`, `archived/`): **promote/merge** — PUT the merged content to `projects/active/<slug>.md` with `status: active`, then DELETE the old location. Preserve the earliest `created:` date. - In a non-active project subfolder (`on-hold/`, `incubating/`, `archived/`): **promote/merge** — PUT the merged content to `projects/active/<slug>.md` with `status: active`, then DELETE the old location. Preserve the earliest `created:` date.
- In the same folder you intended to write: **update in place** (PATCH or merged PUT). Never silently overwrite — fold the existing content in first. - In the same folder you intended to write: **update in place** (PATCH or merged PUT). Never silently overwrite — fold the existing content in first.
- Elsewhere (e.g. a stale duplicate under `resources/`): tell Jason and ask which should be canonical before writing. - Elsewhere (e.g. a stale duplicate under `resources/`): tell the operator and ask which should be canonical before writing.
**Search both the slug AND any human title** Jason used (e.g. slug `echo-memory` and title `ECHO plugin`). Slug-only searches miss notes filed under a different naming scheme. Two cheap `POST /search/simple/?query=...` calls beat one expensive cleanup pass later. **Search both the slug AND any human title** the operator used (e.g. slug `quicksilver` and title `Quicksilver plugin`). Slug-only searches miss notes filed under a different naming scheme. Two cheap `POST /search/simple/?query=...` calls beat one expensive cleanup pass later.
Only after the search comes back empty (or you've decided to merge) is it safe to create a new note. This rule prevents the most common duplication bug: a note exists in `on-hold/` but the agent only checked `active/` and created a parallel record. Only after the search comes back empty (or you've decided to merge) is it safe to create a new note. This rule prevents the most common duplication bug: a note exists in `on-hold/` but the agent only checked `active/` and created a parallel record.
@@ -157,11 +160,10 @@ cat > /tmp/obs_entry.md << 'OBSEOF'
- 2026-06-05: <your entry here> - 2026-06-05: <your entry here>
OBSEOF OBSEOF
curl -s -X POST \ curl -s -X POST -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_entry.md \ --data-binary @/tmp/obs_entry.md \
"https://echoapi.alwisp.com/vault/inbox/captures/inbox.md" "$BASE/vault/inbox/captures/inbox.md"
``` ```
POST appends to the end of a file (creating it if absent). Use it for inbox captures and log sections. POST appends to the end of a file (creating it if absent). Use it for inbox captures and log sections.
@@ -173,9 +175,9 @@ POST appends to the end of a file (creating it if absent). Use it for inbox capt
**Default: GET the document map first** (every first PATCH to a file in a session — cache the result mentally for subsequent PATCHes to the same file). This eliminates the most common failure mode of PATCH: **Default: GET the document map first** (every first PATCH to a file in a session — cache the result mentally for subsequent PATCHes to the same file). This eliminates the most common failure mode of PATCH:
```bash ```bash
curl -s -H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ curl -s -H "$AUTH" \
-H "Accept: application/vnd.olrapi.document-map+json" \ -H "Accept: application/vnd.olrapi.document-map+json" \
"https://echoapi.alwisp.com/vault/_agent/memory/semantic/operator-preferences.md" "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
``` ```
Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. Only skip the doc-map GET if you wrote the file yourself in this session (you already know its structure). Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. Only skip the doc-map GET if you wrote the file yourself in this session (you already know its structure).
@@ -184,17 +186,16 @@ Then PATCH:
```bash ```bash
cat > /tmp/obs_patch.md << 'OBSEOF' cat > /tmp/obs_patch.md << 'OBSEOF'
Jason prefers status updates that lead with the decision. <Operator> prefers status updates that lead with the decision.
OBSEOF OBSEOF
curl -s -X PATCH \ curl -s -X PATCH -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Operation: append" \ -H "Operation: append" \
-H "Target-Type: heading" \ -H "Target-Type: heading" \
-H "Target: Operator Preferences::Fact / Pattern" \ -H "Target: Operator Preferences::Fact / Pattern" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_patch.md \ --data-binary @/tmp/obs_patch.md \
"https://echoapi.alwisp.com/vault/_agent/memory/semantic/operator-preferences.md" "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
``` ```
Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Project Name::Current status`). Percent-encode non-ASCII characters in the `Target` header; spaces are fine. Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Project Name::Current status`). Percent-encode non-ASCII characters in the `Target` header; spaces are fine.
@@ -204,11 +205,10 @@ Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Proj
When a PATCH or PUT changes meaningful content (status update, decision recorded, current-status replacement, scope switch), also PATCH the frontmatter `updated:` field to today's date. This keeps stale-detection queries honest. When a PATCH or PUT changes meaningful content (status update, decision recorded, current-status replacement, scope switch), also PATCH the frontmatter `updated:` field to today's date. This keeps stale-detection queries honest.
```bash ```bash
curl -s -X PATCH \ curl -s -X PATCH -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Operation: replace" -H "Target-Type: frontmatter" -H "Target: updated" \ -H "Operation: replace" -H "Target-Type: frontmatter" -H "Target: updated" \
-H "Content-Type: application/json" --data '"2026-06-06"' \ -H "Content-Type: application/json" --data '"2026-06-06"' \
"https://echoapi.alwisp.com/vault/projects/active/<slug>.md" "$BASE/vault/projects/active/<slug>.md"
``` ```
Skip the bump for **routine log appends** — adding an Agent Log line, an inbox capture, or a timestamped Observations bullet doesn't constitute a meaningful content change. Bump on substance, not on heartbeat. Skip the bump for **routine log appends** — adding an Agent Log line, an inbox capture, or a timestamped Observations bullet doesn't constitute a meaningful content change. Bump on substance, not on heartbeat.
@@ -236,11 +236,10 @@ source_notes: []
- [[journal/daily/2026-06-05]] - [[journal/daily/2026-06-05]]
OBSEOF OBSEOF
curl -s -X PUT \ curl -s -X PUT -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_file.md \ --data-binary @/tmp/obs_file.md \
"https://echoapi.alwisp.com/vault/projects/active/my-project.md" "$BASE/vault/projects/active/my-project.md"
``` ```
The API creates intermediate directories automatically. The API creates intermediate directories automatically.
@@ -248,14 +247,13 @@ The API creates intermediate directories automatically.
### Search the vault ### Search the vault
```bash ```bash
curl -s -X POST \ curl -s -X POST -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ "$BASE/search/simple/?query=your+search+terms"
"https://echoapi.alwisp.com/search/simple/?query=your+search+terms"
``` ```
## Scope Switching (`current-context.md`) ## Scope Switching (`current-context.md`)
`_agent/context/current-context.md` tracks a single active scope. Jason routinely shifts scope within a day (echo plugin → MPM brand → WISP docs). `_agent/context/current-context.md` tracks a single active scope. The operator may shift scope several times within a day.
When scope changes: When scope changes:
@@ -290,14 +288,14 @@ After substantive activity, write a one-line entry to today's daily note's `## A
4. PATCH-append the entry under the target `<YYYY-MM-DD>::Agent Log` (the H1 of a daily note is the date, so that's the full target path). 4. PATCH-append the entry under the target `<YYYY-MM-DD>::Agent Log` (the H1 of a daily note is the date, so that's the full target path).
```bash ```bash
# $BASE and $AUTH come from the local config file (see Configuration & First Run)
DATE=$(date +%Y-%m-%d) DATE=$(date +%Y-%m-%d)
DAILY="https://echoapi.alwisp.com/vault/journal/daily/${DATE}.md" DAILY="$BASE/vault/journal/daily/${DATE}.md"
AUTH="Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab"
# 1+2: ensure the daily note exists (PUT from template if missing) # 1+2: ensure the daily note exists (PUT from template if missing)
HTTP=$(curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$DAILY") HTTP=$(curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$DAILY")
if [ "$HTTP" = "404" ]; then if [ "$HTTP" = "404" ]; then
curl -s -H "$AUTH" "https://echoapi.alwisp.com/vault/journal/templates/daily-note-template.md" \ curl -s -H "$AUTH" "$BASE/vault/journal/templates/daily-note-template.md" \
| sed "s/{{date:YYYY-MM-DD}}/${DATE}/g" \ | sed "s/{{date:YYYY-MM-DD}}/${DATE}/g" \
| curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- "$DAILY" | curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- "$DAILY"
fi fi
@@ -343,7 +341,7 @@ curl -s -X PATCH -H "$AUTH" \
**Decision mirrors:** if the decision belongs to an existing note in `projects/active/`, add a `[[wikilink]]` to the ADR under that project's `## Key Decisions` heading (PATCH). If no matching project note exists, skip the mirror — the by-date ADR is sufficient; do not invent topical mirror files in `decisions/by-project/`. **Decision mirrors:** if the decision belongs to an existing note in `projects/active/`, add a `[[wikilink]]` to the ADR under that project's `## Key Decisions` heading (PATCH). If no matching project note exists, skip the mirror — the by-date ADR is sufficient; do not invent topical mirror files in `decisions/by-project/`.
Never delete files unless Jason explicitly asks. Memory is append-friendly; deletion is destructive. Never delete files unless the operator explicitly asks. Memory is append-friendly; deletion is destructive.
## Session Logging ## Session Logging
@@ -358,23 +356,22 @@ cat > /tmp/obs_session.md << 'OBSEOF'
<session log content — see references/session-log-template.md> <session log content — see references/session-log-template.md>
OBSEOF OBSEOF
curl -s -X PUT \ curl -s -X PUT -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_session.md \ --data-binary @/tmp/obs_session.md \
"https://echoapi.alwisp.com/vault/_agent/sessions/2026-06-05-1430-my-session.md" "$BASE/vault/_agent/sessions/2026-06-05-1430-my-session.md"
``` ```
Then add a one-line entry to today's daily note via the **Daily Note — Agent Log** procedure above. Then add a one-line entry to today's daily note via the **Daily Note — Agent Log** procedure above.
## Vault Unreachable ## Vault Unreachable
If the API returns a connection error, timeout, or `502`, tell Jason once that the memory vault is unreachable (a `502` usually means Obsidian/the REST plugin is not running on the backend), then proceed without memory. Do not retry repeatedly. If the API returns a connection error, timeout, or `502`, tell the operator once that the memory vault is unreachable (a `502` usually means Obsidian/the REST plugin is not running on the backend), then proceed without memory. Do not retry repeatedly.
## Style Rules ## Style Rules
- Write in third person about Jason: "Jason prefers X", not "I prefer X". - Write in third person about the operator, by name: "<Operator> prefers X", not "I prefer X".
- Jason is both operator and architect here — unlike goldbrain (Bryan's vault, which Jason architected). Do not cross-write: Bryan's preferences belong in goldbrain, Jason's belong here. - One vault, one operator. Do not cross-write into another operator's vault; this skill's configured endpoint owns this operator's memory.
- **Anchor relative dates on the conversation's `currentDate`** before writing. "Today" → `currentDate`. "Thursday" / "next week" → resolve to an absolute `YYYY-MM-DD`. Never guess from training-data knowledge of the current year. - **Anchor relative dates on the conversation's `currentDate`** before writing. "Today" → `currentDate`. "Thursday" / "next week" → resolve to an absolute `YYYY-MM-DD`. Never guess from training-data knowledge of the current year.
- Every memory file has canonical YAML frontmatter — see `references/vault-layout.md`. - Every memory file has canonical YAML frontmatter — see `references/vault-layout.md`.
- Set `agent_written: true` on agent-generated notes and list `source_notes` (plain relative paths, not links). - Set `agent_written: true` on agent-generated notes and list `source_notes` (plain relative paths, not links).
@@ -382,15 +379,15 @@ If the API returns a connection error, timeout, or `502`, tell Jason once that t
- **`source_notes` lists the note(s) that *triggered* or *supplied content for* this one** — e.g. the session log that produced a project update, or the daily note where a captured fact originated. It is a *backward* link to inputs. Forward links (this note → other notes it references) belong in the `## Related` section in the note body, never in frontmatter. - **`source_notes` lists the note(s) that *triggered* or *supplied content for* this one** — e.g. the session log that produced a project update, or the daily note where a captured fact originated. It is a *backward* link to inputs. Forward links (this note → other notes it references) belong in the `## Related` section in the note body, never in frontmatter.
- **Never put `[[wikilinks]]` in frontmatter** — YAML parses them as nested lists and the links break in Obsidian's reading view. Put all cross-references in a `## Related` section in the note **body** as a bulleted list of `[[links]]`. - **Never put `[[wikilinks]]` in frontmatter** — YAML parses them as nested lists and the links break in Obsidian's reading view. Put all cross-references in a `## Related` section in the note **body** as a bulleted list of `[[links]]`.
- Use Obsidian wiki links (`[[note name]]`) freely in the note **body** for cross-references. - Use Obsidian wiki links (`[[note name]]`) freely in the note **body** for cross-references.
- Keep entries short and focused. Fewer, sharper entries beat many noisy ones — Jason explicitly prefers concision. - Keep entries short and focused. Fewer, sharper entries beat many noisy ones — default to concision.
- About to write something large or sensitive? Show Jason the content first and confirm. - About to write something large or sensitive? Show the operator the content first and confirm.
## operator-preferences.md — Rules vs Observations ## operator-preferences.md — Rules vs Observations
`_agent/memory/semantic/operator-preferences.md` separates two kinds of content: `_agent/memory/semantic/operator-preferences.md` separates two kinds of content:
- `## Fact / Pattern`**promoted, deduped rules.** No date prefix. These are timeless: "Jason prefers concise communication." Append here only when a rule is stable. - `## Fact / Pattern`**promoted, deduped rules.** No date prefix. These are timeless: "<Operator> prefers concise communication." Append here only when a rule is stable.
- `## Observations`**timestamped raw observations.** Date-prefixed: `- 2026-06-06: Jason chose X over Y because Z.` This is where new evidence goes by default. - `## Observations`**timestamped raw observations.** Date-prefixed: `- 2026-06-06: <Operator> chose X over Y because Z.` This is where new evidence goes by default.
During monthly Vault Health or when an observation stabilizes, promote it from `## Observations` into `## Fact / Pattern` (drop the date) and remove the duplicate from Observations. Trim Observations to the last ~30 entries when it grows past that — the rest live in session logs. During monthly Vault Health or when an observation stabilizes, promote it from `## Observations` into `## Fact / Pattern` (drop the date) and remove the duplicate from Observations. Trim Observations to the last ~30 entries when it grows past that — the rest live in session logs.
@@ -1,8 +1,17 @@
# ECHO — Obsidian Local REST API Reference # Quicksilver — Obsidian Local REST API Reference
Server: `https://echoapi.alwisp.com` (reverse proxy → backend Obsidian Local REST API) Server and key are **not hardcoded** — they come from the local config file
Auth header: `Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab` (`~/.quicksilver/quicksilver-config.json`; see `references/bootstrap.md`). Load them once
The endpoint has a **valid TLS certificate**`-k` is not required. Paths address the vault at its **root**. per session and use them in every call:
```bash
BASE="<endpoint from config>" # e.g. https://obsidian.example.com
AUTH="Authorization: Bearer <api_key from config>"
```
The examples below use `$BASE` and the `$AUTH` header. The endpoint is expected to present a
**valid TLS certificate** — `-k` is not required (add it only if the operator's endpoint uses a
self-signed cert). Paths address the vault at its **root**.
--- ---
@@ -10,18 +19,15 @@ The endpoint has a **valid TLS certificate** — `-k` is not required. Paths add
```bash ```bash
# Read any file by vault path # Read any file by vault path
curl -s \ curl -s -H "$AUTH" "$BASE/vault/_agent/context/current-context.md"
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
"https://echoapi.alwisp.com/vault/_agent/context/current-context.md"
``` ```
Returns raw file content (text/markdown). On 404, the file does not exist. Returns raw file content (text/markdown). On 404, the file does not exist.
```bash ```bash
# Read a specific heading's content only # Read a specific heading's content only
curl -s \ curl -s -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ "$BASE/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator"
"https://echoapi.alwisp.com/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator"
``` ```
Nested headings: separate levels with `::` (URL-encode spaces as `%20`): Nested headings: separate levels with `::` (URL-encode spaces as `%20`):
@@ -35,9 +41,7 @@ Nested headings: separate levels with `::` (URL-encode spaces as `%20`):
```bash ```bash
# List contents of a directory (trailing slash required) # List contents of a directory (trailing slash required)
curl -s \ curl -s -H "$AUTH" "$BASE/vault/_agent/sessions/"
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
"https://echoapi.alwisp.com/vault/_agent/sessions/"
``` ```
Returns JSON: `{ "files": [...], "folders": [...] }`. Returns JSON: `{ "files": [...], "folders": [...] }`.
@@ -53,11 +57,10 @@ cat > /tmp/obs_entry.md << 'OBSEOF'
- 2026-06-05: your entry here - 2026-06-05: your entry here
OBSEOF OBSEOF
curl -s -X POST \ curl -s -X POST -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_entry.md \ --data-binary @/tmp/obs_entry.md \
"https://echoapi.alwisp.com/vault/inbox/captures/inbox.md" "$BASE/vault/inbox/captures/inbox.md"
``` ```
--- ---
@@ -84,11 +87,10 @@ source_notes: []
- [[projects/active/some-project]] - [[projects/active/some-project]]
OBSEOF OBSEOF
curl -s -X PUT \ curl -s -X PUT -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_file.md \ --data-binary @/tmp/obs_file.md \
"https://echoapi.alwisp.com/vault/_agent/sessions/2026-06-05-1430-my-session.md" "$BASE/vault/_agent/sessions/2026-06-05-1430-my-session.md"
``` ```
--- ---
@@ -103,17 +105,16 @@ curl -s -X PUT \
```bash ```bash
cat > /tmp/obs_patch.md << 'OBSEOF' cat > /tmp/obs_patch.md << 'OBSEOF'
Jason prefers concise status updates — lead with the decision. The operator prefers concise status updates — lead with the decision.
OBSEOF OBSEOF
curl -s -X PATCH \ curl -s -X PATCH -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Operation: append" \ -H "Operation: append" \
-H "Target-Type: heading" \ -H "Target-Type: heading" \
-H "Target: Operator Preferences::Fact / Pattern" \ -H "Target: Operator Preferences::Fact / Pattern" \
-H "Content-Type: text/markdown" \ -H "Content-Type: text/markdown" \
--data-binary @/tmp/obs_patch.md \ --data-binary @/tmp/obs_patch.md \
"https://echoapi.alwisp.com/vault/_agent/memory/semantic/operator-preferences.md" "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
``` ```
### Discover heading / block / frontmatter targets ### Discover heading / block / frontmatter targets
@@ -121,10 +122,9 @@ curl -s -X PATCH \
When unsure of the exact heading path, GET the note with the document-map Accept header: When unsure of the exact heading path, GET the note with the document-map Accept header:
```bash ```bash
curl -s \ curl -s -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Accept: application/vnd.olrapi.document-map+json" \ -H "Accept: application/vnd.olrapi.document-map+json" \
"https://echoapi.alwisp.com/vault/_agent/memory/semantic/operator-preferences.md" "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
``` ```
Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`.
@@ -140,14 +140,13 @@ Same call with `Operation: prepend`.
### Patch a frontmatter field ### Patch a frontmatter field
```bash ```bash
curl -s -X PATCH \ curl -s -X PATCH -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-H "Operation: replace" \ -H "Operation: replace" \
-H "Target-Type: frontmatter" \ -H "Target-Type: frontmatter" \
-H "Target: updated" \ -H "Target: updated" \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
--data '"2026-06-05"' \ --data '"2026-06-05"' \
"https://echoapi.alwisp.com/vault/projects/active/vault-foundation.md" "$BASE/vault/projects/active/vault-foundation.md"
``` ```
--- ---
@@ -155,9 +154,8 @@ curl -s -X PATCH \
## Searching ## Searching
```bash ```bash
curl -s -X POST \ curl -s -X POST -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ "$BASE/search/simple/?query=weekly+review"
"https://echoapi.alwisp.com/search/simple/?query=weekly+review"
``` ```
Returns an array of `{ filename, score, matches: [{ context, match }] }`. Returns an array of `{ filename, score, matches: [{ context, match }] }`.
@@ -167,9 +165,8 @@ Returns an array of `{ filename, score, matches: [{ context, match }] }`.
## Deleting Files ## Deleting Files
```bash ```bash
curl -s -X DELETE \ curl -s -X DELETE -H "$AUTH" \
-H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \ "$BASE/vault/archive/notes/old-note.md"
"https://echoapi.alwisp.com/vault/archive/notes/old-note.md"
``` ```
Only on explicit operator request. Deletion is destructive. Only on explicit operator request. Deletion is destructive.
@@ -203,6 +200,6 @@ Only on explicit operator request. Deletion is destructive.
| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT | | Concept / reference note | `resources/concepts/` or `resources/references/` | PUT |
| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH | | Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH |
| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT | | Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT |
| Bootstrap marker (plugin-owned) | `_agent/echo-vault.md` (`schema_version`, bootstrap date) — the "is this vault set up?" probe | GET / PUT | | Bootstrap marker (plugin-owned) | `_agent/quicksilver-vault.md` (`schema_version`, bootstrap date, operator) — the "is this vault set up?" probe | GET / PUT |
**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`). **Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`).
@@ -1,22 +1,83 @@
# Bootstrap & Repair # First-run, Bootstrap & Repair
The **plugin is the single source of truth** for ECHO's structure. Everything needed to stand up a vault ships in this skill under `scaffold/` — there is no dependency on any in-vault control doc and no external/local re-seed path. This makes the vault portable: point the REST API at any empty Obsidian vault, run this procedure, and it becomes a working ECHO vault. The **plugin is the single source of truth** for Quicksilver's structure. Everything needed to stand up a vault ships in this skill under `scaffold/` — there is no dependency on any in-vault control doc and no external/local re-seed path. This makes the vault portable: point the REST API at any empty Obsidian vault, run this procedure, and it becomes a working Quicksilver vault.
The vault holds **data only**. It carries no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md`. The "is this vault set up?" signal is a small marker file, `_agent/echo-vault.md`. The vault holds **data only**. It carries no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md`. The "is this vault set up?" signal is a small marker file, `_agent/quicksilver-vault.md`.
There are **two layers** of setup, probed in order:
1. **Local config** — is *this install* configured with an endpoint + key? (Step 0 below.)
2. **Vault marker** — is the *vault* that endpoint points at scaffolded? (the Probe + Fresh bootstrap below.)
---
## Step 0 — Client configuration (first run)
Credentials live in a **local config file**, never in the plugin source and never in the vault:
``` ```
AUTH="Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" ~/.quicksilver/quicksilver-config.json (macOS/Linux)
BASE="https://echoapi.alwisp.com" %USERPROFILE%\.quicksilver\quicksilver-config.json (Windows)
```
At session start, **read this file** (use the Read tool — no `jq` needed). Its shape:
```json
{
"schema": 1,
"endpoint": "https://obsidian.example.com",
"api_key": "<bearer-token>",
"operator": { "name": "Alex Rivera", "role": "Network Engineer" },
"configured_at": "YYYY-MM-DD",
"verified_at": "YYYY-MM-DD"
}
```
- **File present →** load `endpoint` (use as `$BASE`), `api_key` (use as the bearer), and `operator`. Proceed to the vault-marker probe below. No prompts.
- **File absent → FRESH INSTALL.** Tell the operator this looks like a first run, then prompt for:
1. **API endpoint FQDN** (e.g. `https://obsidian.example.com`)
2. **API key** (the Local REST API bearer token)
3. **Operator name + role** (used to personalize memory)
Verify the endpoint before saving — probe the marker path:
```bash
BASE="https://obsidian.example.com" # from the operator
AUTH="Authorization: Bearer <key-from-operator>"
curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/quicksilver-vault.md"
```
- `200` or `404` → reachable and authorized (`404` just means the vault isn't bootstrapped yet — expected on a brand-new vault). Write the config file.
- connection error / `401` / `403` → tell the operator what failed and re-prompt. Do **not** write the config file.
On success, write the config file with the Write tool (set permissions to `0600` where the platform supports it), stamping `configured_at` / `verified_at` with today's date (from `currentDate`):
```json
{
"schema": 1,
"endpoint": "https://obsidian.example.com",
"api_key": "<bearer-token>",
"operator": { "name": "Alex Rivera", "role": "Network Engineer" },
"configured_at": "{{DATE}}",
"verified_at": "{{DATE}}"
}
```
From here on, every call in this skill uses `$BASE` (the configured endpoint) and an `$AUTH` header built from `api_key`:
```bash
BASE="<endpoint from config>"
AUTH="Authorization: Bearer <api_key from config>"
``` ```
--- ---
## Probe — is the vault bootstrapped? ## Probe — is the vault bootstrapped?
At session start, GET the marker: With `$BASE` / `$AUTH` set, GET the marker:
```bash ```bash
curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/echo-vault.md" curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/quicksilver-vault.md"
``` ```
- **200** → bootstrapped. Read the marker's `schema_version`; if it is **less than** the plugin's current schema (1), run a migration pass (see *Migrations* below), otherwise proceed straight to the loading procedure in `SKILL.md`. - **200** → bootstrapped. Read the marker's `schema_version`; if it is **less than** the plugin's current schema (1), run a migration pass (see *Migrations* below), otherwise proceed straight to the loading procedure in `SKILL.md`.
@@ -54,7 +115,7 @@ _agent/outputs/briefs _agent/outputs/drafts _agent/outputs/summaries _agent/o
A leaf README is just a one-liner, e.g.: A leaf README is just a one-liner, e.g.:
```bash ```bash
printf '# %s\n\nMemory vault folder. See the echo-memory plugin for conventions.\n' "captures" \ printf '# %s\n\nMemory vault folder. See the quicksilver plugin for conventions.\n' "captures" \
| curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- \ | curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- \
"$BASE/vault/inbox/captures/README.md" "$BASE/vault/inbox/captures/README.md"
``` ```
@@ -84,7 +145,7 @@ curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" \
### 3. Anchor seeds (only if absent — no fabricated facts) ### 3. Anchor seeds (only if absent — no fabricated facts)
Substitute `{{DATE}}` → today, then PUT each: Substitute `{{DATE}}` → today, and in the operator-preferences seed substitute `{{OPERATOR}}` / `{{ROLE}}` → the name and role captured in Step 0. Then PUT each:
| Scaffold file | Vault path | | Scaffold file | Vault path |
|---|---| |---|---|
@@ -92,7 +153,7 @@ Substitute `{{DATE}}` → today, then PUT each:
| `scaffold/anchors/current-context.seed.md` | `_agent/context/current-context.md` | | `scaffold/anchors/current-context.seed.md` | `_agent/context/current-context.md` |
| `scaffold/anchors/inbox.seed.md` | `inbox/captures/inbox.md` | | `scaffold/anchors/inbox.seed.md` | `inbox/captures/inbox.md` |
The operator-preferences seed is deliberately empty — **do not invent preferences.** Real facts accrue through use. Beyond the name/role captured at first run, the operator-preferences seed is deliberately empty — **do not invent preferences.** Real facts accrue through use.
### 4. Vault README (human signpost) ### 4. Vault README (human signpost)
@@ -100,7 +161,7 @@ Substitute `{{DATE}}` if present, then PUT `scaffold/README.vault.md` → `/vaul
### 5. Marker (write last) ### 5. Marker (write last)
Substitute `{{DATE}}`, then PUT `scaffold/echo-vault.md``/vault/_agent/echo-vault.md`. Once this returns `200`, the vault is bootstrapped. Substitute `{{DATE}}` and `{{OPERATOR}}` (the operator's name from Step 0), then PUT `scaffold/quicksilver-vault.md``/vault/_agent/quicksilver-vault.md`. The marker records schema version, bootstrap date, and operator name only — **never the key.** Once this returns `200`, the vault is bootstrapped.
### 6. First-run trace ### 6. First-run trace
@@ -118,4 +179,15 @@ Run the same steps 15, but GET-probe each path first and **only create what i
When the marker's `schema_version` is older than the plugin's, apply the migration steps for each intervening version, then PATCH the marker's `schema_version` frontmatter to the new value. When the marker's `schema_version` is older than the plugin's, apply the migration steps for each intervening version, then PATCH the marker's `schema_version` frontmatter to the new value.
- **0 → 1** (control-docs-in-plugin): the vault previously carried root control docs (`CLAUDE.md`, `BOOTSTRAP.md`, `STRUCTURE.md`, `index.md`). Back them up outside the vault, DELETE them, PUT the thin `scaffold/README.vault.md` over the old verbose `README.md`, write the `_agent/echo-vault.md` marker, and scrub now-dangling `[[CLAUDE]]`/`[[BOOTSTRAP]]`/`[[STRUCTURE]]`/`[[index]]` links from the `## Related` sections of `operator-preferences.md` and `current-context.md` (leave historical session logs alone). Confirm with the operator before deleting. - **0 → 1** (control-docs-in-plugin): the vault previously carried root control docs (`CLAUDE.md`, `BOOTSTRAP.md`, `STRUCTURE.md`, `index.md`). Back them up outside the vault, DELETE them, PUT the thin `scaffold/README.vault.md` over the old verbose `README.md`, write the marker, and scrub now-dangling `[[CLAUDE]]`/`[[BOOTSTRAP]]`/`[[STRUCTURE]]`/`[[index]]` links from the `## Related` sections of `operator-preferences.md` and `current-context.md` (leave historical session logs alone). Confirm with the operator before deleting.
### Marker rename (legacy `echo-vault.md``quicksilver-vault.md`)
A vault bootstrapped by the older `echo-memory` plugin has its marker at `_agent/echo-vault.md`. On probe, if `_agent/quicksilver-vault.md` is `404` **but** `_agent/echo-vault.md` is `200`, treat it as a rename migration rather than a fresh bootstrap:
1. GET `_agent/echo-vault.md`, preserve its `schema_version` / `bootstrapped` / `operator` values.
2. PUT the current `scaffold/quicksilver-vault.md` to `_agent/quicksilver-vault.md` with those values carried over.
3. DELETE `_agent/echo-vault.md`.
4. Scrub any dangling `[[echo-vault]]` links from `## Related` sections (leave historical session logs alone).
Confirm with the operator before deleting the old marker.
@@ -1,6 +1,6 @@
# ECHO — Operating Contract # Quicksilver — Operating Contract
The durable, client-independent contract for any agent operating against the ECHO vault. These principles and safety rules formerly lived in the vault's `CLAUDE.md`; they now live in the plugin so they survive regardless of what is (or isn't) in the vault. Day-to-day *procedure* — loading order, search-first, triage, scope switching, PATCH/append rules — is owned by `SKILL.md`. This file holds the things that don't change between sessions or clients. The durable, client-independent contract for any agent operating against the Quicksilver vault. These principles and safety rules formerly lived in the vault's `CLAUDE.md`; they now live in the plugin so they survive regardless of what is (or isn't) in the vault. Day-to-day *procedure* — loading order, search-first, triage, scope switching, PATCH/append rules — is owned by `SKILL.md`. This file holds the things that don't change between sessions or clients.
## What this agent is ## What this agent is
@@ -5,7 +5,7 @@ Session logs go in: `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`
**Filename format is canonical and not optional.** The four-digit local-time HHMM component is what makes session filenames lex-sort in true chronological order — the loading procedure depends on it. Before PUT-ing a new session log, validate the filename matches `^\d{4}-\d{2}-\d{2}-\d{4}-[a-z0-9-]+\.md$`. Legacy session logs without HHMM exist in the vault; do not edit their names, but every new write must use the full form. **Filename format is canonical and not optional.** The four-digit local-time HHMM component is what makes session filenames lex-sort in true chronological order — the loading procedure depends on it. Before PUT-ing a new session log, validate the filename matches `^\d{4}-\d{2}-\d{2}-\d{4}-[a-z0-9-]+\.md$`. Legacy session logs without HHMM exist in the vault; do not edit their names, but every new write must use the full form.
The slug describes what the session was about in 25 words, kebab-case. The slug describes what the session was about in 25 words, kebab-case.
Examples: `2026-06-05-1430-echo-plugin-build.md`, `2026-05-14-0900-q1-review-prep.md`. Examples: `2026-06-05-1430-quicksilver-plugin-build.md`, `2026-05-14-0900-q1-review-prep.md`.
Keep logs focused. Capture the goal, what was read/done, decisions, outputs, open threads, and the next step. This matches the vault's `_agent/templates/session-log-template.md`. Keep logs focused. Capture the goal, what was read/done, decisions, outputs, open threads, and the next step. This matches the vault's `_agent/templates/session-log-template.md`.
@@ -77,21 +77,21 @@ client: claude-code
# Session Log # Session Log
## Goal ## Goal
Build and package the echo-memory CoWork plugin against the live vault. Build and package the quicksilver CoWork plugin against the live vault.
## Notes Read ## Notes Read
- [[BOOTSTRAP]], [[STRUCTURE]], [[_agent/memory/semantic/operator-preferences]] - [[_agent/memory/semantic/operator-preferences]]
## Actions Taken ## Actions Taken
Verified the REST API end-to-end, confirmed the scaffold copied into the live vault, Verified the REST API end-to-end, confirmed the scaffold copied into the live vault,
created missing empty folders, and built the plugin (SKILL + 4 reference files). created missing empty folders, and built the plugin (SKILL + reference files).
## Decisions Made ## Decisions Made
- Vault addressed at root — ECHO is a dedicated vault. - Vault addressed at root — Quicksilver is a dedicated vault.
- Key hardcoded in the plugin (not in the vault) — personal plugin, per the reference pattern. - Credentials read from the local config file (`~/.quicksilver/quicksilver-config.json`); the API key is never stored in the vault.
## Outputs Created ## Outputs Created
- `echo-memory.plugin` — installable CoWork plugin - `quicksilver.plugin` — installable CoWork plugin
## Open Threads ## Open Threads
- [ ] Validate Claude Code direct filesystem access to the vault host. - [ ] Validate Claude Code direct filesystem access to the vault host.
@@ -1,6 +1,6 @@
# Vault Layout & Frontmatter Conventions # Vault Layout & Frontmatter Conventions
**This document is canonical.** The ECHO vault holds data only — there are no `CLAUDE.md` / `STRUCTURE.md` / `BOOTSTRAP.md` / `index.md` control docs in it. Layout, taxonomy, and frontmatter conventions live here in the plugin; the bootstrap procedure (`references/bootstrap.md`) builds the tree below into any empty vault. **This document is canonical.** The Quicksilver vault holds data only — there are no `CLAUDE.md` / `STRUCTURE.md` / `BOOTSTRAP.md` / `index.md` control docs in it. Layout, taxonomy, and frontmatter conventions live here in the plugin; the bootstrap procedure (`references/bootstrap.md`) builds the tree below into any empty vault.
## Folder Map (root-addressed) ## Folder Map (root-addressed)
@@ -33,7 +33,7 @@
├── reviews/ ← weekly / monthly / quarterly / annual ├── reviews/ ← weekly / monthly / quarterly / annual
├── archive/ ← notes / projects / imports ├── archive/ ← notes / projects / imports
└── _agent/ └── _agent/
├── echo-vault.md ← bootstrap marker: schema_version + bootstrap date (plugin-owned; the "is this vault set up?" probe) ├── quicksilver-vault.md ← bootstrap marker: schema_version + bootstrap date (plugin-owned; the "is this vault set up?" probe)
├── context/ ← current-context.md and task bundles ├── context/ ← current-context.md and task bundles
├── memory/ ├── memory/
│ ├── working/ ← transient, time-boxed │ ├── working/ ← transient, time-boxed
@@ -100,14 +100,14 @@ not rewrite frontmatter — the append goes after existing content. To change
The profile analog. Canonical headings: The profile analog. Canonical headings:
- `## Operator` — who Jason is (one paragraph) - `## Operator` — who the operator is (one paragraph), captured at first run
- `## Fact / Pattern`**promoted, deduped rules.** No date prefix. Timeless. - `## Fact / Pattern`**promoted, deduped rules.** No date prefix. Timeless.
- `## Observations`**timestamped raw observations.** Date-prefixed lines (`- 2026-06-06: ...`). Default landing zone for new evidence. - `## Observations`**timestamped raw observations.** Date-prefixed lines (`- 2026-06-06: ...`). Default landing zone for new evidence.
- `## Evidence` — citations/links supporting the rules - `## Evidence` — citations/links supporting the rules
- `## Recommendation or Implication` — how the rules should shape behavior - `## Recommendation or Implication` — how the rules should shape behavior
- `## Review Notes` — confidence / last review date - `## Review Notes` — confidence / last review date
Append observed facts under `## Observations` by default. Promote to `## Fact / Pattern` (dropping the date) once a pattern stabilizes. "The operator" is Jason — he is both operator and architect of this vault. Append observed facts under `## Observations` by default. Promote to `## Fact / Pattern` (dropping the date) once a pattern stabilizes. The operator's name is captured at first run (stored in the local config file and the vault marker's `operator:` field); write memory in third person using that name.
### projects/active/\<slug\>.md ### projects/active/\<slug\>.md
@@ -142,7 +142,7 @@ One paragraph, kept fresh via PATCH replace.
### sessions/YYYY-MM-DD-HHMM-\<slug\>.md ### sessions/YYYY-MM-DD-HHMM-\<slug\>.md
See `session-log-template.md`. ECHO uses an **HHMM time component** in the filename — this is **canonical, not optional**. The four-digit local-time component makes filenames lex-sort in true chronological order, which the loading procedure relies on. Older session logs without HHMM exist; leave them alone, but every new one must use the full `YYYY-MM-DD-HHMM-<slug>.md` form. See `session-log-template.md`. Quicksilver uses an **HHMM time component** in the filename — this is **canonical, not optional**. The four-digit local-time component makes filenames lex-sort in true chronological order, which the loading procedure relies on. Older session logs without HHMM exist; leave them alone, but every new one must use the full `YYYY-MM-DD-HHMM-<slug>.md` form.
### decisions/by-date/YYYY-MM-DD-\<slug\>.md ### decisions/by-date/YYYY-MM-DD-\<slug\>.md
@@ -150,7 +150,7 @@ ADR-style: Context → Decision → Consequences. If the decision belongs to an
### people/\<name\>.md ### people/\<name\>.md
`type: person`. Use lowercase kebab-case for the slug (e.g. `jason-stedwell.md`). `type: person`. Use lowercase kebab-case for the slug (e.g. `alex-rivera.md`).
--- ---
@@ -1,12 +1,12 @@
# ECHO Memory Vault # Quicksilver Memory Vault
This Obsidian vault is the persistent memory substrate ("second brain") for its operator. It is read and written across Claude / CoWork sessions through the Obsidian Local REST API. This Obsidian vault is the persistent memory substrate ("second brain") for its operator. It is read and written across Claude / CoWork sessions through the Obsidian Local REST API.
**This vault holds data, not logic.** All operating procedure — how the vault is bootstrapped, how notes are routed, the taxonomy, frontmatter conventions, and safety rules — lives in the **`echo-memory` plugin**, which is the single source of truth. There are intentionally no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` control docs in this vault; updating or porting ECHO means updating or installing the plugin, not editing files here. **This vault holds data, not logic.** All operating procedure — how the vault is bootstrapped, how notes are routed, the taxonomy, frontmatter conventions, and safety rules — lives in the **`quicksilver` plugin**, which is the single source of truth. There are intentionally no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` control docs in this vault; updating or porting Quicksilver means updating or installing the plugin, not editing files here.
- **Layout:** see the plugin's `references/vault-layout.md`. - **Layout:** see the plugin's `references/vault-layout.md`.
- **Operating contract & safety:** see the plugin's `references/operating-contract.md`. - **Operating contract & safety:** see the plugin's `references/operating-contract.md`.
- **Bootstrap / repair:** see the plugin's `references/bootstrap.md`. - **Bootstrap / repair:** see the plugin's `references/bootstrap.md`.
- **Version marker:** `_agent/echo-vault.md` records the schema version and bootstrap date. - **Version marker:** `_agent/quicksilver-vault.md` records the schema version and bootstrap date.
Folders: `inbox/`, `journal/`, `projects/`, `areas/`, `resources/`, `decisions/`, `reviews/`, `archive/`, and the agent subtree `_agent/`. Folders: `inbox/`, `journal/`, `projects/`, `areas/`, `resources/`, `decisions/`, `reviews/`, `archive/`, and the agent subtree `_agent/`.
@@ -1,3 +1,3 @@
# Inbox — Captures # Inbox — Captures
Quick captures land here as date-prefixed lines (`- {{DATE}}: <thing>`), one per line, via POST. Triage routes durable items to their proper home (see the echo-memory skill's Inbox Triage). Don't delete originals on triage — the processing log is the audit trail. Quick captures land here as date-prefixed lines (`- {{DATE}}: <thing>`), one per line, via POST. Triage routes durable items to their proper home (see the quicksilver skill's Inbox Triage). Don't delete originals on triage — the processing log is the audit trail.
@@ -13,7 +13,8 @@ last_reviewed: {{DATE}}
# Operator Preferences # Operator Preferences
## Operator ## Operator
<!-- One paragraph: who the operator is. Leave for the operator to confirm; do not fabricate. --> {{OPERATOR}} — {{ROLE}}.
<!-- Captured at first run. Expand to one paragraph as facts are confirmed; do not fabricate beyond what the operator stated. -->
## Fact / Pattern ## Fact / Pattern
<!-- Promoted, deduped, timeless rules. No date prefix. Add only when a rule is stable. --> <!-- Promoted, deduped, timeless rules. No date prefix. Add only when a rule is stable. -->
@@ -8,12 +8,15 @@ agent_written: true
source_notes: [] source_notes: []
schema_version: 1 schema_version: 1
bootstrapped: {{DATE}} bootstrapped: {{DATE}}
managed_by: echo-memory-plugin managed_by: quicksilver-plugin
operator: {{OPERATOR}}
--- ---
# ECHO Vault Marker # Quicksilver Vault Marker
This file marks the vault as bootstrapped by the **echo-memory plugin** and records its schema version. The plugin's loading procedure GETs this file as its "is this vault set up?" probe; a `404` triggers a fresh bootstrap. This file marks the vault as bootstrapped by the **quicksilver plugin** and records its schema version. The plugin's loading procedure GETs this file as its "is this vault set up?" probe; a `404` triggers a fresh bootstrap.
- `schema_version` — bumped by the plugin when the vault layout changes; a mismatch is the hook for a migration pass (see `references/bootstrap.md`). - `schema_version` — bumped by the plugin when the vault layout changes; a mismatch is the hook for a migration pass (see `references/bootstrap.md`).
- `operator` — the vault owner's name, captured at first run. Non-secret identity only.
- **No secret is ever stored here.** The API endpoint and key live in the local config file (`~/.quicksilver/quicksilver-config.json`), never in the vault.
- Do not hand-edit. The plugin owns this file. - Do not hand-edit. The plugin owns this file.