Release native assistant execution with complete installer support

DESIGN_NOTES.md

@@ -1,5 +1,34 @@
 # RightMemory Design Notes
 
+## Native Assistant Execution
+
+Assistant execution separates the agent's judgment from RightMemory's deterministic
+storage boundary. The shared orchestrator skill delegates retrieval needs and submits
+evidence. A Retrieve child prepares access to live source files and pending evidence,
+then summarizes what matters. An Update child uses the canonical Update instructions
+and native file tools in a persistent Git worktree. CLI JSON and MCP call the same
+model-free core; neither constructs an internal role agent.
+
+Batching reuses the existing candidate identity, reservation policy, and synchronized
+Git queue. Readiness is carried in ordinary tool results, including instructions for a
+child to relay the notice to its main agent. A notice does not acquire ownership.
+Local assistant reservations survive individual CLI processes; synchronized claims use
+a stable assistant-specific holder so the old worker cannot resume the same live lease.
+
+A batch retains its evidence identity across attempts. Each attempt has its own worktree,
+version, and fenced semantic operation. Completion freezes committed edits, validates
+every original commit and the complete candidate, retains the existing UpdateRecord,
+and publishes through the existing write supervisor or Git queue finalizer. Prepared
+results have an external finalizer so ordinary worker recovery cannot publish them
+without their current claim. Durable outcomes recover interrupted acknowledgement;
+failed publication retries the prepared result without repeating agent judgment.
+
+This is a separate execution path. It preserves the existing runtime and does not claim
+equivalent model history, incremental retrieval caches, delivery suppression, watchers,
+or maintenance scheduling. Ordinary sync is shared; semantic sync conflicts remain an
+explicit blocked state until reconciled. Usage and verification are documented in
+[Assistant Execution](docs/ASSISTANT_EXECUTION.md).
+
 ## Embedding Retrieval
 
 The embedding backend separates finding likely context from deciding how to use it. Nemotron 1B selects forty candidates, Jina reranker v3.5 orders them, and the calling agent judges up to ten returned source entries. On the small frozen experiment, reranking recovered every labelled positive case within ten; score cutoffs also removed required context and failed on related questions whose answers were absent. The production path therefore uses rank and a count limit without claiming to detect missing answers. The experiment and its limits are recorded in `experiments/README.md`.

README.md

@@ -47,6 +47,8 @@ RightMemory is aimed at developers who spend serious time with coding agents and
 
 ## Quick Start
 
+To use your current assistant's native agents without a RightMemory model backend, follow [Assistant execution](docs/ASSISTANT_EXECUTION.md). It uses `rightmemory assistant`, a shared skill, and native file tools. Use the installer’s `--mode assistant` with explicit memory-root and skill-directory paths. The default installer paths below configure the existing internal runtime.
+
 Install prerequisites:
 
 ```bash
@@ -96,9 +98,9 @@ rightmemory doctor agent-cli
 rightmemory doctor agent-cli
 ```
 
