nexus-toolkit 2.2.0__tar.gz → 2.3.0__tar.gz

{nexus_toolkit-2.2.0 → nexus_toolkit-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-toolkit
-Version: 2.2.0
+Version: 2.3.0
 Summary: Hybrid search, retrieval, and Figma Make boilerplate generation MCP server
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT
@@ -26,16 +26,23 @@ Dynamic: license-file
 
 # Nexus — Enterprise Dev Toolkit
 
-> **The Hybrid Search, Retrieval & Design-to-Code Engine for AI Agents.**
+> **Design-to-Code pipeline · 22 Software Development Lifecycle (SDLC) agents · Workflow commands · Hybrid search — all powered by Claude Code.**
 
-Nexus combines semantic web search, documentation-optimised reading, and a **Design → Production Code pipeline** powered by golden path conventions. Feed it a Figma Make export, a text description, or an existing codebase — get back clean, runnable production code in your chosen stack.
+Nexus is an enterprise dev toolkit with four integrated capabilities:
+
+| Capability | What it does |
+|------------|-------------|
+| **Design-to-Code Pipeline** | Turn a [Figma Make](https://www.figma.com/make) export, text description, or existing codebase into production-ready code in your chosen stack — via golden path conventions and Claude-powered transformation |
+| **Dev-Workflow Agents** | 22 specialized Claude agents covering every SDLC stage: code review, security, QA, deployment, architecture, database, monitoring, and more |
+| **Workflow Commands** | 11 multi-step orchestration workflows — design → implement → review → deploy → document |
+| **Hybrid Search & Read** | Web search and documentation-optimised reading for AI agents (`nexus_search`, `nexus_read`) |
 
 **Two ways to use Nexus:**
 
 | Mode | How | Best for |
 |------|-----|----------|
-| **CLI** (`nexus`) | Install via one-liner, run from terminal | Local development, standalone use |
-| **MCP server** (`nexus-mcp`) | Add to Claude Code / n8n / Claude Desktop | AI agent workflows, n8n automation |
+| **CLI** (`nexus`) | Install via one-liner, run from terminal | Local development, CI scripts, standalone use |
+| **MCP server** | Add to Claude Code / n8n / Claude Desktop | AI agent workflows, n8n DevSecOps automation |
 
 ---
 
@@ -100,7 +107,7 @@ flowchart TD
 
 The agent reads queue files one at a time, transforms each component, updates `04_file_tree.json`, deletes the queue file, and repeats until `05_queue/` is empty.
 
-The `Project components` list is the key guard: when generating a page or layout, the agent only imports components from this list — never reference boilerplate stubs (e.g. `Features.tsx`, `CTA.tsx`) that appear in the file tree but were not part of the Figma source.
+The `Project components` list is the key guard: when generating a page or layout, the agent only imports components from this list — never reference boilerplate stubs (e.g. `Features.tsx`, `CTA.tsx`) that appear in the file tree but were not part of the Figma Make source.
 
 | Golden Path | Stack |
 |-------------|-------|
@@ -150,68 +157,78 @@ Specialized Claude Code agents for every stage of the SDLC — code review, secu
 
 ---
 
-## Installation
+## Installation & Integration
+
+Pick the use case that matches what you want to do — each one is self-contained.
+
+---
 
-**Prerequisites:** Python 3.10+
+### I want to generate code from a Figma Make export or prompt
 
-### Option 1: One-liner (recommended)
+**Prerequisites:** Python 3.10+, [`claude` CLI](https://claude.ai/code) installed and authenticated
 
 ```bash
+# 1. Install nexus-toolkit
 curl -fsSL https://nexus.coderstudio.co/install.sh | bash
-```
+# or: pip install nexus-toolkit  /  uv tool install nexus-toolkit
 
-### Option 2: pip / uv
+# 2. Install and authenticate Claude Code (required for transform + agent commands)
+npm install -g @anthropic-ai/claude-code
+claude login
 
-```bash
-pip install nexus-toolkit
-# or
-uv tool install nexus-toolkit
+# 3. Run
+nexus run prompt "A SaaS dashboard" --golden-path nextjs-fullstack --project-name my-app
+nexus run zip ~/Downloads/figma-export.zip --golden-path nextjs-fullstack --project-name my-app
 ```
 
-### Option 3: Development install
+---
 
-```bash
-git clone https://github.com/rcdelacruz/nexus-mcp.git
-cd nexus-mcp
-uv sync          # or: python3 -m venv .venv && source .venv/bin/activate && pip install -e .
-```
+### I want to use Nexus tools inside a Claude Code session
 
-### Server / n8n
+No separate install needed — `uvx` fetches the package on demand.
 
 ```bash
-uvx --reinstall nexus-toolkit
-systemctl --user restart nexus-sse
+# Add the MCP server
+claude mcp add nexus -- uvx --refresh --from nexus-toolkit nexus-mcp
+
+# Verify
+claude mcp list   # nexus ✓ Connected
 ```
 
----
+All 9 MCP tools are now available in every Claude Code session — pipeline tools (`ingest_figma_zip`, `remap_to_golden_path`, `validate_output`, …) and agent tools (`run_agent`, `list_agents`).
 
-## Configuration
+---
 
-### Claude Code (CLI)
+### I want to use Nexus in Claude Desktop or Cursor
 
-```bash
-# uvx (recommended)
-claude mcp add nexus -- uvx nexus-toolkit
+No separate install needed. Add one entry to your config file and restart the app.
 
-# local dev
-claude mcp add nexus --scope project -- \
-  $(pwd)/.venv/bin/python $(pwd)/nexus_server.py
+Config file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-claude mcp list   # verify: nexus - ✓ Connected
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "nexus-toolkit", "nexus-mcp"]
+    }
+  }
+}
 ```
 
-### n8n (HTTP / streamable-http)
+Nexus tools will appear in the tool picker after restart.
 
-Run the server in HTTP mode so n8n can reach it over the network:
+---
 
-```bash
-# Development (dev install)
-MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
-  .venv/bin/python nexus_server.py
+### I want to automate workflows with n8n
 
-# uvx
-MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
-  uvx nexus-toolkit
+Run Nexus as a persistent HTTP MCP server — your n8n instance calls its tools to automate code review, security scanning, QA gates, and more.
+
+```bash
+# Start in HTTP mode (uvx — no prior install needed)
+MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 uvx --from nexus-toolkit nexus-mcp
 ```
 
 In n8n, set the MCP Client node **Endpoint URL** to:
@@ -220,29 +237,53 @@ In n8n, set the MCP Client node **Endpoint URL** to:
 http://<server-ip>:3900/mcp
 ```
 
-> **Note:** The server binds to `0.0.0.0` so it is reachable from n8n on any interface.
-> `stateless_http` is enabled, so tool calls work without a prior MCP initialize handshake
-> (required for n8n SSH nodes that call the server directly via curl/HTTP).
+Nexus tools (`run_agent`, pipeline tools, `nexus_search`) are then callable from any n8n workflow node.
 
 ---
 
-### Claude Desktop / Cursor
+### Development install (contribute / modify)
 
-Config location:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+git clone https://github.com/rcdelacruz/nexus-toolkit.git
+cd nexus-toolkit
+uv sync   # or: python3 -m venv .venv && source .venv/bin/activate && pip install -e .
+```
+
+---
 
+## Updating
+
+### Auto-update (recommended for uvx setups)
+
+Add `--refresh` to your uvx command once — Nexus checks PyPI on every startup and updates automatically when a new version is available.
+
+**Claude Code:**
+```bash
+claude mcp add nexus -- uvx --refresh --from nexus-toolkit nexus-mcp
+```
+
+**Claude Desktop / Cursor** — edit your config:
 ```json
 {
   "mcpServers": {
     "nexus": {
       "command": "uvx",
-      "args": ["nexus-toolkit"]
+      "args": ["--refresh", "--from", "nexus-toolkit", "nexus-mcp"]
     }
   }
 }
 ```
 
+> `--refresh` adds ~1–2 seconds at startup while uvx checks PyPI. If no new version is available, it starts immediately.
+
+### Manual update
+
+| Integration | Command |
+|---|---|
+| **CLI** (pip / uv tool) | `pip install --upgrade nexus-toolkit` or `uv tool upgrade nexus-toolkit` |
+| **Claude Code / Desktop / Cursor** (uvx) | `uvx --reinstall --from nexus-toolkit nexus-mcp` then restart the app |
+| **n8n HTTP server** (persistent process) | `uvx --reinstall --from nexus-toolkit nexus-mcp` then restart the process |
+
 ---
 
 ## Usage
@@ -396,7 +437,13 @@ nexus workflow run workflow-review-security src/api/routes.ts
 
 ### MCP (Claude Code / n8n)
 
-The MCP server is unchanged — all 7 pipeline tools remain available as before. The CLI and MCP server share the same codebase; both entry points call the same underlying functions.
+The MCP server exposes all tools across all four capabilities. The CLI and MCP server share the same codebase.
+
+| MCP tool group | Tools |
+|----------------|-------|
+| Search & Read | `nexus_search` · `nexus_read` |
+| Design-to-Code Pipeline | `ingest_figma_zip` · `ingest_from_prompt` · `ingest_from_codebase` · `remap_to_golden_path` · `validate_output` · `package_output` · `update_file_in_tree` |
+| Dev-Workflow Agents | `run_agent` · `list_agents` |
 
 ---
 
@@ -428,7 +475,7 @@ Here is my Figma Make export as base64: <PASTE>
 Project name: dashboard-app, golden path: nextjs-fullstack
 ```
 
-#### Starting point B — Text description (no Figma file needed)
+#### Starting point B — Text description (no Figma Make file needed)
 
 ```
 Build a SaaS landing page with a hero section, features grid, pricing table,
@@ -552,7 +599,7 @@ Seeds the golden path reference boilerplate, classifies Figma/prompt/codebase fi
 Runs static analysis on the generated file tree before packaging. Checks for:
 - Missing required files (per `manifest.json`)
 - Broken `@/` imports
-- Leftover Figma artifacts (`React.FC`, bare `import React`, inline styles)
+- Leftover Figma Make artifacts (`React.FC`, bare `import React`, inline styles)
 - Missing `"use client"` on components that use hooks or event handlers
 - Default exports in `components/` (should be named exports)
 - `oklch()` color usage (must be `hsl()`)

{nexus_toolkit-2.2.0 → nexus_toolkit-2.3.0}/README.md

@@ -1,15 +1,22 @@
 # Nexus — Enterprise Dev Toolkit
 
-> **The Hybrid Search, Retrieval & Design-to-Code Engine for AI Agents.**
+> **Design-to-Code pipeline · 22 Software Development Lifecycle (SDLC) agents · Workflow commands · Hybrid search — all powered by Claude Code.**
 
-Nexus combines semantic web search, documentation-optimised reading, and a **Design → Production Code pipeline** powered by golden path conventions. Feed it a Figma Make export, a text description, or an existing codebase — get back clean, runnable production code in your chosen stack.
+Nexus is an enterprise dev toolkit with four integrated capabilities:
+
+| Capability | What it does |
+|------------|-------------|
+| **Design-to-Code Pipeline** | Turn a [Figma Make](https://www.figma.com/make) export, text description, or existing codebase into production-ready code in your chosen stack — via golden path conventions and Claude-powered transformation |
+| **Dev-Workflow Agents** | 22 specialized Claude agents covering every SDLC stage: code review, security, QA, deployment, architecture, database, monitoring, and more |
+| **Workflow Commands** | 11 multi-step orchestration workflows — design → implement → review → deploy → document |
+| **Hybrid Search & Read** | Web search and documentation-optimised reading for AI agents (`nexus_search`, `nexus_read`) |
 
 **Two ways to use Nexus:**
 
 | Mode | How | Best for |
 |------|-----|----------|
-| **CLI** (`nexus`) | Install via one-liner, run from terminal | Local development, standalone use |
-| **MCP server** (`nexus-mcp`) | Add to Claude Code / n8n / Claude Desktop | AI agent workflows, n8n automation |
+| **CLI** (`nexus`) | Install via one-liner, run from terminal | Local development, CI scripts, standalone use |
+| **MCP server** | Add to Claude Code / n8n / Claude Desktop | AI agent workflows, n8n DevSecOps automation |
 
 ---
 
@@ -74,7 +81,7 @@ flowchart TD
 
 The agent reads queue files one at a time, transforms each component, updates `04_file_tree.json`, deletes the queue file, and repeats until `05_queue/` is empty.
 
-The `Project components` list is the key guard: when generating a page or layout, the agent only imports components from this list — never reference boilerplate stubs (e.g. `Features.tsx`, `CTA.tsx`) that appear in the file tree but were not part of the Figma source.
+The `Project components` list is the key guard: when generating a page or layout, the agent only imports components from this list — never reference boilerplate stubs (e.g. `Features.tsx`, `CTA.tsx`) that appear in the file tree but were not part of the Figma Make source.
 
 | Golden Path | Stack |
 |-------------|-------|
@@ -124,68 +131,78 @@ Specialized Claude Code agents for every stage of the SDLC — code review, secu
 
 ---
 
-## Installation
+## Installation & Integration
+
+Pick the use case that matches what you want to do — each one is self-contained.
+
+---
 
-**Prerequisites:** Python 3.10+
+### I want to generate code from a Figma Make export or prompt
 
-### Option 1: One-liner (recommended)
+**Prerequisites:** Python 3.10+, [`claude` CLI](https://claude.ai/code) installed and authenticated
 
 ```bash
+# 1. Install nexus-toolkit
 curl -fsSL https://nexus.coderstudio.co/install.sh | bash
-```
+# or: pip install nexus-toolkit  /  uv tool install nexus-toolkit
 
-### Option 2: pip / uv
+# 2. Install and authenticate Claude Code (required for transform + agent commands)
+npm install -g @anthropic-ai/claude-code
+claude login
 
-```bash
-pip install nexus-toolkit
-# or
-uv tool install nexus-toolkit
+# 3. Run
+nexus run prompt "A SaaS dashboard" --golden-path nextjs-fullstack --project-name my-app
+nexus run zip ~/Downloads/figma-export.zip --golden-path nextjs-fullstack --project-name my-app
 ```
 
-### Option 3: Development install
+---
 
-```bash
-git clone https://github.com/rcdelacruz/nexus-mcp.git
-cd nexus-mcp
-uv sync          # or: python3 -m venv .venv && source .venv/bin/activate && pip install -e .
-```
+### I want to use Nexus tools inside a Claude Code session
 
-### Server / n8n
+No separate install needed — `uvx` fetches the package on demand.
 
 ```bash
-uvx --reinstall nexus-toolkit
-systemctl --user restart nexus-sse
+# Add the MCP server
+claude mcp add nexus -- uvx --refresh --from nexus-toolkit nexus-mcp
+
+# Verify
+claude mcp list   # nexus ✓ Connected
 ```
 
----
+All 9 MCP tools are now available in every Claude Code session — pipeline tools (`ingest_figma_zip`, `remap_to_golden_path`, `validate_output`, …) and agent tools (`run_agent`, `list_agents`).
 
-## Configuration
+---
 
-### Claude Code (CLI)
+### I want to use Nexus in Claude Desktop or Cursor
 
-```bash
-# uvx (recommended)
-claude mcp add nexus -- uvx nexus-toolkit
+No separate install needed. Add one entry to your config file and restart the app.
 
-# local dev
-claude mcp add nexus --scope project -- \
-  $(pwd)/.venv/bin/python $(pwd)/nexus_server.py
+Config file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-claude mcp list   # verify: nexus - ✓ Connected
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "nexus-toolkit", "nexus-mcp"]
+    }
+  }
+}
 ```
 
-### n8n (HTTP / streamable-http)
+Nexus tools will appear in the tool picker after restart.
 
-Run the server in HTTP mode so n8n can reach it over the network:
+---
 
-```bash
-# Development (dev install)
-MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
-  .venv/bin/python nexus_server.py
+### I want to automate workflows with n8n
 
