timescale · jgpruitt · Jul 30, 2026 · Jul 30, 2026
@@ -30,7 +30,7 @@ claude plugin install --scope user memory-engine@memory-engine \
   [--config server=<url>] [--config space=<slug>] [--config api_key=<key>]
 ```
 
-The marketplace step is idempotent (skipped if already configured). **By default nothing is pinned into the plugin** -- `server`, `space`, and `api_key` are left blank so the plugin (hooks + MCP) tracks your live `me` config at runtime: your `me login` server, active space, and session. Pinning is opt-in: `--server` / `--space` pin those, and `--api-key` marks a headless install (see below). After install, restart Claude Code (or run `/plugin`) to load the hooks and slash commands.
+The marketplace step is idempotent (skipped if already configured). **By default nothing is pinned into the plugin** -- `server`, `space`, and `api_key` are left blank. Hooks track your live `me` config, including the active space for captures; MCP uses your live server and session but is multi-space until `space`, `--space`, or `ME_SPACE` is set. Pinning is opt-in: `--server` / `--space` pin those, and `--api-key` marks a headless install (see below). After install, restart Claude Code (or run `/plugin`) to load the hooks and slash commands.
 
 A session (non-headless) install then:
 
@@ -43,11 +43,11 @@ Pass `--mcp-only` to skip the plugin and register just the `me` MCP server (no h
 |--------|-------------|
 | `--mcp-only` | Register only the `me` MCP server (no hooks or slash commands). |
 | `--api-key <key>` | API key for a headless install. Default: the plugin/MCP server uses your `me login` session, resolved at runtime. |
-| `--space <slug>` | Pin a space. Default: resolve `ME_SPACE` / active space at runtime. |
+| `--space <slug>` | Lock MCP to this space and pin captures. Without it, MCP is multi-space unless `ME_SPACE` is set. |
 | `--server <url>` | Pin a server. Default: use your `me login` server at runtime. |
 | `--dev` | Install the plugin from the local checkout instead of the published marketplace (run from inside this repo). |
 
-Credential handling: by default (a personal install) nothing is pinned, so the plugin (and the MCP server) uses your `me login` session, server, and active space, resolved from the OS keychain / `~/.config/me` at runtime — so it follows `me login` / `me space use` and survives re-login. Pass `--server` / `--space` to pin either. Pass `--api-key` for a **headless** install that can't reach your keychain — since there's no session to fall back to, an API key bakes in a fixed server + space + key together (and skips the defaults/capture steps above — the operator's `~/.config/me` is not necessarily the tool's; capture is credential-agnostic, so a headless deployment opts in via a committed `.me` `capture: true` or `capture: true` in the target machine's config). For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; the pinned space must be declared by that key. The space is resolved from `--space`, `ME_SPACE`, or your active space (whichever is set — install errors if none, since a global key has no active space to fall back to at runtime), and `--server` defaults to your resolved server.
+Credential handling: by default (a personal install) nothing is pinned, so the plugin and MCP server use your `me login` session and server, resolved from the OS keychain / `~/.config/me` at runtime. An unpinned MCP server is multi-space: agents call `me_space_list`, then pass `space` to every memory tool. Your active space controls captures, not MCP routing. Pass `--server` / `--space` to pin either; a pinned space locks the MCP tools to that space. Pass `--api-key` for a **headless** install that cannot reach your keychain; it may also run multi-space. Capture is credential-agnostic, so a headless deployment opts in through a committed `.me` `capture: true` or the target machine's config. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; a pinned space must be declared by that key. `ME_SPACE` also locks MCP at runtime, and `--server` defaults to your resolved server.
 
 There is no `--scope` flag: the plugin is always installed at **user** scope (once, for all projects). Per-project behavior — a shared tree, a pinned space, and capture on/off — comes from the committed [`.me/config.yaml`](../project-config.md), which the single installed plugin reads per project.
 
@@ -82,7 +82,7 @@ claude plugin install --scope user memory-engine@memory-engine
 /plugin  # select memory-engine, Configure (all values optional if logged in)
 ```
 
-Both `api_key` and `space` are optional: blank `api_key` uses your `me login` session, and blank `space` uses your active space (`me space use`; pin it for project/shared installs).
+Both `api_key` and `space` are optional: blank `api_key` uses your `me login` session. Blank `space` leaves MCP multi-space; it does not use your active space. Set `space` to lock MCP and pin capture for a project/shared install.
 
 If you only want the MCP tools (no hooks, no slash commands), run [me claude install --mcp-only](#me-claude-install) instead.
 

@@ -21,18 +21,18 @@ me codex install [options]
 | Option | Description |
 |--------|-------------|
 | `--api-key <key>` | API key for a headless install. Default: the MCP server uses your `me login` session, resolved at runtime. |
-| `--space <slug>` | Pin a space. Default: resolve `ME_SPACE` / active space at runtime. |
+| `--space <slug>` | Lock MCP to this space. Without it, MCP is multi-space unless `ME_SPACE` is set. |
 | `--server <url>` | Server URL to embed in the MCP config. |
 
-By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login) and your active space (set by `me space use` / `ME_SPACE`). Pass `--api-key` for a headless install that cannot reach your keychain; that bakes the key and requires a pinned `--space`. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; the pinned space must be declared by that key.
+By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login). MCP is multi-space unless the generated command includes `--space` or its environment sets `ME_SPACE`: agents call `me_space_list`, then pass `space` to every memory tool. Your active space does not select an MCP space. Pass `--space` to lock the MCP tools to one space. Pass `--api-key` for a headless install that cannot reach your keychain; it may also run multi-space. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; a pinned space must be declared by that key.
 
 `me codex install` also adds a hook to `~/.codex/hooks.json` so that a plain `me` call from Codex's shell can discover the active project after a directory change. Re-running install is safe and leaves any other hooks you've configured untouched. **One-time step**: Codex holds new hooks for review — run `/hooks` inside Codex once to approve it.
 
 For manual MCP client configuration, see [MCP Integration](../mcp-integration.md).
 
 ### Known gap: Codex Desktop and the VS Code extension
 
-Under the Codex **terminal CLI**, `me mcp` resolves your project the ordinary way — no action needed. The Codex **Desktop app** and **VS Code extension** currently launch MCP servers from the wrong working directory, so `me mcp` can't tell which project you're in and falls back to your global config (your own session and active space) instead of the project's `.me/config.yaml`. The workaround is to set a per-server `cwd` pointing at your project directory in Codex's own MCP config. The terminal CLI is unaffected.
+Under the Codex **terminal CLI**, `me mcp` resolves your project the ordinary way — no action needed. The Codex **Desktop app** and **VS Code extension** currently launch MCP servers from the wrong working directory, so `me mcp` cannot use a project's `.me/config.yaml` for server resolution and falls back to global configuration. MCP space selection is unaffected: an unpinned server is always multi-space. The workaround is to set a per-server `cwd` pointing at your project directory in Codex's own MCP config. The terminal CLI is unaffected.
 
 ---
 

@@ -20,11 +20,11 @@ me gemini install [options]
 | Option | Description |
 |--------|-------------|
 | `--api-key <key>` | API key for a headless install. Default: the MCP server uses your `me login` session, resolved at runtime. |
-| `--space <slug>` | Pin a space. Default: resolve `ME_SPACE` / active space at runtime. |
+| `--space <slug>` | Lock MCP to this space. Without it, MCP is multi-space unless `ME_SPACE` is set. |
 | `--server <url>` | Server URL to embed in the MCP config. |
 | `-s, --scope <scope>` | Gemini CLI config scope: `user` or `project`. Default: `user`. |
 
-By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login) and your active space (set by `me space use` / `ME_SPACE`). Pass `--api-key` for a headless install that cannot reach your keychain; that bakes the key and requires a pinned `--space`. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; the pinned space must be declared by that key.
+By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login). MCP is multi-space unless the generated command includes `--space` or its environment sets `ME_SPACE`: agents call `me_space_list`, then pass `space` to every memory tool. Your active space does not select an MCP space. Pass `--space` to lock the MCP tools to one space. Pass `--api-key` for a headless install that cannot reach your keychain; it may also run multi-space. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; a pinned space must be declared by that key.
 
 `me gemini install` also adds a small hook to `~/.gemini/settings.json` so that a plain `me` call from Gemini CLI's shell tool can discover the active project after a directory change. Re-running install is safe and leaves any other hooks you've configured untouched.
 

@@ -21,15 +21,15 @@ me mcp [options]
 | Option | Description |
 |--------|-------------|
 | `--api-key <key>` | API key. If omitted, the server uses your stored `me login` session. |
