fix:

QUICKSTART.md

@@ -27,11 +27,21 @@ and Synthesis.
 5. **(Optional) LLM configured** — if you chose a free backend during the prompt,
    Perseus is ready for `perseus suggest` and `perseus synthesize`
 
-## Add Persistent Memory (optional)
+## Context, memory, and session terms
 
-Cross-session memory is a separate, optional component — the **Perseus Vault**
-MCP server. `perseus quickstart` already wires the connector in your config; to
-install the engine (prebuilt binary, Linux/macOS):
+Perseus resolves and shapes the active working context; Perseus Vault owns durable-memory persistence and recall.
+
+- **Active working context** is the current, task-relevant workspace state — files, services, tasks, and other facts that can change. Perseus resolves and shapes it at render time before the assistant sees it.
+- **Durable memory** is information intended to survive session boundaries. Perseus Vault owns its persistence and recall.
+- **Recalled memory** is the subset of durable memory returned for a query and shaped into the rendered context. The public `@memory` directive remains the compatibility API name for Vault-backed recall; existing MCP compatibility names remain unchanged.
+- **Session history** is Perseus's recent checkpoint and session-digest record. `@waypoint` and `@session` expose it; it is distinct from durable memory. An explicit capture may persist a checkpoint in Perseus Vault as durable memory.
+
+## Add Durable Memory (optional)
+
+Cross-session durable memory is a separate, optional component — the **Perseus Vault**
+MCP server. Perseus resolves and shapes the active working context; Perseus Vault
+owns durable-memory persistence and recall. `perseus quickstart` already wires the
+connector in your config; to install the engine (prebuilt binary, Linux/macOS):
 
 ```bash
 curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh
@@ -150,9 +160,15 @@ start.
 
 ### MCP Server
 
+For MCP configurations and scheduled jobs, use the stable launcher
+`~/.local/bin/perseus`. It remains the same entry point across package upgrades,
+so background jobs do not pin a version-specific Python or Library path. Bare
+`perseus` remains fine for interactive shells; use `command -v perseus` to
+inspect the resolved installation when diagnosing a path problem.
+
 ```bash
-perseus mcp config    # Print MCP client config for Claude Desktop, Cursor, etc.
-perseus mcp serve     # Run as an MCP server over stdio
+~/.local/bin/perseus mcp config    # Print MCP client config for Claude Desktop, Cursor, etc.
+~/.local/bin/perseus mcp serve     # Run as an MCP server over stdio
 ```
 
 ## CI/CD Integration
@@ -161,7 +177,7 @@ Add to your CI pipeline (GitHub Actions, etc.):
 
 ```yaml
 - name: Refresh Perseus context
-  run: perseus render .perseus/context.md --output .hermes.md --strict
+  run: ~/.local/bin/perseus render .perseus/context.md --output .hermes.md --strict
 ```
 
 The `--strict` flag fails the build if any directive emits a warning.

README.md

@@ -28,6 +28,15 @@ start (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, ...). Keep it live with
 - **Local-first by default** — the core renderer reads your workspace locally; no account or hosted service is required.
 - **MCP-native when you need it** — expose the same live context as a stdio or SSE MCP server, with shell-executing tools opt-in.
 
+### Context, memory, and session terms
+
+Perseus resolves and shapes the active working context; Perseus Vault owns durable-memory persistence and recall.
+
+- **Active working context** is the current, task-relevant workspace state — files, services, tasks, and other facts that can change. Perseus resolves and shapes it at render time before the assistant sees it.
+- **Durable memory** is information intended to survive session boundaries. Perseus Vault owns its persistence and recall.
+- **Recalled memory** is the subset of durable memory returned for a query and shaped into the rendered context. The public `@memory` directive remains the compatibility API name for Vault-backed recall; existing MCP compatibility names remain unchanged.
+- **Session history** is Perseus's recent checkpoint and session-digest record. `@waypoint` and `@session` expose it; it is distinct from durable memory. An explicit capture may persist a checkpoint in Perseus Vault as durable memory.
+
 ### Fastest path
 
 ```bash
@@ -145,14 +154,16 @@ PR Pilot — 5-agent autonomous PR review pipeline. Gemini API, Google Cloud Run
 
 Perseus implements the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), exposing tools over stdio or SSE transport. Every tool resolves live workspace state at invocation time — no stale cache, no pre-computed snapshots.
 