-# uvx
-MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 \
-  uvx nexus-toolkit
+Run Nexus as a persistent HTTP MCP server — your n8n instance calls its tools to automate code review, security scanning, QA gates, and more.
+
+```bash
+# Start in HTTP mode (uvx — no prior install needed)
+MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3900 uvx --from nexus-toolkit nexus-mcp
 ```
 
 In n8n, set the MCP Client node **Endpoint URL** to:
@@ -194,29 +211,53 @@ In n8n, set the MCP Client node **Endpoint URL** to:
 http://<server-ip>:3900/mcp
 ```
 
-> **Note:** The server binds to `0.0.0.0` so it is reachable from n8n on any interface.
-> `stateless_http` is enabled, so tool calls work without a prior MCP initialize handshake
-> (required for n8n SSH nodes that call the server directly via curl/HTTP).
+Nexus tools (`run_agent`, pipeline tools, `nexus_search`) are then callable from any n8n workflow node.
 
 ---
 
-### Claude Desktop / Cursor
+### Development install (contribute / modify)
 
-Config location:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+git clone https://github.com/rcdelacruz/nexus-toolkit.git
+cd nexus-toolkit
+uv sync   # or: python3 -m venv .venv && source .venv/bin/activate && pip install -e .
+```
+
+---
 