-| `--space <slug>` | Space to operate in (the `X-Me-Space`). |
+| `--space <slug>` | Lock MCP to this space (the `X-Me-Space`). |
 
 Resolution order:
 
 - **Auth token**: `--api-key` > `ME_API_KEY` > stored session token.
-- **Space**: `--space` > `ME_SPACE` > stored active space.
+- **Space**: `--space` > `ME_SPACE`; without either, MCP is multi-space.
 - **Server URL**: `--server` (global option) > `ME_SERVER` > `https://api.memory.build`.
 
-A logged-in developer needs no key or space — the active session and active space are used automatically. For an unattended or restricted installation, pass `--api-key` and `--space` (or set `ME_API_KEY` / `ME_SPACE`). The server acts as the principal represented by that credential.
+A logged-in developer needs no key or space. `--space` and `ME_SPACE` create a locked server: memory tools cannot select another space. Without either, MCP starts multi-space mode: `me_space_list` is available and memory tools require `space`. Project configuration and your stored active space do not select an MCP space. This supports manual configuration without `.me/config.yaml` or an active space, for example `me mcp --api-key <key> --server <url>`. Selecting a space never grants access; the server still enforces membership and tree grants. The server acts as the principal represented by that credential.
 
 This command is typically not run directly -- it is invoked by AI tools based on their MCP configuration.
 
@@ -53,4 +53,4 @@ claude plugin marketplace add timescale/memory-engine
 claude plugin install memory-engine@memory-engine [--scope user|project|local]
 ```
 
-Then start Claude Code, run `/plugin`, select `memory-engine`, and configure the options (all optional): leave `api_key`, `server`, and `space` blank to fall back to your `me login` session, server, and active space; set `content_mode` to control how much of each message is captured. The plugin has no tree setting — where captured sessions are stored is controlled by your project's [`.me/config.yaml`](../project-config.md) `tree` (or the private `~/projects` default). See [`me claude`](me-claude.md) for the full plugin reference.
+Then start Claude Code, run `/plugin`, select `memory-engine`, and configure the options (all optional): leave `api_key` and `server` blank to use your `me login` session and server; leave `space` blank for multi-space MCP tools or set it to lock MCP and pin captures. Set `content_mode` to control how much of each message is captured. The plugin has no tree setting — where captured sessions are stored is controlled by your project's [`.me/config.yaml`](../project-config.md) `tree` (or the private `~/projects` default). See [`me claude`](me-claude.md) for the full plugin reference.
@@ -24,11 +24,11 @@ A session (non-headless) install ends with the shared **capture prompt** (defaul
 | Option | Description |
 |--------|-------------|
 | `--api-key <key>` | API key for a headless install. Default: the MCP server uses your `me login` session, resolved at runtime. |
-| `--space <slug>` | Pin a space. Default: resolve `ME_SPACE` / active space at runtime. |
+| `--space <slug>` | Lock MCP to this space. Without it, MCP is multi-space unless `ME_SPACE` is set. |
 | `--server <url>` | Server URL to embed in the MCP config. |
 | `--scope <scope>` | Where to write the config: `project` (`./opencode.json` at the repo root) or `user` (`~/.config/opencode/opencode.json`). Default: `user`. |
 
-By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login) and your active space (set by `me space use` / `ME_SPACE`). Pass `--api-key` for a headless install that cannot reach your keychain; that bakes the key and requires a pinned `--space`. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; the pinned space must be declared by that key.
+By default only the server URL is baked into the config: at runtime `me mcp` uses your `me login` session (resolved from the OS keychain / `~/.config/me` each run, so it survives re-login). MCP is multi-space unless the generated command includes `--space` or its environment sets `ME_SPACE`: agents call `me_space_list`, then pass `space` to every memory tool. Your active space does not select an MCP space. Pass `--space` to lock the MCP tools to one space. Pass `--api-key` for a headless install that cannot reach your keychain; it may also run multi-space. For least privilege, mint a restricted PAT or service-account key with `me apikey create --allow <space>:<path>:<r|w|o>`; a pinned space must be declared by that key.
 
 Use `--scope project` to write the `mcp.me` entry into the repo's `opencode.json` (instead of your global config) so it can be committed and shared with your team. Don't combine `--scope project` with a baked `--api-key` unless you intend to commit that key.