@echomem/mcp 1.4.0 → 1.4.2

package/README.md

@@ -35,23 +35,57 @@ legacy EchoMem-synthesized recall answer.
 ## Quick start (recommended)
 
 ```bash
-# One command: detect your editor, write its MCP config, log in via the browser.
-npx -y @echomem/mcp setup
+# One command: install the CLI, detect your editor, write MCP config, log in via the browser.
+npm i -g @echomem/mcp@latest && echomem-mcp setup
 ```
 
-`setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP config (with **no
-secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600), then opens the
-browser to approve the device and, for encrypted accounts, unlock the vault. Reload your editor and
-you're done.
+This keeps `echomem-mcp` available for later commands like `status`, `update`, `unlock`, and
+playground setup. `setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP
+config (with **no secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600),
+then opens the browser to approve the device and, for encrypted accounts, unlock the vault. Reload
+your editor and you're done.
 
 | Command | What it does |
 |---|---|
+| `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and run setup in one explicit step |
+| `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop]` | Write client config + log in |
+| `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|codex]` | Write client config without opening the browser or changing credentials |
+| `npx -y @echomem/mcp@latest update [--client cursor\|windsurf\|claude-desktop\|codex]` | One-shot update: repoint the client config to the latest bridge, with no browser login |
+| `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
 | `echomem-mcp status` | Show token / key / detected clients |
 | `echomem-mcp logout` | Remove stored credentials |
 
+The bridge reports its package version in MCP server instructions and in the `search_memories`
+tool description. Agents should use that version signal to update once when stale, not auto-update
+on every MCP startup.
+
+## EchoMem Context HUD
+
+The package also ships `echomem-hud`, a local context-health sidecar for Codex and Claude. It reads
+local agent logs, computes a tracked lower-bound "clean vs dirty" context score, and renders a small
+HUD without adding tokens to the agent conversation.
+
+```bash
+echomem-hud app                 # Electron floating HUD
+echomem-hud serve               # Browser fallback at http://127.0.0.1:17377
+echomem-hud summary --json      # Machine-readable current score
+echomem-hud status              # Show detected Codex/Claude sources
+```
+
+Supported local sources:
+- Codex: `~/.codex/sessions/**/rollout-*.jsonl`
+- Claude Code: `~/.claude/echo-ctx/*.json` first, then local transcripts when present
+- Claude desktop agent/Cowork: local agent-mode transcripts under Application Support
+
+The v1 metric counts `range_redundant` reads only and reports pollution as `tracked dead-weight ≥`
+because exact context composition and provider eviction are not observable.
+
+MCP fallback: agents can call `echo_context_health` to get the same score as markdown in-chat. This
+is on-demand; the passive HUD remains a separate local process.
+
 ### Manual / headless (SSH, containers, CI)
 
 No browser? Provide secrets directly — this is the documented headless path:
@@ -80,7 +114,7 @@ npm test   # crypto compat + encrypted-local integration tests
 
 ### Add to your IDE (Cursor or Windsurf)
 
-> Prefer `npx -y @echomem/mcp setup` above — it writes these files for you and keeps secrets out of
+> Prefer `npm i -g @echomem/mcp@latest && echomem-mcp setup` above — it writes these files for you and keeps secrets out of
 > the client config. The manual steps below are the fallback.
 
 #### For Cursor
@@ -151,6 +185,7 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
 * **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 * **`delete_memory`**: Delete a single personal memory through a two-step confirmation flow. First call with `memoryId` only to preview the target and receive `confirmationToken`; after the user explicitly confirms, call again with `confirmed: true` and that exact token. This deletes the memory row only and preserves raw `source_of_truth` conversation records.
+* **`echo_context_health`**: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.
 
 Legacy aliases are preserved for compatibility: