echo/echo-memory.plugin.src

echo-memory

Persistent memory for Claude via the ECHO Obsidian vault, using the Obsidian Local REST API.

Reads and writes notes across Claude/CoWork sessions through direct REST calls, 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). 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/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
• 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/echo-memory/references/bootstrap.md
• Exposes /echo-load, /echo-save, /echo-recall, /echo-triage, /echo-health, /echo-sweep, /echo-reflect, /echo-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 /echo-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/echo-memory/config.json        (honors $CLAUDE_CONFIG_DIR; file path overridable with $ECHO_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:

python3 skills/echo-memory/scripts/echo.py config init     # writes the template if absent → edit it
python3 skills/echo-memory/scripts/echo.py config set --owner "…" --endpoint "https://…" --key "…"
python3 skills/echo-memory/scripts/echo.py config           # show resolved config (key redacted) + source

Per field, an environment variable overrides the file: ECHO_OWNER, ECHO_BASE (endpoint), ECHO_KEY. config init writes the template (shown above) when the file is absent; a copy also ships at the repo root (echo-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/
    ├── echo-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: echo-load, echo-save, echo-recall, echo-triage, echo-health, echo-sweep, echo-reflect, echo-doctor
skills/echo-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)
│   ├── echo.py                    ← validated client + high-level CLI (capture/resolve/recall/link/load/scope/lock/config)
│   ├── echo_config.py             ← resolves owner/endpoint/key from the machine-local config (env-overridable)
│   ├── 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.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)
    └── anchors/    (operator-preferences, current-context, inbox seeds)

Skills & commands

Skill	Triggers
echo-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
/echo-load	Cold-start context read (profile, scope, latest session, today, inbox)
/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.py and summarize invariant + graph-health violations
/echo-sweep	Bring the vault up to current spec (build index + symmetrize links)
/echo-reflect	Extract durable items from the session, preview, and apply on approval
/echo-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 enabled
• HTTPS access from the Claude/CoWork session environment to the endpoint configured in ~/.claude/echo-memory/config.json
• A machine-local config (~/.claude/echo-memory/config.json) supplying the vault owner, endpoint, and API key — see Configuration