+## Updating
+
+### Auto-update (recommended for uvx setups)
+
+Add `--refresh` to your uvx command once — Nexus checks PyPI on every startup and updates automatically when a new version is available.
+
+**Claude Code:**
+```bash
+claude mcp add nexus -- uvx --refresh --from nexus-toolkit nexus-mcp
+```
+
+**Claude Desktop / Cursor** — edit your config:
 ```json
 {
   "mcpServers": {
     "nexus": {
       "command": "uvx",
-      "args": ["nexus-toolkit"]
+      "args": ["--refresh", "--from", "nexus-toolkit", "nexus-mcp"]
     }
   }
 }
 ```
 
+> `--refresh` adds ~1–2 seconds at startup while uvx checks PyPI. If no new version is available, it starts immediately.
+
+### Manual update
+
+| Integration | Command |
+|---|---|
+| **CLI** (pip / uv tool) | `pip install --upgrade nexus-toolkit` or `uv tool upgrade nexus-toolkit` |
+| **Claude Code / Desktop / Cursor** (uvx) | `uvx --reinstall --from nexus-toolkit nexus-mcp` then restart the app |
+| **n8n HTTP server** (persistent process) | `uvx --reinstall --from nexus-toolkit nexus-mcp` then restart the process |
+
 ---
 
 ## Usage
