chorus/docs/USAGE.md

CHORUS Memory — Usage Guide

Written for any group member coming to CHORUS (or back to it after a break). Current as of v2.0.0-rc.1, July 2026. Setup itself is in ONBOARDING.md.

CHORUS gives Claude persistent group memory across sessions. Everything durable — people, companies, projects, decisions, session history, each member's preferences — lives as markdown notes in one shared Obsidian vault, read and written over the Obsidian Local REST API. The whole team's sessions work against the same knowledge graph, and every agent write is attributed (author: <member>), so you always know who knows what.

The short version of how to use it: you mostly don't have to do anything. The system loads itself at session start (and onboards you automatically on your very first session), and nudges itself to save at session end. The slash commands below are for when you want to drive it explicitly.

---

One-time setup

You were handed a per-member baked plugin (chorus-memory-2.x-<you>.plugin). Just install it — your member id, the endpoint, and the vault key are baked in. No config file, no key pasting, works on desktop and in every CoWork session. Treat the file like a password: it contains the live vault key. Don't share or commit it.

Verify: run /chorus-doctor. Green across the board (Python, endpoint, key, member id, group, vault reachable, bootstrapped schema 5) means you're live. Your first load creates your _agent/members/<you>/ namespace and adds you to the group roster — nothing to do on your side.

---

Day-to-day usage

What happens automatically

• Session start — a hook runs the cold-start load and injects memory into context: the group profile, your preferences, your current scope, your last session, today's shared journal note, and both inbox depths (yours + the group's).
• Session end — if the session was substantive and nothing was saved, a hook nudges (once) to run /chorus-reflect and write the session log. Reflection always previews before writing — nothing lands without your OK.
• If the vault is unreachable, writes queue to a local outbox and replay automatically next time it's up; reads fall back to a cached last-known-good.

The slash commands

Command	When to use it
/chorus-load	Manually load memory context (the session-start hook usually does this). load --all-members adds a group-wide view: every member's scope and last session.
/chorus-save <thing>	Save something right now: "remember the Henagar tower password is in the vault", "log that we decided X". Routes it to the right note automatically, attributed to you.
/chorus-recall <topic>	Ask what the GROUP's memory knows about a topic — including things teammates saved. Returns ranked matches plus their linked neighbourhood; add --author <member> to see one person's notes only.
/chorus-reflect	End-of-session sweep: extracts durable facts, decisions, and new entities from the conversation, previews, applies on confirm. The main way memory grows.
/chorus-triage	Empty the inboxes — yours and the group's: classifies each capture, previews destinations, routes accepted items with a who-routed-what audit trail.
/chorus-doctor	Readiness check — Python, vault reachability, auth, member id, bootstrap/schema, key source. First stop when anything seems off.
/chorus-health	Full vault lint: routing violations, broken wikilinks, orphans, per-member stale scopes and aging inboxes, unattributed agent notes, index drift.
/chorus-sweep	Bring the vault up to the current plugin spec after an upgrade — rebuilds indexes, backfills frontmatter, fixes one-way links. Dry-run by default.

A typical session

1. Start a conversation — memory loads itself. Claude knows who you are, what the group is, what you were doing, and what happened in your last session.
2. Work normally. Say "save that" / "remember this" whenever something durable comes up. Not sure where it belongs? It lands in your inbox; something the team should see lands in the group inbox.
3. At the end, accept the reflection nudge (or run /chorus-reflect). Confirm the preview. Done — your next session picks up from here, and your teammates' sessions can already see what you saved.

Group etiquette (the short list)

• Shared knowledge is everyone's. Projects, people, companies, decisions — read them, update them (your updates are member-tagged), link to them.
• Namespaces are personal. Never edit another member's _agent/members/<id>/ files. A fact about a person goes in resources/people/; a teammate's preference is theirs to record.
• The duplicate gate is a teammate detector. If a save is blocked with "likely already exists — created by jason", that's the system telling you the group already tracks it. Merge into the existing note.
• Everything is group-visible. One vault, one key. Truly private material belongs in a personal vault, not CHORUS.

---

What the memory system can do

Smart, attributed, deduplicating capture. One capture call routes content to its canonical home via a shared entity index, stamps complete frontmatter (status, tags, timestamps, author), cross-links every entity it mentions, and writes a member-tagged line on the team's daily log. Names resolve through aliases and fuzzy matching; a pre-write duplicate gate stops near-duplicates before they exist and names whose entity you collided with.

Real retrieval over the whole group's knowledge. Recall fuses BM25 full-text search with graph expansion along note links, over entities and every member's session logs and the journal. Ranking is freshness- and status-aware. Filter to one member with --author.

Structured memory model. Working / episodic / semantic layers plus the group profile, per-member scope + preferences + inbox + sessions, an append-only shared journal with rollups, and PARA-style projects/areas/resources/decisions. A machine-readable routing manifest defines what may be written where, and the linter enforces it.

Durability and safety. Every write is HTTP-status-checked and read-back-verified. Appends are idempotent. Offline writes queue and replay. Shared indexes are lock-guarded with retry, and lock owners are member-attributed. The per-member namespacing means teammates' sessions can't clobber your scope or heartbeat even in principle.

Self-maintaining, self-onboarding. The vault bootstraps itself from empty, onboards new members on their first load, migrates its own schema on version bumps, and /chorus-sweep + /chorus-health keep the graph honest.

---

Troubleshooting

Symptom	Fix
NOT CONFIGURED banner / doctor shows red config	Your build isn't baked or the config is missing this machine — see ONBOARDING.md, or ask the vault admin for your baked build.
Vault unreachable	Obsidian + the Local REST API + the proxy at chorusapi.mpm.to must be up. Meanwhile writes queue safely and replay on reconnect.
Save blocked with "duplicate gate … created by <member>" (exit 76)	Not an error — the group already tracks that entity. Merge into the existing note (--merge-into <slug>), or force-create if genuinely distinct.
Memory feels stale or inconsistent	/chorus-health to see what's off, /chorus-sweep to repair.
Inboxes keep getting mentioned at load	/chorus-triage — one pass empties both.
Anything else weird	/chorus-doctor first, then ask the vault admin.