nexo-brain 3.0.2 → 3.1.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -20,12 +20,16 @@
 
 Start here:
 - [5-minute quickstart](docs/quickstart-5-minutes.md)
+- [Workflow quickstart](docs/workflows-quickstart.md)
+- [Supported client guides](docs/integrations/cursor.md)
+- [Docker setup](docs/docker-setup.md)
 - [Architecture visuals](docs/architecture-visuals.md)
 - [Memory classes](docs/memory-classes.md)
 - [Session portability](docs/session-portability.md)
 - [Python SDK](docs/sdk-python.md)
 - [Reference verticals](docs/reference-verticals.md)
 - [Measured compare scorecard](compare/README.md)
+- [Memory benchmark harness](benchmarks/README.md)
 - [Public contribution guide](docs/public-contribution.md)
 
 Every time you close a session, everything is lost. Your agent doesn't remember yesterday's decisions, repeats the same mistakes, and starts from zero. NEXO Brain fixes this with a cognitive architecture modeled after how human memory actually works.
@@ -89,6 +93,17 @@ Versions `3.0.0` and `3.0.1` close the next execution gap:
 | Runtime doctor parity audit | Yes | Yes | Shared-brain only |
 | Recommended today | Yes | Supported | Shared-brain companion |
 
+### Supported Clients
+
+| Client | Status | Integration style | Notes |
+|--------|--------|-------------------|-------|
+| Claude Code | First-class | Managed install + hooks + bootstrap | Deepest NEXO parity today |
+| Codex | First-class | Managed install + bootstrap + transcript parity | Best non-Claude terminal path |
+| Claude Desktop | Companion | MCP-only shared brain | Useful as read/chat companion |
+| Cursor | Documented companion | MCP + `.cursor/rules` | Good editor pairing; no Deep Sleep transcript parity yet |
+| Windsurf | Documented companion | MCP + `.windsurf/rules` or repo `AGENTS.md` | Native MCP support, manual companion mode |
+| Gemini CLI | Adapter included | MCP + `GEMINI.md` | Best when you want Gemini as a shared-brain companion, not the primary NEXO runtime |
+
 ## The Problem
 
 AI coding agents are powerful but amnesic:
@@ -669,6 +684,27 @@ The installer handles everything and syncs the same `nexo` MCP brain into Claude
   +----------------------------------------------------------+
 ```
 
+### Docker Compose
+
+NEXO now ships a root-level [`docker-compose.yml`](docs/docker-setup.md) for a persistent containerized runtime. It does two things at once:
+
+- keeps `NEXO_HOME` on a named volume
+- exposes a remote MCP endpoint at `http://localhost:8000/mcp` for IDEs that support HTTP/SSE MCP
+
+Start it with:
+
+```bash
+docker compose up -d
+```
+
+For Claude Code and Codex, keep using stdio and point the MCP command at the running container:
+
+```bash
+docker compose exec -T nexo python src/server.py
+```
+
+That gives you the same persistent brain in the container while keeping terminal clients on their native stdio transport. The full step-by-step flow, health checks, and config examples live in [docs/docker-setup.md](docs/docker-setup.md).
+
 ### Starting a Session
 
 After install, use the runtime CLI:
@@ -896,6 +932,18 @@ When Claude Desktop is installed, `nexo-brain`, `nexo update`, and `nexo clients
 
 When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop. If selected during install, `nexo chat` can open Codex directly and background automation can also run through Codex. Interactive `nexo chat` launches use Codex's aggressive no-confirmation mode so the session does not stall on repetitive approval prompts. The current recommended Codex profile is `gpt-5.4` with `xhigh` reasoning. Runtime Doctor also audits recent Codex sessions for NEXO startup markers and conditioned-file protocol discipline so parity drift does not hide behind the lack of native Claude-style hooks.
 
+### Cursor
+
+Cursor works well as a documented companion client. Point Cursor at the same local `nexo` MCP server and add a project rule that forces `nexo_startup`, `nexo_heartbeat`, and the protocol path on real work. See [docs/integrations/cursor.md](docs/integrations/cursor.md).
+
+### Windsurf
+
+Windsurf/Cascade supports MCP plus durable repo rules. Use the same local `nexo` server and add NEXO startup/protocol instructions in `.windsurf/rules/` or your repo `AGENTS.md`. See [docs/integrations/windsurf.md](docs/integrations/windsurf.md).
+
+### Gemini CLI
+
+Gemini CLI can share the same local NEXO brain through `mcpServers` in `~/.gemini/settings.json` plus a repo `GEMINI.md`. NEXO now ships a starter adapter in [adapters/gemini/README.md](adapters/gemini/README.md).
+
 ### OpenClaw
 
 NEXO Brain also works as a cognitive memory backend for [OpenClaw](https://github.com/openclaw/openclaw):
@@ -980,6 +1028,20 @@ If NEXO Brain is useful to you, consider:
 
 [![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 
+## Memory Benchmark Snapshot
+
+The full harness is in [benchmarks/README.md](benchmarks/README.md). The first checked-in micro-benchmark compares the NEXO runtime against a static `CLAUDE.md`-only baseline on five recall-heavy scenarios:
+
+| Scenario | NEXO full stack | Static `CLAUDE.md` | No memory |
+|----------|-----------------|--------------------|-----------|
+| Decision rationale recall | Pass | Partial | Fail |
+| User preference recall | Pass | Partial | Fail |
+| Repeat-error avoidance | Pass | Partial | Fail |
+| Resume interrupted task | Pass | Partial | Fail |
+| Related-context stitching | Pass | Fail | Fail |
+
+See [benchmarks/results/memory-recall-vs-static.md](benchmarks/results/memory-recall-vs-static.md) for the rubric, prompt shape, and first-run notes.
+
 ## Changelog
 
 ### v3.0.1 — Python 3.10 Compatibility Patch (2026-04-06)

package/community/launch/2026-04-v3-0-2/case-study-outreach.md

@@ -0,0 +1,36 @@
+# NEXO case-study outreach template
+
+Use this to ask operators for a public NEXO story without making the ask heavy.
+
+## Short outreach message
+
+Hi,
+
+I am collecting a few public NEXO operator stories so the project can show real-world usage more clearly.
+
+If NEXO has been useful in your setup, would you be open to sending a short note with:
+
+- your main client surface
+- what problem you wanted to solve
+- which NEXO pieces actually mattered
+- one concrete example of how it helped
+
+Even 5-8 lines is enough. If you prefer, I can turn it into a draft and send it back for approval before anything is published.
+
+Thanks.
+
+## Structured version
+
+Ask for:
+
+- Role or setup
+- Main client or clients
+- What was painful before NEXO
+- What changed after using NEXO
+- Which feature or workflow mattered most
+- Whether the story can be quoted publicly
+
+## Public proof rule
+
+Do not fabricate company names, usage scale, or testimonials.
+If a case is not approved for public quoting, keep it private until the operator confirms.

package/community/launch/2026-04-v3-0-2/devto-v3-0-2.md

@@ -0,0 +1,91 @@
+# NEXO v3.0.2: libre shared brain, review-gated Evolution, and a cleaner public path
+
+NEXO is free/libre, open-source software for people who want a local cognitive runtime instead of another isolated AI session.
+
+At the center is a simple promise:
+
+- one shared brain across Claude Code, Codex, Claude Desktop, and other MCP-compatible clients
+- persistent local memory instead of session-only context
+- a real runtime around memory: doctor, workflows, reminders, scripts, followups, and review-gated Evolution
+
+With `v3.0.2`, the product itself is not radically different, but the public path is much clearer.
+
+## What changed in this release
+
+Three things matter most:
+
+1. Public integrations and release publishing were hardened.
+2. The public site now explains NEXO faster, with demo-first entry points and sharper search-intent pages.
+3. The runtime keeps moving toward a more disciplined public Evolution loop, where opt-in contributors can propose bounded changes via Draft PRs and maintainers still decide what gets merged.
+
+## Why "libre" matters here
+
+NEXO is not just "free as in price."
+
+It is AGPL-licensed, inspectable, forkable, and local-first by design. That matters because memory systems are infrastructure. If your agent remembers project state, release habits, and past failures, you should be able to inspect the system that stores and retrieves that memory.
+
+There is no hidden hosted control plane behind the product story.
+
+## The shortest way to understand NEXO now
+
+Instead of sending everyone straight into a huge feature map, the public site now starts with three short demos:
+
+- Install in 60 seconds
+- Shared brain across Claude Code and Codex
+- Review-gated public Evolution with Draft PR pause/resume behavior
+
+There are also three search-intent pages for:
+
+- Claude Code memory
+- Codex memory
+- Open-source MCP memory server
+
+That matters because most people do not search for "cognitive runtime." They search for a concrete need.
+
+## What NEXO is best at today
+
+The strongest fit today is still the operator who wants:
+
+- local persistent memory
+- a shared brain across more than one client
+- guardrails before changes
+- durable workflows and followups
+- an inspectable runtime instead of a black box
+
+Claude Code remains the deepest integration path.
+Codex is also supported and benefits from the same shared-brain model.
+
+## Install
+
+```bash
+npx nexo-brain
+```
+
+After install, the fastest sanity check is:
+
+```bash
+nexo doctor
+```
+
+## Public links
+
+- Release: https://github.com/wazionapps/nexo/releases/tag/v3.0.2
+- Home: https://nexo-brain.com
+- Demos: https://nexo-brain.com/demos/
+- Solutions: https://nexo-brain.com/solutions/
+- Docs: https://nexo-brain.com/docs/
+- GitHub: https://github.com/wazionapps/nexo
+- npm: https://www.npmjs.com/package/nexo-brain
+
+## What comes next
+
+The next public step is not "more adjectives."
+
+It is more proof:
+
+- more operator case studies
+- more demo material
+- more high-intent entry pages
+- more disciplined public Evolution cycles that generate reviewable improvements
+
+If you use Claude Code, Codex, or other MCP-compatible clients and want a local shared brain rather than another stateless session, NEXO is ready to try now.

package/community/launch/2026-04-v3-0-2/github-discussion-v3-0-2.md

@@ -0,0 +1,58 @@
+# NEXO v3.0.2 is out: libre shared brain, cleaner demos, and sharper public entry points
+
+`v3.0.2` is now published:
+
+- Release: https://github.com/wazionapps/nexo/releases/tag/v3.0.2
+- npm: https://www.npmjs.com/package/nexo-brain
+- Site: https://nexo-brain.com
+
+This release matters less because of one giant feature and more because the public product story is now much easier to understand.
+
+## What NEXO is
+
+NEXO is libre/open-source software for a local cognitive runtime with:
+
+- one shared brain across Claude Code, Codex, Claude Desktop, and other MCP-compatible clients
+- persistent local memory
+- doctor diagnostics, workflows, scripts, reminders, followups, and public Evolution discipline around that memory layer
+
+## What changed
+
+- release and public integration verification were hardened
+- the public website now has a demo-first path
+- new search-intent pages explain where NEXO fits without forcing everyone through the full docs first
+
+New public surfaces:
+
+- Demos: https://nexo-brain.com/demos/
+- Solutions: https://nexo-brain.com/solutions/
+- Use cases: https://nexo-brain.com/use-cases/
+
+## The three shortest demos
+
+1. Install in 60 seconds
+2. Shared brain across Claude Code and Codex
+3. Review-gated public Evolution with Draft PR pause/resume behavior
+
+## Why this direction
+
+The old problem was not lack of capability. It was that the path from "I heard about NEXO" to "I understand what it actually does" was too long.
+
+The new public surfaces are designed to fix that while keeping the product technically honest:
+
+- local-first
+- inspectable
+- AGPL-licensed
+- stronger for real operators than for generic AI hype
+
+## If you are already using NEXO
+
+The most useful thing right now is public proof.
+
+If you have a real setup or workflow where NEXO helps, reply here or open a new discussion with:
+
+- your main client surface
+- the problem you wanted to solve
+- which NEXO pieces actually mattered
+
+That will help turn the current honest use-case patterns into stronger public case studies.

package/community/launch/2026-04-v3-0-2/x-thread-v3-0-2.md

@@ -0,0 +1,60 @@
+1. NEXO v3.0.2 is out.
+
+Libre/open-source shared brain for Claude Code, Codex, Claude Desktop, and other MCP-compatible clients.
+
+Local memory, workflows, doctor, followups, scripts, and review-gated Evolution.
+
+Release:
+https://github.com/wazionapps/nexo/releases/tag/v3.0.2
+
+2. The main idea is simple:
+
+NEXO is not just "memory for AI."
+
+It is a local cognitive runtime so your assistant can keep operator context across sessions instead of resetting every time the terminal resets.
+
+3. We also cleaned up the public path.
+
+Three short demos now explain the product faster than a feature list:
+
+- install in 60 seconds
+- shared brain across Claude Code + Codex
+- review-gated public Evolution
+
+https://nexo-brain.com/demos/
+
+4. We added sharper search-intent pages too:
+
+- Claude Code memory
+- Codex memory
+- open-source MCP memory server
+
+https://nexo-brain.com/solutions/
+
+5. NEXO is AGPL-3.0 and local-first by design.
+
+If your assistant remembers your work, you should be able to inspect and fork the system behind that memory.
+
+https://github.com/wazionapps/nexo
+
+6. Strongest fit today:
+
+- operators using Claude Code or Codex
+- people who want one shared brain across clients
+- local-first workflows
+- teams that want real runtime discipline, not just retrieval
+
+7. If you want to try it:
+
+```bash
+npx nexo-brain
+nexo doctor
+```
+
+8. If you already use it, the next thing we need is public proof.
+
+Real setups.
+Real use cases.
+Real feedback.
+
+That is how the project gets easier to trust.

package/hooks/hooks.json

@@ -38,6 +38,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|Delete",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/protocol-pretool-guardrail.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/client_sync.py

@@ -342,6 +342,12 @@ CORE_HOOK_SPECS = [
         "timeout": 10,
         "script": "session-stop.sh",
     },
+    {
+        "event": "PreToolUse",
+        "identity": "protocol-pretool-guardrail.sh",
+        "timeout": 5,
+        "script": "protocol-pretool-guardrail.sh",
+    },
     {
         "event": "PostToolUse",
         "identity": "capture-tool-logs.sh",

package/src/db/_personal_scripts.py

@@ -62,8 +62,8 @@ def _safe_slug(value: str) -> str:
 
 def _ensure_script_id(conn, name: str, path: str) -> str:
     existing = conn.execute(
-        "SELECT id FROM personal_scripts WHERE path = ? OR name = ? ORDER BY path = ? DESC LIMIT 1",
-        (path, name, path),
+        "SELECT id FROM personal_scripts WHERE path = ? LIMIT 1",
+        (path,),
     ).fetchone()
     if existing:
         return existing["id"]

package/src/doctor/providers/runtime.py

@@ -627,11 +627,12 @@ def _client_assumption_regressions() -> list[str]:
     src_root = NEXO_CODE if (NEXO_CODE / "server.py").is_file() else (NEXO_CODE / "src")
     if not src_root.is_dir():
         return []
+    src_root = src_root.resolve()
     backup_root = (NEXO_HOME / "backups").resolve()
     contrib_root = (NEXO_HOME / "contrib").resolve()
-    allowed_claude_projects = {
-        (src_root / "scripts" / "deep-sleep" / "collect.py").resolve(),
-        Path(__file__).resolve(),
+    allowed_relative_paths = {
+        Path("scripts") / "deep-sleep" / "collect.py",
+        Path("doctor") / "providers" / "runtime.py",
     }
     offenders: list[str] = []
     for path in src_root.rglob("*.py"):
@@ -650,8 +651,12 @@ def _client_assumption_regressions() -> list[str]:
                 continue
         except Exception:
             pass
-        if ".claude/projects" in text and resolved not in allowed_claude_projects:
-            offenders.append(f"{path.relative_to(NEXO_CODE)} hardcodes ~/.claude/projects")
+        try:
+            relative_path = resolved.relative_to(src_root)
+        except Exception:
+            relative_path = path.relative_to(src_root)
+        if ".claude/projects" in text and relative_path not in allowed_relative_paths:
+            offenders.append(f"{relative_path} hardcodes ~/.claude/projects")
     collect_path = src_root / "scripts" / "deep-sleep" / "collect.py"
     try:
         collect_text = collect_path.read_text()

package/src/evolution_cycle.py

@@ -350,7 +350,12 @@ Max 3 proposals. Quality over quantity. If nothing needs improving, say so."""
     return prompt
 
 
-def build_public_contribution_prompt(*, repo_root: str, cycle_number: int) -> str:
+def build_public_contribution_prompt(
+    *,
+    repo_root: str,
+    cycle_number: int,
+    queued_candidate: dict | None = None,
+) -> str:
     """Prompt for the public-core contributor mode.
 
     This prompt must never rely on private runtime state. It should inspect only
@@ -358,6 +363,27 @@ def build_public_contribution_prompt(*, repo_root: str, cycle_number: int) -> st
     by returning machine-readable summary JSON.
     """
 
+    queued_section = ""
+    if queued_candidate:
+        queued_files = "\n".join(
+            f"- {path}" for path in (queued_candidate.get("files_changed") or [])[:20]
+        ) or "- (no files recorded)"
+        queued_source = str((queued_candidate.get("metadata") or {}).get("source") or "managed-runtime")
+        queued_section = f"""
+
+PRIORITY PUBLIC-PORT QUEUE ITEM:
+- Source: {queued_source}
+- Title: {str(queued_candidate.get("title") or "").strip()}
+- Why it matters: {str(queued_candidate.get("reasoning") or "").strip()}
+- Files originally touched:
+{queued_files}
+
+This item was already fixed or detected outside the public contribution runner.
+Before inventing another improvement, verify whether the public repository still
+needs the same change and port it if necessary. If the repo is already correct,
+make the smallest validating change that captures the same gap.
+"""
+
     return f"""You are NEXO Public Evolution.
 
 You are running inside an isolated checkout of the public NEXO repository.
@@ -389,6 +415,7 @@ What to do:
 
 Cycle: #{cycle_number}
 Quality over quantity. One strong improvement is better than three weak ones.
+{queued_section}
 """