-Before using RightMemory, configure its role backend in `<memory-root>/rightmemory.toml` (by default `~/.rightmemory/rightmemory.toml`). See [Standalone Config](#standalone-config) for model endpoints and credentials, or [CLI-Agent Config](#cli-agent-config) for Codex SDK / Claude Code CLI execution. MCP connects your host agent to this runtime; it does not replace the configured backend or use the host's model automatically.
+Before using the internal runtime, configure its role backend in `<memory-root>/rightmemory.toml` (by default `~/.rightmemory/rightmemory.toml`). See [Standalone Config](#standalone-config) for model endpoints and credentials, or [CLI-Agent Config](#cli-agent-config) for Codex SDK / Claude Code CLI execution. The `rightmemory mcp` transport connects your host agent to this runtime; it does not replace the configured backend or use the host's model automatically. Native assistant execution instead uses `rightmemory assistant`, including its optional `assistant mcp` transport.
 
-For an MCP client, follow [MCP setup](docs/MCP.md) to register `rightmemory mcp` as a local stdio server. Connect the server in your host and check its available tools: `rightmemory_retrieve`, `rightmemory_submit_update`, and `rightmemory_capture_guidance`. Seeing all three verifies tool discovery, not backend execution or a completed memory update. Do not also load a RightMemory orchestrator skill in that MCP conversation; command-only clients use the CLI skills instead.
+For the internal runtime's MCP transport, follow [MCP setup](docs/MCP.md) to register `rightmemory mcp` as a local stdio server. Connect the server in your host and check its available tools: `rightmemory_retrieve`, `rightmemory_submit_update`, and `rightmemory_capture_guidance`. Seeing all three verifies tool discovery, not backend execution or a completed memory update. Do not also load a RightMemory orchestrator skill in that MCP conversation; command-only clients use the CLI skills instead.
 
 After connecting MCP, add a short instruction to your agent guidance file, such as
 `AGENTS.md` for Codex or `CLAUDE.md` for Claude Code:
@@ -171,6 +173,7 @@ For a short recording script, see [docs/DEMO.md](docs/DEMO.md).
 - Multi-device memory continuity across laptops, desktops, agent clients, and project-specific roots.
 - Automatic orchestration plus independent explicit skills for map maintenance, Memory maintenance, guidance review, and Manager support in Codex App.
 - Two executor modes behind the same `rightmemory` CLI: standalone runtime or delegated Codex SDK/Claude Code CLI role execution.
+- Native assistant execution through shared role instructions and deterministic JSON CLI/MCP tools; your assistant supplies its own agents.
 - Source-authored retrieval output, selected by an agent or an optional embedding + reranking retrieval service.
 - One updater for Memory and Agent Corrections, transcript-review candidate extraction, and immutable candidate records for input-to-edit provenance.
 

docs/ASSISTANT_EXECUTION.md

@@ -0,0 +1,96 @@
+# Assistant Execution
+
+RightMemory can use the current assistant's native agents for memory work. The main agent submits evidence and delegates ready batches. Retrieve inspects the real memory files and pending evidence; Update edits an isolated Git worktree. RightMemory performs deterministic queue, validation, publication, and recovery operations without creating a model client.
+
+This path uses one shared [assistant skill](../skills/rightmemory-assistant/SKILL.md), a [Retrieve role](../rightmemory/prompts/assistant-retrieve.md), and the existing [Update role](../rightmemory/prompts/update.md). The existing standalone and CLI-agent paths remain available.
+
+## Setup
+
+From the repository checkout, run the shared installer with explicit memory and skill directories:
+
+```bash
+./install.sh --mode assistant /absolute/memory-root /absolute/assistant-skills
+```
+
+On Windows, use `./install.ps1 --mode assistant C:\path\memory C:\path\assistant-skills` in PowerShell. The installer uses Git and uv, provisions Python 3.11+ and the runtime, initializes a new memory root, and installs `rightmemory-assistant` with that root bound. Existing complete roots are preserved; incomplete roots are refused before changes. Enable the installed skill using your assistant's supported skill mechanism. The skills directory is an explicit host choice, not automatic dot plugin registration.
+
+Use `rightmemory validate --root /absolute/memory-root` to check the root. Replace the new root's example entries with your own state through the normal memory workflow. Re-run the same installer command after updating the checkout. Stop agents and separately configured watchers that can submit evidence before switching execution modes. Finish or cancel pending updates with their original executor first; the installer refuses a switch while it finds their pending work. Use assistant execution rather than an internal Update worker for this root. If an old orchestrator skill was customized and therefore preserved, disable it before enabling the native assistant skill. The default standalone and CLI-agent installer modes remain unchanged.
+
+Assistant execution does not require RightMemory model API credentials, Codex, or Claude Code. The assistant uses its own configured agent. Keep the active root explicit:
+
+```bash
+rightmemory assistant --root /absolute/memory-root context --session example-session
+```
+
+The assistant's native subagents must be able to read the returned memory and pending paths and write the assigned Update worktree. A remote MCP connection does not expose the server's filesystem to native file tools. Place the runtime and native agents in a common accessible environment, or provide an authorized shared filesystem. Each assistant may use its own synchronized Git checkout.
+
+An Update worktree isolates candidate edits from the active root. A working-directory setting alone does not restrict arbitrary native shell access; use the assistant's file permissions where available. RightMemory validates the candidate it admits, while the assistant governs its agents' other file access.
+
+## Read and Submit
+
+The main agent delegates the retrieval need, bound root, session id, and `context` command (or matching MCP tool) to a native Retrieve subagent. That subagent calls `context` and reads its returned instruction file. The result supplies real source locations, imported-view mappings, and readable pending evidence, plus the observed `memory_commit` and `live_files: true`: memory sources remain live, rather than becoming a frozen snapshot. The subagent inspects them with native file tools and returns a useful summary with sources. This path does not require a `RetrieveSelection` or run the original retrieval renderer.
+
+Save submission evidence in a UTF-8 file outside the memory root:
+
+```bash
+rightmemory assistant --root /absolute/memory-root submit --session example-session --request-id evidence-1 --file /absolute/evidence.txt
+```
+
+Submission records evidence for later reconciliation. It does not start an internal model worker. Retry the same submission with the same request id and content; changed evidence needs a new request id.
+
+Normal assistant tool responses can carry a batch-ready notice. A Retrieve or other subagent passes that notice to its main agent, which arranges Update. The program owns pending and active batch state; the main agent owns native delegation.
+
+## Update a Batch
+
+```bash
+rightmemory assistant --root /absolute/memory-root update begin
+```
+
+Delegate only a newly claimed task (`claimed: true`). Give the native Update subagent the returned `instructions_file`, `candidates_file`, and `worktree`. Repeating ordinary `begin` while a task is active returns that task with `claimed: false`; resume the existing task instead of dispatching a second updater. `status: not_ready` means there is no eligible batch, and `status: sync_required` means sync needs attention first.
+
+Update follows the canonical role, including native edits, complete validation, and commits restricted to allowed files. `validate` remains independently callable:
+
+```bash
+rightmemory validate --root /absolute/candidate-worktree
+```
+
+Complete the task using the returned completion command, preserving its active-root binding:
+
+```bash
+rightmemory assistant --root /absolute/memory-root update complete --task TASK
+rightmemory assistant --root /absolute/memory-root update status --task TASK
+```
+
+`complete` admits the exact validated candidate through the program's protected publication path and records the batch outcome. A commit inside the worktree is not yet an applied update. An unchanged reconciliation still needs completion. `--output-file FILE` can attach the agent's UTF-8 summary to completion. The completion receipt includes `landed_commit`, `changed_paths`, and a `sync` outcome of `published` or `disabled`.
+
+After an interrupted call or lost response, inspect the same task and retry its completion. Keep its identity and worktree. When shared Git sync is enabled, completion first durably prepares the candidate, then publishes through the shared queue's compare-and-swap finalizer. If publication fails, the prepared result remains available; repeating `complete` retries publication without repeating semantic Update. With sync disabled, completion uses the local protected write path.
+
+A stale-base conflict requires reconciliation against current state. To abandon the current task's edits and prepare the same batch again, use:
+
+```bash
+rightmemory assistant --root /absolute/memory-root update begin --retry TASK
+```
+
+The replacement task fences the old task, so its edits cannot later be completed. The program checks for a previously completed or recoverable prepared result before replacing a task. Do not use replacement merely because a completion reply was lost.
+
+## Sync and MCP
+
+Configured ordinary sync refreshes memory before retrieval and pulls before preparing Update. Shared-queue completion publishes through the protected Git finalizer. Explicit ordinary sync operations use the same core:
+
+```bash
+rightmemory assistant --root /absolute/memory-root sync refresh
+rightmemory assistant --root /absolute/memory-root sync pull
+rightmemory assistant --root /absolute/memory-root sync push
+```
+
+An incoming conflict or invalid merged state returns sync status and available file/operation details, and blocks a new Update. Resolve the reported conflict using the existing sync repair workflow, then retry ordinary sync before preparing another Update. Sync conflicts are not delegated to a native repair agent by this interface.
+
+The optional MCP transport wraps the same assistant core:
+
+```bash
+rightmemory assistant --root /absolute/memory-root mcp --transport stdio
+```
+
+Load the shared assistant skill with this MCP transport; it explains how the assistant's own agents use the deterministic tools. The older `rightmemory mcp` command continues to use its configured internal role backend. See [MCP](MCP.md).
+
+Assistant execution covers native retrieval and batch updates. Internal model-session history, incremental retrieval caching, transcript watchers, Dreamer, and scheduled maintenance belong to the separate internal runtime. Use `assistant submit` and its completion receipts for native batches, not the internal `update submit` worker commands.

docs/MCP.md

@@ -1,5 +1,9 @@
 # RightMemory MCP
 
+For native assistant execution, use `rightmemory assistant --root /absolute/memory-root mcp --transport stdio` with the shared `rightmemory-assistant` skill. This transport exposes the model-independent assistant core and returns native-agent handoffs and batch notices. See [Assistant execution](ASSISTANT_EXECUTION.md) for setup, filesystem access, and verification boundaries.
+
+The `rightmemory mcp` server described below keeps the existing internal role backend and its ordinary-agent contract.
+
 RightMemory exposes a local MCP stdio server for ordinary agent work using the official MCP Python SDK v2:
 
 ```bash

install.ps1

@@ -6,7 +6,7 @@ if (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction Sile
 }
 
 if ($args -contains "-h" -or $args -contains "--help") {
-  Write-Host "Usage: .\install.ps1 [--mode cli-agent|standalone] [<memory-root> <skills-target>]"
+  Write-Host "Usage: .\install.ps1 [--mode assistant|cli-agent|standalone] [<memory-root> <skills-target>]"
   exit 0
 }
 

install.sh

@@ -5,7 +5,7 @@ set -u
 
 for argument in "$@"; do
   if [ "$argument" = "-h" ] || [ "$argument" = "--help" ]; then
-    echo "Usage: ./install.sh [--mode cli-agent|standalone] [<memory-root> <skills-target>]"
+    echo "Usage: ./install.sh [--mode assistant|cli-agent|standalone] [<memory-root> <skills-target>]"
     exit 0
   fi
 done

pyproject.toml

@@ -54,3 +54,4 @@ exclude = ["rightmemory/web/frontend/**"]
 [tool.hatch.build.targets.wheel.force-include]
 "MEMORY.example.md" = "rightmemory/MEMORY.example.md"
 "PURSUITS.example.md" = "rightmemory/PURSUITS.example.md"
+"skills/rightmemory-assistant" = "rightmemory/skills/rightmemory-assistant"