@@ -370,7 +411,13 @@ nexus workflow run workflow-review-security src/api/routes.ts
 
 ### MCP (Claude Code / n8n)
 
-The MCP server is unchanged — all 7 pipeline tools remain available as before. The CLI and MCP server share the same codebase; both entry points call the same underlying functions.
+The MCP server exposes all tools across all four capabilities. The CLI and MCP server share the same codebase.
+
+| MCP tool group | Tools |
+|----------------|-------|
+| Search & Read | `nexus_search` · `nexus_read` |
+| Design-to-Code Pipeline | `ingest_figma_zip` · `ingest_from_prompt` · `ingest_from_codebase` · `remap_to_golden_path` · `validate_output` · `package_output` · `update_file_in_tree` |
+| Dev-Workflow Agents | `run_agent` · `list_agents` |
 
 ---
 
@@ -402,7 +449,7 @@ Here is my Figma Make export as base64: <PASTE>
 Project name: dashboard-app, golden path: nextjs-fullstack
 ```
 
-#### Starting point B — Text description (no Figma file needed)
+#### Starting point B — Text description (no Figma Make file needed)
 
 ```
 Build a SaaS landing page with a hero section, features grid, pricing table,
@@ -526,7 +573,7 @@ Seeds the golden path reference boilerplate, classifies Figma/prompt/codebase fi
 Runs static analysis on the generated file tree before packaging. Checks for:
 - Missing required files (per `manifest.json`)
 - Broken `@/` imports
