Internal Tooling Brief · CoWork / Claude Plugin
Persistent, cross-session memory for Claude and CoWork. The assistant loads your context, decisions, and projects at the start of every session. No re-explaining.
Claude forgets everything when a chat closes. ECHO fixes that. It gives the assistant a structured Obsidian vault that it reads at session start and writes to as you work. The result: memory you can trust and retrieve, running identically on every machine.
Every session starts cold. You re-explain who you are, what you're building, and what was decided last week. Notes scatter, duplicate, or land in the wrong place. Worse, writes fail silently — you think a note saved when it didn't. ECHO closes all four gaps.
Profile, active scope, recent sessions, and open projects load automatically at session start. No re-briefing.
One capture call files a note, stamps it, indexes it, and cross-links it. No manual filing.
Ask about a topic. Get the note plus everything linked to it — people, decisions, meetings. Not one fragment.
Most of the time you do nothing. The skill fires on phrases like "remember that," "what do you know about me," and "log this decision," and loads your context at the start of real work. For direct control, use the eight slash commands:
/echo-loadCold-start read — profile, scope, recent sessions, inbox./echo-saveRoute and persist a memory to its correct home in one call./echo-recallPull a topic plus its linked neighbourhood./echo-reflectExtract durable takeaways from the session for one-tap capture./echo-triageDrain the inbox — route aging captures to their homes./echo-healthRun the linter — surface drift, broken links, orphans./echo-sweepBring an upgraded vault up to spec — index plus links./echo-doctorReadiness check — Python, reachability, auth, schema.ECHO loads your profile, active scope, last session, today's note, and inbox. It confirms scope before doing anything.
Mention a decision, a project, or a preference. Say "remember that" and it's filed and cross-linked.
"What do we know about the ALABAMA wISP rollout?" returns the project note and its linked people, decisions, and meetings.
ECHO writes a one-line Agent-Log entry and a session log, then drops a heartbeat pointer to resume from next time.
echo.py write-key <token> or the env var). Point the plugin at an empty vault and it builds the full structure itself.One principle drives the design: the plugin is the single source of truth. All behavior — bootstrap logic, the operating contract, taxonomy, routing rules, and note templates — ships inside the plugin. The vault holds data only. That makes the system self-bootstrapping, updatable in one place, and portable across machines.
Sessions talk to the plugin. The plugin owns all logic and is the only thing that touches the vault, through one validated client. The vault stores structured markdown — nothing else.
| Component | What it does |
|---|---|
| echo.py | The validated client and CLI. Every read and write injects auth, checks HTTP status, retries transient errors, and read-back-verifies the result. A failed write fails loud, not silent. |
| capture / recall / resolve / link | The do-it-for-me layer. capture routes, stamps, indexes, auto-links, and logs in one call. recall returns a topic's linked neighbourhood. |
| Entity index | A slug→{path, kind, aliases} registry. Turns routing into an O(1), alias-aware lookup instead of a fuzzy search. |
| Hybrid recall | Local BM25 over note bodies, fused with decayed graph expansion. Keyword relevance and link structure, together. |
| Offline queue + cache | Vault unreachable? Writes queue to a local write-ahead log and replay idempotently later. Reads fall back to a last-known-good cache. |
| routing.json + linter | A machine-readable manifest of what writes where, enforced by a read-only checker — drift, broken links, orphans, frontmatter integrity. |
| scaffold/ + bootstrap | Templates and seeds that stand up an empty vault deterministically and idempotently. |
ECHO mirrors a working memory model: working (transient state), episodic (what happened, when), semantic (durable facts and preferences), and context (the active focus). Daily content lives in plain folders — projects/, journal/, decisions/, resources/. The agent's bookkeeping sits under _agent/.
A credential-free A/B harness compares the plugin before (hand-built REST calls from the old skill docs) and after (the shipped validated client) across six representative operations, with deterministic fault injection. It measures the plumbing: token cost of the I/O layer and the rate of silent write failures.
| Metric | Before (0.6) | After (0.7+) | Delta |
|---|---|---|---|
| Generated tokens (I/O layer) | 608 | 174 | −71% |
| Silent failures | 4 | 0 | −4 |
| Duplicate lines written | 1 | 0 | −1 |
| Silent-error-free ops | 1 / 5 | 5 / 5 | +4 |
| Effective tokens (incl. recovery) | 6,608 | 334 | −95% |
Source: eval/run_eval.py (mock OLRAPI, chars/token = 4.0). Generated-token counts are a proxy for the I/O layer only. "Effective tokens" applies a tunable recovery penalty on top of the hard silent-failure count.
A failed write that looks like success is the worst outcome for a memory system. You trust a note that never saved. The old approach hid four across six operations. The validated client surfaces every one — non-zero exit, retry, read-back verify — so the assistant recovers instead of moving on. That is the line between memory and memory you can trust.
Before creating a note, ECHO searches the whole vault for the slug and title. No duplicates scattered across folders.
Reads before appending, skips on an exact whole-line match. A retry never duplicates an entry.
A cooperative lock plus re-read-merge closes the race when Claude Code and CoWork write at once.
The operating contract forbids inventing facts or decisions, mass restructuring, and storing secrets in notes.
Vault down? ECHO says so once, queues writes, and proceeds. No retry storms.
Deterministic bootstrap, migration, and sweep scripts keep any vault on the current spec.
| Version | Milestone |
|---|---|
| 0.3–0.4 | Source promoted to a tracked tree. Search-first writes, project lifecycle, scope switching, monthly vault-health. |
| 0.5 | Self-bootstrap. The plugin becomes the single source of truth; vault migrated to data-only. |
| 0.7 | Validated client (echo.py), routing manifest plus linter, A/B eval harness: −71% I/O tokens, 4→0 silent failures. |
| 0.8 | Toolchain ported to pure Python. Runs identically on Windows, macOS, Linux. |
| 0.9 | Entity index, hybrid recall, bidirectional auto-linking, graph-health checks. |
| 1.0 | "Memory you can trust and retrieve." Hybrid BM25+graph recall, offline durability, concurrency hardening, reflection capture, secret hardening. CI across 3 OSes × 2 Python versions. |