ver 0.9
This commit is contained in:
jason
@@ -2,17 +2,18 @@
|
||||
|
||||
Persistent memory for Claude via the **ECHO** 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, but routed through a bundled validated client (`scripts/echo.sh`) that status-checks every write. 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, but routed through a bundled validated client (`scripts/echo.py`) that status-checks every write. The toolchain is **pure Python**, so it runs identically on Windows, macOS, and Linux (only a Python 3 interpreter is needed — no bash). Built for **Jason Stedwell** (Director of Technical Services / Systems Engineer, MPM / ALABAMA wISP), who is both the operator and the architect of this vault.
|
||||
|
||||
**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.
|
||||
|
||||
## What it does
|
||||
|
||||
- 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
|
||||
- **One-call `capture`** routes a memory to its canonical home, stamps frontmatter, indexes it, auto-links any entity it mentions, and logs it — driven by a machine-maintained **entity index** so routing is an alias-aware lookup, not a fuzzy search
|
||||
- **`recall`** returns a topic's matching notes *and* their one-hop linked neighbourhood (Related links + `source_notes`) for comprehensive context; **`resolve`** maps any mention to its canonical path; **`link`** adds reciprocal cross-links
|
||||
- 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 via `scripts/bootstrap.sh` / `scripts/migrate.sh` — see `skills/echo-memory/references/bootstrap.md`
|
||||
- Exposes `/echo-load`, `/echo-save`, `/echo-triage`, `/echo-health` slash commands as explicit entry points, and coordinates concurrent Claude/CoWork sessions via a cooperative advisory lock
|
||||
- **Bootstraps an empty vault from the bundled `scaffold/`** (folders, templates, anchor seeds, marker), repairs/migrates an existing one via `scripts/bootstrap.py` / `scripts/migrate.py`, and brings an upgraded vault up to spec (index + cross-links) via `scripts/sweep.py` — see `skills/echo-memory/references/bootstrap.md`
|
||||
- Exposes `/echo-load`, `/echo-save`, `/echo-recall`, `/echo-triage`, `/echo-health`, `/echo-sweep` slash commands as explicit entry points, and coordinates concurrent Claude/CoWork sessions via a cooperative advisory lock
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -43,13 +44,14 @@ The endpoint presents a **valid TLS certificate**, so `-k` is not required. The
|
||||
├── templates/ ← canonical note templates (seeded from the plugin's scaffold/)
|
||||
├── skills/ ← active / archived
|
||||
├── heartbeat/ ← last-session.md orientation pointer (read at load, written at session end)
|
||||
├── index/ ← entities.json — machine-maintained slug→{path,kind,aliases} registry
|
||||
└── locks/ ← vault.lock — cooperative advisory multi-writer lock
|
||||
```
|
||||
|
||||
Control logic and the master scaffold live in the plugin, not the vault:
|
||||
|
||||
```
|
||||
commands/ ← slash commands: echo-load, echo-save, echo-triage, echo-health
|
||||
commands/ ← slash commands: echo-load, echo-save, echo-recall, echo-triage, echo-health, echo-sweep
|
||||
skills/echo-memory/
|
||||
├── SKILL.md ← operating procedure (authoritative)
|
||||
├── references/
|
||||
@@ -59,12 +61,18 @@ skills/echo-memory/
|
||||
│ ├── routing-map.md ← complete endpoint→logic map (human authority)
|
||||
│ ├── api-reference.md ← REST endpoint patterns + routing map
|
||||
│ └── session-log-template.md
|
||||
├── scripts/
|
||||
│ ├── echo.sh ← validated API client (auth, status-check, retry, verify, lock, scope)
|
||||
├── scripts/ ← pure Python; run with python3 (Windows: python / py -3)
|
||||
│ ├── echo.py ← validated client + high-level CLI (capture/resolve/recall/link/load/scope/lock)
|
||||
│ ├── echo_index.py ← entity index (registry, resolve, name→path map)
|
||||
│ ├── echo_links.py ← cross-link primitives (Related parsing, bidirectional linking)
|
||||
│ ├── echo_ops.py ← high-level ops (capture, recall, resolve, link, agent-log)
|
||||
│ ├── routing.json ← canonical machine-readable route manifest (linter enforces it)
|
||||
│ ├── vault-lint.sh ← read-only invariant checker (monthly Vault Health pass)
|
||||
│ ├── bootstrap.sh ← deterministic, idempotent vault setup/repair
|
||||
│ └── migrate.sh ← deterministic schema migration (dry-run by default)
|
||||
│ ├── vault_lint.py ← read-only invariant + graph-health checker (Vault Health)
|
||||
│ ├── check_routing.py ← verifies routing docs stay in sync with routing.json (offline)
|
||||
│ ├── test_echo_client.py ← offline regression tests + the routing-sync guard
|
||||
│ ├── bootstrap.py ← deterministic, idempotent vault setup/repair
|
||||
│ ├── migrate.py ← deterministic schema migration (dry-run by default)
|
||||
│ └── sweep.py ← bring an upgraded vault up to spec (build index + symmetrize links)
|
||||
└── scaffold/ ← verbatim files the bootstrap writes into the vault
|
||||
├── README.vault.md echo-vault.md
|
||||
├── templates/ (8 note templates)
|
||||
@@ -80,11 +88,14 @@ skills/echo-memory/
|
||||
| Command | Does |
|
||||
|---------|------|
|
||||
| `/echo-load` | Cold-start context read (profile, scope, latest session, today, inbox) |
|
||||
| `/echo-save <text>` | Route + persist content to its canonical home (search-first, idempotent) |
|
||||
| `/echo-save <text>` | Route + persist via one-call `capture` (index-resolved, auto-linked) |
|
||||
| `/echo-recall <query>` | Recall a topic's matching notes plus their linked neighbourhood |
|
||||
| `/echo-triage` | Drain aging inbox captures to their homes, logging each move |
|
||||
| `/echo-health` | Run `vault-lint.sh` and summarize invariant violations |
|
||||
| `/echo-health` | Run `vault_lint.py` and summarize invariant + graph-health violations |
|
||||
| `/echo-sweep` | Bring the vault up to current spec (build index + symmetrize links) |
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Python 3** available in the session environment (the scripts use only the standard library; invoke as `python3`, or `python` / `py -3` on Windows)
|
||||
- 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
|
||||
|
||||
Reference in New Issue
Block a user