+> **Stable launcher for MCP and schedulers:** Use `~/.local/bin/perseus` in MCP configurations and scheduled jobs. This install-managed launcher stays stable across package upgrades instead of baking a version-specific Python or Library path into background configuration. Interactive shell commands may still use `perseus`; verify the resolved entry point with `command -v perseus` when diagnosing an installation.
+
 > **⚠️ Security Gate:** Shell-executing directives (`@query`, `@agent`, `@services command:`) require `export PERSEUS_ALLOW_DANGEROUS=1`. Without it, shell directives are silently skipped.
 
 ### Quick Start (MCP Server)
 
 ```bash
 pip install perseus-ctx
-perseus mcp serve                          # stdio (Claude Desktop, Claude Code, Cursor, Codex)
-perseus mcp serve --transport sse --port 8420  # SSE (remote agents, multi-machine)
+~/.local/bin/perseus mcp serve                          # stdio (Claude Desktop, Claude Code, Cursor, Codex)
+~/.local/bin/perseus mcp serve --transport sse --port 8420  # SSE (remote agents, multi-machine)
 ```
 
 ### Assistant-Specific Wiring
@@ -164,21 +175,21 @@ Pick your assistant and add the config block shown:
 ```yaml
 mcp_servers:
   perseus:
-    command: perseus
+    command: ~/.local/bin/perseus
     args: ["mcp", "serve", "--workspace", "/path/to/workspace"]
 ```
 
 Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in your session.
 
