Phase 1: mechanical echo→chorus rename with back-compat shims

Identity rename, no behavior change (CHORUS-PLAN.md Phase 1): - Plugin echo-memory → chorus-memory: manifest (v2.0.0-alpha.1), skill dir, 16 scripts (chorus.py, chorus_config.py, …), EchoError → ChorusError, /chorus-* commands, hook paths, docs, scaffold seeds, eval harness, build.py. Docs endpoint → chorusapi.mpm.to. - Env ECHO_* → CHORUS_*; config → ~/.claude/chorus-memory/config.json; state dir → ~/.chorus-memory/; marker → _agent/chorus-vault.md. Back-compat shims (one major version): - chorus_config aliases legacy ECHO_* env at import; reads a legacy echo-memory config.json when no CHORUS config exists (writes never land there); doctor/config report the legacy source. - State dir honors an existing ~/.echo-memory when the new dir is absent (offline queue not stranded). - Marker dual-probe in load/doctor/bootstrap/lint/sweep/migrate: a pre-fork _agent/echo-vault.md counts as bootstrapped; bootstrap repair won't write a second marker; routing gains agent-marker-legacy (GET). Verified: 25/25 unit tests, scaffold + routing-sync checks, 4 mock e2e suites, run_eval metrics unchanged, +6 shim smoke tests green. Rebuilt chorus-memory.plugin (79 entries). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-21 13:35:51 -05:00
parent ff2f2efd0b
commit d366ca4032
98 changed files with 1312 additions and 1164 deletions
@@ -0,0 +1,122 @@
+# chorus-memory
+
+Persistent memory for Claude via the **CHORUS** Obsidian vault, using the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api).
+
+Reads and writes notes across Claude/CoWork sessions through direct REST calls, routed through a bundled validated client (`scripts/chorus.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). The plugin is **user-agnostic**: the vault owner, endpoint, and API key are not shipped in it — each machine supplies them through a local config file (see **Configuration**).
+
+Architected 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/chorus-memory/`. The vault itself holds **data only**: there are no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs in it. This makes CHORUS 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
+- **One-call `capture`** routes a memory to its canonical home, stamps **complete** frontmatter (kind-default `status`, kind-seeded `tags`), 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. Updates keep the **whole body**; a title that strongly resembles an existing entity **stops at a duplicate gate** (exit 76 — `--merge-into <slug>` / `--force`) instead of spawning a near-duplicate
+- **`recall`** returns a topic's matching notes *and* their one-hop linked neighbourhood (Related links + `source_notes`) — the corpus spans the entity graph **plus session logs and journal notes** (down-weighted), ranked by BM25 × freshness × status so live notes outrank stale ones; **`resolve`** maps any mention to its canonical path; **`link`** adds reciprocal cross-links; **`triage`** routes aging inbox captures with an automatic processing-log audit trail
+- 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), 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/chorus-memory/references/bootstrap.md`
+- Exposes `/chorus-load`, `/chorus-save`, `/chorus-recall`, `/chorus-triage`, `/chorus-health`, `/chorus-sweep`, `/chorus-reflect`, `/chorus-doctor` slash commands as explicit entry points, and coordinates concurrent Claude/CoWork sessions via a cooperative advisory lock
+- **Ships session hooks** (`hooks/hooks.json`): SessionStart auto-runs the cold-start load into context, and Stop nudges `/chorus-reflect` once per substantive session — the load/reflect discipline fires deterministically instead of depending on the model remembering (reflection still previews before writing)
+
+## Configuration
+
+The plugin ships **no** owner, endpoint, or key. On each machine it installs on, provide a machine-local JSON config:
+
+```
+~/.claude/chorus-memory/config.json        (honors $CLAUDE_CONFIG_DIR; file path overridable with $CHORUS_CONFIG)
+{
+  "owner":    "Full Name — how the agent refers to the vault owner (third person)",
+  "endpoint": "https://your-obsidian-rest-endpoint.example.com",
+  "key":      "<obsidian-local-rest-api-bearer-token>"
+}
+```
+
+Set it up on a fresh install by copying the bundled template and filling it in, or via the client:
+
+```bash
+python3 skills/chorus-memory/scripts/chorus.py config init     # writes the template if absent → edit it
+python3 skills/chorus-memory/scripts/chorus.py config set --owner "…" --endpoint "https://…" --key "…"
+python3 skills/chorus-memory/scripts/chorus.py config           # show resolved config (key redacted) + source
+```
+
+Per field, an environment variable overrides the file: `CHORUS_OWNER`, `CHORUS_BASE` (endpoint), `CHORUS_KEY`. `config init` writes the template (shown above) when the file is absent; a copy also ships at the repo root (`chorus-memory.config.template.json`). The config is **never committed** and **never written into a vault note**; the bearer key stays out of the plugin tree entirely.
+
+## Vault layout (root-addressed)
+
+```
+/vault/
+├── README.md     ← thin human signpost (not read for routing)
+├── inbox/        (captures, imports, processing-log)
+├── journal/      (daily, weekly, monthly, quarterly, annual, templates) — one time-series stream; rollups live here, not in a separate reviews/ tree
+├── projects/     (active, incubating, on-hold, archived)
+├── areas/        (business, personal, learning, systems)
+├── resources/    (companies, concepts, references, people, meetings)
+├── decisions/    (by-date)
+└── _agent/
+    ├── chorus-vault.md   ← bootstrap marker (schema_version + date)
+    ├── context/        ← task-scoped context bundles
+    ├── memory/         ← working / episodic / semantic
+    ├── sessions/       ← YYYY-MM-DD-HHMM-<slug>.md
+    ├── health/         ← YYYY-MM-vault-health.md (monthly self-maintenance audit)
+    ├── 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: chorus-load, chorus-save, chorus-recall, chorus-triage, chorus-health, chorus-sweep, chorus-reflect, chorus-doctor
+skills/chorus-memory/
+├── SKILL.md                       ← operating procedure (authoritative)
+├── references/
+│   ├── operating-contract.md      ← durable principles + safety + concurrency
+│   ├── bootstrap.md               ← bootstrap / repair / migrate an empty vault
+│   ├── vault-layout.md            ← canonical layout + frontmatter
+│   ├── routing-map.md             ← complete endpoint→logic map (human authority)
+│   ├── api-reference.md           ← REST endpoint patterns + routing map
+│   └── session-log-template.md
+├── scripts/                       ← pure Python; run with python3 (Windows: python / py -3)
+│   ├── chorus.py                    ← validated client + high-level CLI (capture/resolve/recall/link/load/scope/lock/config)
+│   ├── chorus_config.py             ← resolves owner/endpoint/key from the machine-local config (env-overridable)
+│   ├── chorus_index.py              ← entity index (registry, resolve, name→path map)
+│   ├── chorus_links.py              ← cross-link primitives (Related parsing, bidirectional linking)
+│   ├── chorus_ops.py                ← high-level ops (capture, recall, resolve, link, agent-log)
+│   ├── routing.json               ← canonical machine-readable route manifest (linter enforces it)
+│   ├── 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_chorus_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  chorus-vault.md
+    ├── templates/  (8 note templates)
+    └── anchors/    (operator-preferences, current-context, inbox seeds)
+```
+
+## Skills & commands
+
+| Skill | Triggers |
+|-------|----------|
+| `chorus-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 |
+
+| Command | Does |
+|---------|------|
+| `/chorus-load` | Cold-start context read (profile, scope, latest session, today, inbox) |
+| `/chorus-save <text>` | Route + persist via one-call `capture` (index-resolved, auto-linked) |
+| `/chorus-recall <query>` | Recall a topic's matching notes plus their linked neighbourhood |
+| `/chorus-triage` | Drain aging inbox captures to their homes, logging each move |
+| `/chorus-health` | Run `vault_lint.py` and summarize invariant + graph-health violations |
+| `/chorus-sweep` | Bring the vault up to current spec (build index + symmetrize links) |
+| `/chorus-reflect` | Extract durable items from the session, preview, and apply on approval |
+| `/chorus-doctor` | Readiness check: config, endpoint reachability, auth, bootstrap/schema |
+
+## 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 from the Claude/CoWork session environment to the endpoint configured in `~/.claude/chorus-memory/config.json`
+- A machine-local config (`~/.claude/chorus-memory/config.json`) supplying the vault owner, endpoint, and API key — see **Configuration**