chorus/CHORUS-PLAN.md

# CHORUS — Group-Based Memory: Conversion Plan

**Fork of:** `jason/echo` (ECHO v1.5.1, schema 4) → `jason/chorus`
**Goal:** convert the single-operator ECHO memory plugin into CHORUS — one shared
Obsidian vault serving a **group of members**, with per-member identity,
attribution, and isolation of the churn-prone per-person state, while keeping the
shared knowledge graph (projects, areas, resources, decisions) communal.

**Naming metaphor:** ECHO is one voice reflected back; CHORUS is many voices in
one performance.

---

## 1. What the review found

ECHO is ~4,800 LOC of pure-stdlib Python (18 scripts) + a large doc surface
(SKILL.md ~456 lines, 6 references, 8 commands, 15 scaffold seeds). The
architecture is already favorable for this conversion:

- **Identity is barely wired in.** `echo.py` loads `OWNER` from config but never
  actually consumes it — attribution today is purely doc-driven ("write in third
  person about Jason"). Adding a `member` identity breaks nothing.
- **Routing is data-driven.** `routing.json` is the single source of truth for
  "what may be written where"; `vault_lint.py` and `check_routing.py` enforce it.
  Per-member paths are new route rows, not new code paths.
- **The vault is self-describing.** Bootstrap/migrate/sweep + `schema_version`
  in the marker give us a clean upgrade lever (schema 4 → 5).

The hard part is **not** identity plumbing — it's the five shared single-writer
artifacts that make no sense (or clobber) with multiple concurrent users:

| Artifact | Today | Problem in a group |
|---|---|---|
| `_agent/memory/semantic/operator-preferences.md` | One profile | Whose preferences? |
| `_agent/context/current-context.md` | One active scope for the vault | Members work on different things simultaneously |
| `_agent/heartbeat/last-session.md` | One "last session" pointer (PUT overwrite) | Race: lost updates; meaningless shared |
| `inbox/captures/inbox.md` | One shared inbox (POST append) | Append races; triage can't tell whose capture |
| `journal/daily/YYYY-MM-DD.md` `## Agent Log` | One shared heading | Duplicate-heading races; unattributed lines |

Also single-user by design: session filenames carry no author
(`YYYY-MM-DD-HHMM-<slug>.md` — two members can collide on the same minute),
frontmatter has no `author:` field anywhere, the offline queue is per-machine
with no member attribution, and the advisory lock owner is a session id, not a
person. Concurrency is advisory-only — `vault_lock()` warns and **proceeds** if
it can't acquire (echo_concurrency.py:78–81), which is acceptable for one person
on two machines but not for N people.

---

## 2. Target design

### 2.1 Identity model

- Config gains a `member` field:
  `{ "group": "...", "member": "jason", "endpoint": "https://chorusapi.mpm.to", "key": "..." }`.
  **Deployment endpoint: `https://chorusapi.mpm.to`** — the CHORUS vault gets
  its own Obsidian + Local REST API instance exposed there (separate from
  ECHO's `echoapi.alwisp.com`; the personal ECHO vault is untouched). The
  endpoint stays machine-local/baked config, never in source, same as ECHO.
  `owner` → `group`. Resolution order
  unchanged: baked > env (`CHORUS_MEMBER` etc.) > config file. Baked per-user
  builds (`build.py --bake-key --label alice`) already exist and become the
  primary **onboarding** mechanism: one artifact per member, member id baked in.
- Every agent-written note gets `author: <member>` stamped in frontmatter
  (`echo_ops._build_note`), added to the canonical frontmatter block, to
  `KIND_REQUIRED_FM` for agent-written kinds, linted by `vault_lint`, and
  backfilled by `sweep --apply` (existing notes → the migrating member).
- Lock owner and offline-queue entries carry the member id
  (`auto_owner()` → `f"{member}-{client}-{pid}"`), so contention and replay are
  attributable.

**Auth reality check:** the Obsidian Local REST API has **one bearer key per
vault**. Phase 1–4 ship with a shared key and honor-system attribution (fine for
a trusted team). Real per-member credentials/revocation would need a thin auth
proxy in front of `chorusapi.mpm.to` that maps per-member tokens → the vault
key and can inject/verify the member id. That's deliberately **out of scope**
here but the config shape (`member` + per-member baked artifacts) is designed so
the proxy slots in later without another migration.

### 2.2 Vault layout changes (schema 5)

Per-member state moves under a member namespace; shared knowledge stays where it
is.

```
_agent/
├── chorus-vault.md            ← renamed marker (schema_version: 5, managed_by: chorus-memory-plugin)
├── members/
│   └── <member>/
│       ├── preferences.md     ← was operator-preferences.md (one per member)
│       ├── current-context.md ← per-member scope + Scope History
│       ├── heartbeat.md       ← per-member last-session pointer
│       └── inbox.md           ← per-member quick-capture inbox
├── memory/
│   └── semantic/
│       └── group-profile.md   ← NEW: shared facts about the group itself
├── sessions/
│   └── <member>/YYYY-MM-DD-HHMM-<slug>.md   ← member-namespaced session logs
└── (context/, memory/, health/, index/, locks/, templates/, skills/ unchanged — shared)
```

- **Shared and unchanged:** `projects/`, `areas/`, `resources/`, `decisions/`,
  `journal/`, semantic/episodic/working memory (now with `author:`), the entity
  index, recall index, health notes.
- **Daily Agent Log stays one shared heading** (it's the group's timeline) but
  every line is member-prefixed: `- HH:MM [alice] did X`. `ensure_daily_log`
  keeps its GET→POST-heading→PATCH flow; idempotent whole-line append plus the
  member prefix makes interleaving safe and attributed. (Per-member daily notes
  were considered and rejected — the whole point of a group vault is one shared
  timeline.)
- **Inbox:** per-member capture files (`_agent/members/<id>/inbox.md`) kill the
  append race and make triage member-aware, **plus** one shared
  `inbox/captures/group.md` for unowned "someone should look at this" items
  (member-prefixed lines; routed by whoever triages first). Triage covers both:
  accepted items route to shared homes; preference-type items route to *that
  member's* `preferences.md`. Processing-log lines carry the member id.
- `resources/people/<member>.md` continues to exist for every member — the
  public "who is this person" note, distinct from their private-ish
  `preferences.md` (how the agent should behave *for them*).

### 2.3 Cold-start load (per member)

`chorus.py load` reads: marker → **group-profile** → **my** preferences → **my**
current-context → **my** heartbeat/last-session (fallback: my sessions dir) →
today's shared daily note → **my** inbox depth → **group inbox** depth. Optional `--all-members` flag
for a group-wide orientation (e.g., "what has the team been doing"). Reconcile
(inbox aging, scope drift) runs against the member's own state only.

### 2.4 Concurrency posture

Namespacing removes ~all of the contention (each member's churn-prone files are
theirs alone). What remains shared-write:

- **Entity + recall indexes** — keep `vault_lock` + `atomic_index_update`, but
  flip the lock to **required** (`required=True`) on index writes: block/retry
  briefly instead of warn-and-proceed. TTL reclaim unchanged.
- **Daily note / shared notes** — idempotent member-prefixed appends; PATCH to
  headings is last-writer-wins per line, which is acceptable for log lines.
- **Duplicate gate** — unchanged and global (dedup across the group is the
  *feature*: two members shouldn't create parallel notes for the same client).
  Gate messages name the `author` of the existing candidate.

### 2.5 Recall / reflection

- Corpus unchanged (shared graph is the point). `recall` gains an optional
  `--author <member>` filter and surfaces `author:` in hits.
- `reflect` proposals route preference items to the current member's
  `preferences.md`; everything else routes to shared homes with `author:`
  stamped. The Stop-hook nudge state stays per-machine (already is).

---

## 3. Renaming map (echo → chorus)

| Category | From | To |
|---|---|---|
| Plugin | `echo-memory` (plugin.json, skill dir, SKILL.md name) | `chorus-memory` |
| Commands | `/echo-{load,save,recall,reflect,triage,sweep,health,doctor}` | `/chorus-*` |
| Scripts | `echo*.py` (16 modules + imports everywhere) | `chorus*.py` |
| Exception | `EchoError` | `ChorusError` |
| Env vars | `ECHO_OWNER/BASE/KEY/CONFIG/TODAY/VERIFY/LOCK_TTL/TIMEOUT/WORKERS/STATE_DIR/CLIENT/DUP_GATE/REFLECT_MIN_TURNS/FRESH_HALF_LIFE` | `CHORUS_*` (+ new `CHORUS_MEMBER`) |
| Config file | `~/.claude/echo-memory/config.json` | `~/.claude/chorus-memory/config.json` |
| State dir | `~/.echo-memory/` | `~/.chorus-memory/` |
| Marker | `_agent/echo-vault.md` (hardcoded in 8 files + routing.json) | `_agent/chorus-vault.md` |
| Hooks | `hooks.json` paths ×2 incl. CoWork fallback glob | updated paths |
| Docs/branding | README, SKILL.md, references, scaffold seeds, icons | rewrite pass (cosmetic but large) |

`operator-preferences.md` is renamed as part of the **layout** change
(§2.2), not the branding pass.

---

## 4. Phased plan

### Phase 0 — Baseline (½ day)
Repo hygiene on the fork: strip stale versioned `.plugin` artifacts from the
tree (move to Gitea releases per ROADMAP-2.0), confirm `eval/` suites green
as-is, tag the fork point.

### Phase 1 — Mechanical rename (1–2 days) — DONE
Everything in §3. All existing tests pass under the new names. No behavior
change. **Deliverable:** installable `chorus-memory` plugin that is
ECHO-with-a-new-name. *(Decided post-Phase-1: CHORUS is a **clean break** —
fresh vaults on fresh machines for new users, so no ECHO back-compat: legacy
`ECHO_*` env vars, echo-memory configs, `~/.echo-memory` state, and
`_agent/echo-vault.md` markers are all ignored. Shims briefly existed and were
removed.)*

### Phase 2 — Identity plumbing (1–2 days) — DONE
`member` in config (+ `CHORUS_MEMBER`, baked-tier support, `config set --member`
with slug validation; `owner` → `group`; member REQUIRED for is_configured),
`MEMBER` global in `chorus.py`, `author:` stamping in `_build_note` + bootstrap
`{{MEMBER}}` anchor stamping + templates, canonical frontmatter docs + a
`missing-author` lint check (agent_written notes must carry `author:`; sweep
does NOT backfill — attribution can't be guessed), member-aware lock owner
(`<member>-<client>-<pid>`) and queue records, `doctor` reports member/group.
Vault layout untouched. **Deliverable:** every new write is attributed;
single-user behavior otherwise identical.

### Phase 3 — Per-member namespacing (3–5 days — the core) — DONE
Schema 5. New `LEAVES` + seeds (`members/<id>/…`, `group-profile.md`),
member-parameterized bootstrap (bootstraps *your* member subtree on first load
if the vault exists but your namespace doesn't — new members self-onboard),
`cmd_load`/`cmd_scope`/heartbeat/inbox/triage/reflect retargeted to member
paths, session logs under `sessions/<member>/`, member-prefixed Agent Log
lines, `routing.json` route rows (with `<member>` pattern segment) + retired
old paths, lint updates, `migrate.py` 4→5 (for any alpha CHORUS vaults stood
up between phases — there is no ECHO-vault adoption path; CHORUS vaults start
fresh). Docs: vault-layout.md, routing-map.md, bootstrap.md rewritten.
**Deliverable:** a real multi-member vault, bootstrapped from empty.

### Phase 4 — Shared-write hardening (1–2 days) — DONE
Lock on index writes with bounded retry/backoff (unlocked fallback only after
exhausted retries, loudly — a written note must never go unindexed), gate
messages carry the existing entity's author, `recall --author`,
`load --all-members`, concurrency docs (operating-contract.md) rewritten for
N writers. Two-member e2e suite committed as `eval/test_multimember.py`.

### Phase 5 — Docs, onboarding & eval (2–3 days) — DONE
SKILL.md rewrite (operator → member voice; group safety rules: don't edit
another member's namespace, shared notes are fair game), 8 command docs, repo +
plugin READMEs, `docs/USAGE.md` member guide. Onboarding runbook
(`docs/ONBOARDING.md`): per-member baked builds end to end. Eval: the
two-member scenarios shipped early (Phase 4) as `eval/test_multimember.py`;
all metrics re-run green. New icon (`chorus-icon.svg` + PNGs).

**Total: roughly 9–15 working days planned — all five phases delivered
2026-07-21 (v2.0.0-rc.1).** Remaining before 2.0.0 final: stand up the live
vault at `chorusapi.mpm.to` (Obsidian + Local REST API + proxy), bootstrap it,
bake and deliver the first member artifacts (see `docs/ONBOARDING.md`) — plus
the deferred auth proxy as its own later project (decision #3).

---

## 5. Decisions (settled with Jason, 2026-07-21)

1. **Journal rollups — shared.** One group rollup per period
   (`journal/weekly/YYYY-Www.md` etc.) with member-attributed bullets inside.
   No per-member rollup trees.
2. **Preference privacy — group-visible, documented.** Member `preferences.md`
   files live in the shared vault and are readable by every member (one vault,
   one key — no read ACLs possible). SKILL.md documents this explicitly;
   anything a member considers private belongs in their own personal ECHO
   vault, not CHORUS.
3. **Auth proxy — out of scope; shared key first.** Phases 1–5 ship with the
   shared vault key and honor-system attribution. The per-member token proxy
   (namespace write ACL, server-side audit, per-member revocation) is a later
   standalone project; the config shape (`member` + per-member baked
   artifacts) already accommodates it with zero plugin changes.
4. **Commands — `/chorus-*`.** Full-prefix names
   (`/chorus-load`, `/chorus-save`, …), consistent with the ECHO pattern and
   collision-free if both plugins are installed.
5. **Inboxes — per-member + shared group inbox.** Each member gets
   `_agent/members/<id>/inbox.md`; a shared `inbox/captures/group.md` holds
   unowned items (member-prefixed lines, idempotent appends), routed by
   whoever triages first. Both are probed at load and covered by triage.
6. **Clean break from ECHO** *(added post-Phase-1)*. CHORUS vaults are fresh
   vaults on fresh machines for new users — no ECHO adoption path, no legacy
   `ECHO_*` env/config/state/marker compatibility. Jason's personal ECHO vault
   continues unchanged on its own plugin and endpoint. If ECHO history is ever
   wanted in CHORUS, it would be a one-off import exercise, out of scope.