-> Use an absolute path for `--workspace`. Perseus's non-interactive shell context has a limited PATH — a bare `perseus` command works in the Hermes MCP config because Hermes resolves it from the user's environment, but the workspace path must be absolute.
+> Use an absolute path for `--workspace`. Perseus's non-interactive shell context has a limited PATH, so the stable launcher above avoids relying on interactive-shell lookup.
 
 **Claude Desktop** (`claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "perseus": {
-      "command": "perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve", "--workspace", "/path/to/workspace"]
     }
   }
@@ -191,7 +202,7 @@ Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in y
 {
   "mcpServers": {
     "perseus": {
-      "command": "perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve"]
     }
   }
@@ -204,7 +215,7 @@ Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in y
 {
   "mcpServers": {
     "perseus": {
-      "command": "perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve"]
     }
   }
@@ -217,7 +228,7 @@ Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in y
 {
   "mcpServers": {
     "perseus": {
-      "command": "perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve"]
     }
   }
@@ -230,7 +241,7 @@ Then verify with `hermes mcp test perseus`. Tools appear as `mcp_perseus_*` in y
 {
   "mcpServers": {
     "perseus": {
-      "command": "perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve"]
     }
   }
@@ -360,13 +371,13 @@ Keep it fresh with cron, launchd, systemd, or `perseus watch`:
 
 ```bash
 # Linux systemd (auto-refresh every 5 minutes)
-perseus systemd .perseus/context.md --output AGENTS.md --interval 5m --install --enable
+~/.local/bin/perseus systemd .perseus/context.md --output AGENTS.md --interval 5m --install --enable
 
 # macOS launchd
-perseus launchd .perseus/context.md --output AGENTS.md
+~/.local/bin/perseus launchd .perseus/context.md --output AGENTS.md
 
 # Cron (any POSIX host)
-perseus cron .perseus/context.md --output AGENTS.md --every 5 --install
+~/.local/bin/perseus cron .perseus/context.md --output AGENTS.md --every 5 --install
 ```
 
 See the [Integration Guide](https://github.com/Perseus-Computing-LLC/perseus/blob/main/docs/HERMES_INTEGRATION.md) for Hermes-specific auto-refresh setups and [adapter patterns](https://github.com/Perseus-Computing-LLC/perseus/blob/main/spec/integration.md) for full integration details.

SETUP-GUIDE.md

@@ -20,6 +20,15 @@ Perseus is a **compile-before-context engine** — it runs a set of directives i
 
 The key insight: **the AI reads the rendered output, not the directives**. Perseus solves the problem of giving an AI accurate "what is happening right now" context without relying on the AI to go fetch it.
 
+## Context, memory, and session terms
+
+Perseus resolves and shapes the active working context; Perseus Vault owns durable-memory persistence and recall.
+
+- **Active working context** is the current, task-relevant workspace state — files, services, tasks, and other facts that can change. Perseus resolves and shapes it at render time before the assistant sees it.
+- **Durable memory** is information intended to survive session boundaries. Perseus Vault owns its persistence and recall.
+- **Recalled memory** is the subset of durable memory returned for a query and shaped into the rendered context. The public `@memory` directive remains the compatibility API name for Vault-backed recall; existing MCP compatibility names remain unchanged.
+- **Session history** is Perseus's recent checkpoint and session-digest record. `@waypoint` and `@session` expose it; it is distinct from durable memory. An explicit capture may persist a checkpoint in Perseus Vault as durable memory.
+
 ### Token Efficiency
 
 Perseus is a **long-session efficiency play**. Context is injected once at session start and reused across all turns — the LLM never wastes turns asking "what machine is this?" or "what tools do I have?"
@@ -84,6 +93,14 @@ cd perseus
 pip install -e .
 ```
 
+### Stable launcher for automation
+
+Use `~/.local/bin/perseus` as the launcher in MCP configurations and scheduled
+jobs. This install-managed entry point stays stable across package upgrades and
+avoids pinning a version-specific Python or Library path into background
+configuration. Interactive shell commands may use `perseus`; run `command -v
+perseus` when you need to discover or diagnose the resolved executable.
+
 ---
 
 ## Quick Start
@@ -157,8 +174,10 @@ in `.perseus/config.yaml`.
 > **Rovo Dev users:** The "two-file problem" — Rovo Dev CLI reads `~/.rovodev/AGENTS.md` while
 > the Rovo web agent reads `~/AGENTS.md`. Keep them in sync via the automation section below.
 >
-> **Cross-platform paths:** All examples below use macOS-style `/Users/yourname/...` paths.
-> Substitute as needed:
+> **Cross-platform paths:** Workspace examples below use macOS-style `/Users/yourname/...` paths.
+> Substitute as needed. Automation examples intentionally use the stable
+> `~/.local/bin/perseus` launcher; expand it only when an MCP client requires a
+> fully resolved path:
 > - **Windows (git-bash):** `C:/Users/yourname/...` or `/c/Users/yourname/...`
 > - **Linux:** `/home/yourname/...`
 > - **Docker:** `/opt/data/...` or wherever `$HERMES_HOME` points
@@ -204,7 +223,7 @@ trust:
 > ```bash
 > export PERSEUS_ALLOW_DANGEROUS=1
 > # or per-command:
-> PERSEUS_ALLOW_DANGEROUS=1 perseus render ~/.perseus/context.md --output ~/AGENTS.md
+> PERSEUS_ALLOW_DANGEROUS=1 ~/.local/bin/perseus render ~/.perseus/context.md --output ~/AGENTS.md
 > ```
 > If missing, these directives will render as disabled even when `render.allow_query_shell: true`.
 
@@ -755,7 +774,7 @@ In addition to AGENTS.md auto-injection, Hermes can wire Perseus as an MCP serve
 ```yaml
 mcp_servers:
   perseus:
-    command: /home/yourname/.local/bin/perseus   # Linux/Docker; use /Users/… on macOS
+    command: ~/.local/bin/perseus   # stable launcher; expand ~ if this client requires an absolute path
     args:
       - mcp
       - serve
@@ -773,7 +792,7 @@ mcp_servers:
 > reload. Smoke-test with:
 > ```bash
 > echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
->   timeout 3 /home/yourname/.local/bin/perseus mcp serve --workspace /home/yourname
+>   timeout 3 ~/.local/bin/perseus mcp serve --workspace /home/yourname
 > ```
 
 ### Claude Code (hooks-based injection)
@@ -793,7 +812,7 @@ Add Perseus MCP to your MCP config at `~/.rovodev/mcp.json`:
 {
   "mcpServers": {
     "perseus": {
-      "command": "/Users/yourname/Library/Python/3.13/bin/perseus",
+      "command": "~/.local/bin/perseus",
       "args": ["mcp", "serve", "--workspace", "/Users/yourname"]
     }
   }
@@ -806,10 +825,10 @@ Perseus also auto-renders AGENTS.md at session start if the launchd job is confi
 
 ```bash
 # Print MCP client config for your editor
-perseus mcp config
+~/.local/bin/perseus mcp config
 
 # Or use the MCP server directly in any MCP-compatible client:
-# command: perseus mcp serve --workspace /path/to/workspace
+# command: ~/.local/bin/perseus mcp serve --workspace /path/to/workspace
 ```
 
 ---
@@ -828,7 +847,7 @@ If you're already using Hermes Agent, its built-in cron scheduler is the simples
 #!/bin/bash
 # Silent on success, alerts on failure (designed for no_agent=true cron)
 export PATH="$HOME/.local/bin:$PATH"
-PERSEUS_ALLOW_DANGEROUS=1 perseus render "$HOME/.perseus/context.md" --output "$HOME/AGENTS.md" >/dev/null 2>&1
+PERSEUS_ALLOW_DANGEROUS=1 ~/.local/bin/perseus render "$HOME/.perseus/context.md" --output "$HOME/AGENTS.md" >/dev/null 2>&1
 exit_code=$?
 if [ $exit_code -ne 0 ]; then
     echo "Perseus render FAILED (exit $exit_code)"
@@ -888,7 +907,7 @@ Create `~/Library/LaunchAgents/com.yourname.perseus.render.plist`:
     <array>
         <string>/bin/sh</string>
         <string>-c</string>
-        <string>/Users/yourname/.local/bin/perseus render /Users/yourname/.perseus/context.md --output /Users/yourname/AGENTS.md</string>
+        <string>~/.local/bin/perseus render /Users/yourname/.perseus/context.md --output /Users/yourname/AGENTS.md</string>
     </array>
     <key>StartInterval</key>
     <integer>1800</integer>
@@ -920,7 +939,7 @@ Description=Perseus context render
 
 [Service]
 Type=oneshot
-ExecStart=/bin/sh -c '/home/yourname/.local/bin/perseus render /home/yourname/.perseus/context.md --output /home/yourname/AGENTS.md'
+ExecStart=/bin/sh -c '~/.local/bin/perseus render /home/yourname/.perseus/context.md --output /home/yourname/AGENTS.md'
 
 # ~/.config/systemd/user/perseus-render.timer
 [Unit]
@@ -943,7 +962,7 @@ systemctl --user enable --now perseus-render.timer
 ```bash
 crontab -e
 # Add:
-*/30 * * * * /full/path/to/perseus render /home/yourname/.perseus/context.md --output /home/yourname/AGENTS.md
+*/30 * * * * ~/.local/bin/perseus render /home/yourname/.perseus/context.md --output /home/yourname/AGENTS.md
 ```
 
 ---
@@ -994,13 +1013,13 @@ Perseus can run as an MCP server over stdio, or as an HTTP server with a dashboa
 
 ```bash
 # MCP server (stdio, JSON-RPC 2.0) — exposes directives as tools
-perseus mcp serve --workspace /path/to/workspace
+~/.local/bin/perseus mcp serve --workspace /path/to/workspace
 
 # Print MCP client config for Claude Desktop / Cursor
-perseus mcp config
+~/.local/bin/perseus mcp config
 
 # HTTP server with dashboard at http://127.0.0.1:7991
-perseus serve --port 7991 --workspace /path/to/workspace
+~/.local/bin/perseus serve --port 7991 --workspace /path/to/workspace
 ```
 
 HTTP endpoints:
@@ -1230,7 +1249,7 @@ cd ~/my-project && perseus init
 
 # Render context to AGENTS.md (Hermes, Claude Code, Rovo web agent)
 # Requires PERSEUS_ALLOW_DANGEROUS=1 for @query, @agent, @services command: directives
-PERSEUS_ALLOW_DANGEROUS=1 perseus render ~/.perseus/context.md --output ~/AGENTS.md
+PERSEUS_ALLOW_DANGEROUS=1 ~/.local/bin/perseus render ~/.perseus/context.md --output ~/AGENTS.md
 perseus render ~/.perseus/context.md --output ~/AGENTS.md
 
 # Render to .hermes.md (Hermes high-priority context)
@@ -1264,7 +1283,7 @@ perseus memory show
 perseus memory status
 
 # MCP server
-perseus mcp serve --workspace ~
+~/.local/bin/perseus mcp serve --workspace ~
 
 # Hermes cronjob (automated render every 30 min)
 hermes cron create "every 30m" --name "Perseus render" --script perseus-render.sh --no-agent