-- Leftover Figma artifacts (`React.FC`, bare `import React`, inline styles)
+- Leftover Figma Make artifacts (`React.FC`, bare `import React`, inline styles)
 - Missing `"use client"` on components that use hooks or event handlers
 - Default exports in `components/` (should be named exports)
 - `oklch()` color usage (must be `hsl()`)

{nexus_toolkit-2.2.0 → nexus_toolkit-2.3.0}/nexus_cli.py

@@ -99,7 +99,7 @@ _THEME = Theme({
 console = Console(theme=_THEME)
 
 
-_VERSION = "2.2.0"
+_VERSION = "2.3.0"
 
 _LOGO = """\
 [cyan]███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗[/cyan]
@@ -1044,9 +1044,17 @@ def agent_run(
     claude_path: Annotated[
         Optional[str], typer.Option("--claude-path", help="Path to claude CLI.")
     ] = None,
+    memory_path: Annotated[
+        Optional[pathlib.Path],
+        typer.Option("--memory-path", help="Path to .claude/memory/agents/ for persistent agent memory."),
+    ] = None,
+    remember: Annotated[
+        bool, typer.Option("--remember", help="Write findings back to memory after run.")
+    ] = False,
 ) -> None:
     """Run a dev-workflow agent (e.g. code-reviewer, security) against a file or inline context."""
     import sys as _sys
+    from tools.devsecops.memory import build_memory_context_block, update_memory
 
     agent_file = _find_dev_agent(agent_name)
 
@@ -1066,14 +1074,36 @@ def agent_run(
         console.print("[red]✗ Provide a file path or --context string.[/red]")
         raise typer.Exit(1)
 
+    # Auto-detect memory_path from cwd if --remember given without --memory-path
+    resolved_memory_path: Optional[pathlib.Path] = memory_path
+    if remember and not resolved_memory_path:
+        candidate = pathlib.Path.cwd()
+        for _ in range(3):
+            if (candidate / ".git").exists() or (candidate / "package.json").exists():
+                resolved_memory_path = candidate / ".claude" / "memory" / "agents"
+                break
+            parent = candidate.parent
+            if parent == candidate:
+                break
+            candidate = parent
+
+    # Prepend past memory to input if memory path is available
+    if resolved_memory_path:
+        memory_block = build_memory_context_block(str(resolved_memory_path), agent_name)
+        if memory_block:
+            input_text = memory_block + "\n\n" + input_text
+
     claude_bin = _find_claude(claude_path)
 
     meta = Table.grid(padding=(0, 2))
-    meta.add_column(style="dim white", min_width=10)
+    meta.add_column(style="dim white", min_width=12)
     meta.add_column(style="white")
     meta.add_row("agent", f"[cyan]{agent_name}[/cyan]")
     meta.add_row("source", source_label)
     meta.add_row("model", model)
+    if resolved_memory_path:
+        mem_label = "on" if resolved_memory_path.exists() else "on (new)"
+        meta.add_row("memory", f"[dim]{mem_label}[/dim]  [dim white]{resolved_memory_path}[/dim white]")
     console.print()
     console.print(Panel(meta, title="[bold] nexus agent run [/bold]", box=box.ROUNDED, border_style="bright_black", padding=(0, 1)))
     console.print()
@@ -1089,8 +1119,24 @@ def agent_run(
 
     console.print(Rule(agent_name, style="bright_black"))
     console.print()
+    captured_output = ""
+    returncode = 0
     try:
-        result = subprocess.run(cmd, text=True, capture_output=False)
+        if resolved_memory_path and remember:
+            # Stream output to terminal while capturing for memory write
+            import io as _io
+            proc = subprocess.Popen(cmd, text=True, stdout=subprocess.PIPE, stderr=None)
+            assert proc.stdout is not None
+            buf = _io.StringIO()
+            for line in proc.stdout:
+                print(line, end="", flush=True)
+                buf.write(line)
+            proc.wait()
+            captured_output = buf.getvalue().strip()
+            returncode = proc.returncode
+        else:
+            result = subprocess.run(cmd, text=True, capture_output=False)
+            returncode = result.returncode
     except KeyboardInterrupt:
         console.print()
         console.print(f"\n  [yellow]⚠[/yellow]  interrupted\n")
@@ -1098,9 +1144,19 @@ def agent_run(
 
     console.print()
     console.print(Rule(style="bright_black"))
-    if result.returncode != 0:
-        _step_error("agent run", f"claude exited with code {result.returncode}")
-        raise typer.Exit(result.returncode)
+    if returncode != 0:
+        _step_error("agent run", f"claude exited with code {returncode}")
+        raise typer.Exit(returncode)
+
+    # Write findings to memory
+    if resolved_memory_path and remember and captured_output:
+        _, pending_items = update_memory(str(resolved_memory_path), agent_name, captured_output)
+        console.print(f"  [green]●[/green]  memory updated  [dim]{resolved_memory_path}[/dim]")
+        if pending_items:
+            console.print(f"\n  [yellow]⚠[/yellow]  Pending human review:")
+            for item in pending_items:
+                console.print(f"    [yellow]•[/yellow] {item}")
+        console.print()
 
 
 # ── nexus workflow run ────────────────────────────────────────────────────────