nowledge-co · HamsteRider-m · Apr 9, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 11, 2026
diff --git a/.ccb/.claude-session b/.ccb/.claude-session
@@ -0,0 +1,16 @@
+{
+  "session_id": "ai-1775888498-61737",
+  "ccb_project_id": "ea66bbb87cd797287d668bb57a8ab9762f0509c76e37e90cb1e0536d75ec7b72",
+  "work_dir": "/Users/hansonmei/Projects/nowledge-community",
+  "work_dir_norm": "/Users/hansonmei/Projects/nowledge-community",
+  "start_dir": "/Users/hansonmei/Projects/nowledge-community",
+  "terminal": "tmux",
+  "active": false,
+  "started_at": "2026-04-11 14:21:38",
+  "updated_at": "2026-04-13 14:04:31",
+  "pane_id": "%7",
+  "pane_title_marker": "CCB-Claude-ea66bbb8",
+  "claude_session_path": "/Users/hansonmei/.claude/projects/-Users-hansonmei-Projects-nowledge-community/3d8de919-0380-474d-9fef-24b3612d1289.jsonl",
+  "claude_session_id": "3d8de919-0380-474d-9fef-24b3612d1289",
+  "ended_at": "2026-04-13 14:04:31"
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,30 @@
+# Nowledge Community — Agent Guidelines
+
+## Registry
+
+[`integrations.json`](integrations.json) is the **single source of truth** for all Nowledge Mem integrations. It tracks capabilities, versions, install commands, transport, tool naming, and thread save methods.
+
+**When adding or modifying any integration, update `integrations.json` first.** Other surfaces (website `integrations.ts`, desktop app integrations view, README tables, marketplace JSONs) derive from or validate against this file.
+
+The desktop app fetches this file at runtime from `https://raw.githubusercontent.com/nowledge-co/community/main/integrations.json` for plugin update awareness. Changes to the schema (adding/removing/renaming fields) affect:
+- **Rust** (`lib.rs`): `fetch_plugin_registry`, `detect_installed_plugins`, `write_plugin_update_state`
+- **TypeScript** (`plugin-update-manager.ts`): `RegistryIntegration` interface
+- **Python** (`health.py`): `_read_plugin_update_state` reader
+
+## Behavioral Guidance
+
+[`shared/behavioral-guidance.md`](shared/behavioral-guidance.md) defines when plugins should search, save, read Working Memory, and distill. All plugins should align with this shared guidance.
+
+## Plugin Development
+
+See [`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md) for authoring rules, directory layout, and testing expectations.
+
+## Submodules
+
+`nowledge-mem-gemini-cli` is a nested submodule (separate repo with its own release cycle). All other integrations are normal directories in this repo.
+
+## Commit Workflow
+
+When modifying this repo as a submodule of the parent `muscat` repo:
+1. Commit inside `community/` first
+2. Then stage the updated submodule reference in the parent repo
diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ Each directory is a standalone integration. Pick the one that matches your tool.
 | **[Antigravity Trajectory Extractor](https://github.com/jijiamoer/antigravity-trajectory-extractor)** | `git clone https://github.com/jijiamoer/antigravity-trajectory-extractor.git` | Live RPC extraction for Antigravity conversation trajectories. |
 | **[Windsurf Trajectory Extractor](https://github.com/jijiamoer/windsurf-trajectory-extractor)** | `git clone https://github.com/jijiamoer/windsurf-trajectory-extractor.git` | Offline protobuf extraction for Windsurf Cascade conversation history. |
 | **[Cursor Plugin](nowledge-mem-cursor-plugin)** | Link `nowledge-mem-cursor-plugin` into `~/.cursor/plugins/local/nowledge-mem-cursor` | Cursor-native plugin package with a session-start Working Memory hook, bundled MCP config, rules, and honest `save-handoff` semantics. |
-| **[Codex Plugin](nowledge-mem-codex-plugin)** | Copy the full plugin directory, including `.codex-plugin`, to `~/.codex/plugins/cache/local/nowledge-mem/local/` and enable it in `~/.codex/config.toml` | Packaged Codex skills for Working Memory bootstrap, proactive recall guidance, real session save, and distillation. |
+| **[Codex Plugin](nowledge-mem-codex-plugin)** | Copy the full plugin directory, including `.codex-plugin`, to `~/.codex/plugins/cache/local/nowledge-mem/local/`, enable it in `~/.codex/config.toml`, then run the bundled hook installer | Packaged Codex skills for Working Memory bootstrap, proactive recall guidance, and distillation, plus an optional host-level `Stop` hook installer for automatic transcript capture. |
 | **[OpenClaw Plugin](nowledge-mem-openclaw-plugin)** | `openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem` | Full memory lifecycle with memory tools, thread tools, automatic capture, and distillation. |
 | **[Alma Plugin](nowledge-mem-alma-plugin)** | Search Nowledge in Alma official Plugin marketplace | Alma-native plugin with Working Memory, thread-aware recall, structured saves, and optional auto-capture. |
 | **[Bub Plugin](nowledge-mem-bub-plugin)** | `pip install nowledge-mem-bub` | Bub-native plugin: cross-tool knowledge, auto-capture via save_state, Working Memory, and graph exploration. |

diff --git a/docs/PLUGIN_DEVELOPMENT_GUIDE.md b/docs/PLUGIN_DEVELOPMENT_GUIDE.md
@@ -119,7 +119,7 @@ All behavioral heuristics (when to search, when to save, when to read Working Me
 
 ### Skill naming
 
-Skill names use kebab-case and are consistent across all plugins:
+Skill names use kebab-case. Prefer the shared names below for new integrations, but preserve published compatibility exceptions:
 
 | Skill | Purpose |
 |-------|---------|
@@ -131,6 +131,9 @@ Skill names use kebab-case and are consistent across all plugins:
 | `check-integration` | Detect agent, verify setup, guide plugin installation |
 | `status` | Connection and configuration diagnostics |
 
+Published exception:
+- Codex already shipped `working-memory`; keep that name for Codex unless and until a compatible alias is introduced.
+
 ### Autonomous save is required
 
 Every integration's distill/save guidance MUST include proactive save encouragement:

diff --git a/integrations.json b/integrations.json
@@ -110,7 +110,7 @@
         "search": true,
         "distill": true,
         "autoRecall": false,
-        "autoCapture": false,
+        "autoCapture": true,
         "graphExploration": false,
         "status": true
       },
@@ -123,23 +123,24 @@
         "bootstrap": "guided",
         "recall": "guided",
         "distill": "guided",
-        "threads": "explicit-save",
+        "threads": "automatic-capture",
         "bestResultRequires": [
-          "Install the Codex package and enable plugins in ~/.codex/config.toml",
+          "Install the Codex package, enable plugins in ~/.codex/config.toml, then run the bundled hook installer",
           "Keep nmem available on this machine",
+          "Run the hook installer with a Python interpreter that can import nmem_cli",
           "Merge the package AGENTS.md into the project for stronger follow-through"
         ]
       },
       "install": {
-        "command": "mkdir -p ~/.codex/plugins/cache/local/nowledge-mem/local && cp -R nowledge-mem-codex-plugin/. ~/.codex/plugins/cache/local/nowledge-mem/local/",
-        "updateCommand": "cp -R nowledge-mem-codex-plugin/. ~/.codex/plugins/cache/local/nowledge-mem/local/",
+        "command": "mkdir -p ~/.codex/plugins/cache/local/nowledge-mem/local && cp -R nowledge-mem-codex-plugin/. ~/.codex/plugins/cache/local/nowledge-mem/local/ && python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py",
+        "updateCommand": "cp -R nowledge-mem-codex-plugin/. ~/.codex/plugins/cache/local/nowledge-mem/local/ && python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py",
         "configRequired": "[features] plugins = true AND [plugins.\"nowledge-mem@local\"] enabled = true in ~/.codex/config.toml",
         "detectionHint": "Running as Codex CLI agent; ~/.codex/ exists",
         "docsUrl": "/docs/integrations/codex-cli"
       },
       "toolNaming": {
         "convention": "cli-direct",
-        "note": "Packaged Codex skills teach the agent to invoke nmem CLI progressively. Working Memory is the reliable bootstrap; search and distill remain model-driven unless repo guidance tightens policy."
+        "note": "Packaged Codex skills teach the agent to invoke nmem CLI progressively. Working Memory is the reliable bootstrap; search and distill remain model-driven unless repo guidance tightens policy. The bundled host-level Stop hook installer adds automatic transcript capture once installed."
       },
       "skills": ["working-memory", "search-memory", "save-thread", "distill-memory", "status"],
       "slashCommands": []

diff --git a/nowledge-mem-codex-plugin/CHANGELOG.md b/nowledge-mem-codex-plugin/CHANGELOG.md
@@ -1,6 +1,11 @@
 # Changelog
 
 ## [0.1.3] - 2026-04-11
+### Added
+
+- **Bundled Codex hook installer**: added `scripts/install_hooks.py` to install a native Codex `Stop` hook into `~/.codex/hooks.json`, copy the runtime hook into `~/.codex/hooks/`, and enable `codex_hooks = true` in `~/.codex/config.toml`.
+- **Host-level Stop hook runtime**: added `hooks/nmem-stop-save.py`, which reads Codex's `transcript_path`, parses the rollout directly with `nmem_cli.session_import.parse_codex_session_streaming`, and imports the current thread into Mem without relying on `nmem t save --from codex` session discovery.
+- **Plugin validation and release notes**: added `scripts/validate-plugin.mjs` and `RELEASING.md` so the Codex package now has the same explicit release contract as the other maintained integrations in this repo.
 
 ### Improved
 
@@ -11,7 +16,9 @@
 ### Fixed
 
 - **Install copy command**: Codex install/update instructions now preserve hidden files such as `.codex-plugin/plugin.json`.
-- **Docs honesty**: removed wording that implied Codex has lifecycle-hook automation comparable to hosts like Claude Code or OpenClaw.
+- **Hook runtime now uses the installer interpreter**: `scripts/install_hooks.py` now pins the copied `Stop` hook to the same Python interpreter that ran the installer, and it fails fast if that interpreter cannot import `nmem_cli`.
+- **Refresh helper no longer crashes on import**: `scripts/refresh_thread_titles.py` now lazily loads `nmem_cli` and counts generic refresh failures instead of aborting the full run.
+- **Docs honesty**: clarify that Codex memory search and distill remain skill-guided, while automatic transcript capture comes from the optional host-level hook installer.
 
 ## [0.1.2] - 2026-04-06
 

diff --git a/nowledge-mem-codex-plugin/README.md b/nowledge-mem-codex-plugin/README.md
@@ -9,6 +9,7 @@ Switch between Claude Code, Gemini, Cursor, and Codex without losing context. De
 - **Pick up where you left off.** Every session can start from your current priorities, recent decisions, and unresolved questions.
 - **Search when prior work matters.** The plugin teaches Codex when to search memories and threads, especially on continuation-style tasks.
 - **Insights stick around.** The plugin teaches Codex to distill durable decisions and learnings when they emerge.
+- **Automatic transcript capture is available.** Once you run the bundled host-level `Stop` hook installer, Codex can import the real transcript after each completed turn.
 - **Real session history.** Save the full Codex transcript, not just a summary.
 - **Quick diagnostics.** One command to verify everything is connected.
 
@@ -26,7 +27,9 @@ Codex does not give this package hard lifecycle hooks like Claude Code or OpenCl
 
 ## Prerequisites
 
-`nmem` CLI must be in your PATH.
+For day-to-day skill usage, put `nmem` on your PATH.
+
+For automatic `Stop`-hook capture, the Python interpreter that runs `scripts/install_hooks.py` must be able to import `nmem_cli`. `uvx --from nmem-cli nmem` is enough for interactive CLI commands, but it does not make `nmem_cli` importable to Codex's hook runtime by itself.
 
 **Quickest path** (if the Nowledge Mem desktop app is running):
 Settings > Preferences > Developer Tools > Install CLI
@@ -36,9 +39,11 @@ Settings > Preferences > Developer Tools > Install CLI
 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
 uvx --from nmem-cli nmem --version
+python3 -m pip install nmem-cli
+python3 -c "import nmem_cli, nmem_cli.session_import"
 ```
 
-Or `pip install nmem-cli`. Then verify with `nmem status`.
+Then verify with `nmem status`.
 
 ## Install
 
@@ -62,6 +67,12 @@ plugins = true
 enabled = true
 ```
 
+Install the bundled Codex hook helper with the same Python you want Codex to use for the hook runtime:
+
+```bash
+python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
+```
+
 Restart Codex after installation.
 
 ### Repo-level (this project only)
@@ -100,6 +111,31 @@ The path is relative to the repo root, not to the `marketplace.json` file.
 
 You still need the feature gate and plugin entry in `~/.codex/config.toml` (see Home-level above). Codex will discover the marketplace on startup and load the plugin from the repo-local source.
 
+If you want automatic thread capture in repo-level installs too, run:
+
+```bash
+python3 ./.agents/nowledge-mem/scripts/install_hooks.py
+```
+
+## Codex Hook Support
+
+Codex hooks are currently **host-level**, not plugin-local. In practice that means Codex reads `~/.codex/hooks.json`, not hook assets tucked inside the plugin directory.
+
+This package therefore ships a small helper installer:
+
+```bash
+python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
+```
+
+It does four things:
+
+1. Copies the bundled runtime hook into `~/.codex/hooks/nowledge-mem-stop-save.py`
+2. Merges a `Stop` hook entry into `~/.codex/hooks.json`
+3. Ensures `codex_hooks = true` exists under `[features]` in `~/.codex/config.toml`
+4. Pins the installed hook shebang to the current `sys.executable` so Codex runs the hook with the same Python interpreter you used for installation
+
+The installed `Stop` hook reads Codex's `transcript_path`, parses the rollout directly with `nmem_cli.session_import.parse_codex_session_streaming`, and imports the current thread into Mem. It keeps lightweight state in `~/.codex/nowledge_mem_codex_hook_state.json` so repeated `Stop` events only re-import when the transcript actually changed.
+
 ## Verify
 
 Start a new Codex session and ask: "What was I working on?" The agent should load your Working Memory briefing.
@@ -108,13 +144,23 @@ Then test one continuation-style prompt such as "What did we decide before about
 
 If Mem is not running yet, try `$nowledge-mem:status` to check connectivity.
 
+For automatic capture, you can also run a tiny one-shot check:
+
+```bash
+codex exec -C . "Reply with exactly OK and nothing else."
+tail -n 20 ~/.codex/log/nowledge-mem-stop-hook.log
+```
+
+You should see `start event=Stop`, `nmem_exit=0`, and a `created thread=...`, `appended thread=...`, or `skip: ...` outcome entry in the hook log.
+
 ## Update
 
 ```bash
 git clone https://github.com/nowledge-co/community.git /tmp/nowledge-community-update
 cp -R /tmp/nowledge-community-update/nowledge-mem-codex-plugin/. \
   ~/.codex/plugins/cache/local/nowledge-mem/local/
 rm -rf /tmp/nowledge-community-update
+python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
 ```
 
 Restart Codex after updating.
@@ -165,9 +211,12 @@ If you used `nowledge-mem-codex-prompts` before:
 ## Troubleshooting
 
 - **"Command not found: nmem"**: `pip install nmem-cli` or use `uvx --from nmem-cli nmem`. See [Getting Started](https://mem.nowledge.co/docs/installation).
-- **"Cannot connect to server"**: Run `nmem status`. For remote setups, check `~/.nowledge-mem/config.json`. See [Remote Access](https://mem.nowledge.co/docs/remote-access).
+- **"Cannot connect to server"**: Run `nmem status`. For remote setups, check `nmem config client show`. See [Remote Access](https://mem.nowledge.co/docs/remote-access).
 - **Skills not appearing**: Restart Codex after installing. Verify both `[features] plugins = true` and `[plugins."nowledge-mem@local"] enabled = true` are in `~/.codex/config.toml`.
 - **"plugin is not installed"**: Check that the plugin files are at `~/.codex/plugins/cache/local/nowledge-mem/local/` and that `.codex-plugin/plugin.json` exists inside that directory.
+- **Hooks do not fire**: Run `python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py` again, then confirm `~/.codex/hooks.json` exists and `codex_hooks = true` is present under `[features]` in `~/.codex/config.toml`.
+- **Installer says `nmem_cli` is missing**: Run `python3 -m pip install nmem-cli`, then verify `python3 -c "import nmem_cli, nmem_cli.session_import"` succeeds before rerunning `scripts/install_hooks.py`.
+- **No auto-save after a response**: Inspect `~/.codex/log/nowledge-mem-stop-hook.log`. The hook imports directly from Codex's `transcript_path`; if the log shows repeated skips, check that the installed hook starts with the same `#!python` you used for `scripts/install_hooks.py`, and that `python3 -c "import nmem_cli, nmem_cli.session_import"` succeeds in that interpreter.
 - **Only Working Memory runs, but search/distill never show up**: this package is skill-guided, not hook-driven. Merge the package `AGENTS.md` into the project root for stronger repo-specific behavior, and verify you are asking a continuation-style question rather than a fresh isolated one.
 
 ## Links

diff --git a/nowledge-mem-codex-plugin/RELEASING.md b/nowledge-mem-codex-plugin/RELEASING.md
@@ -0,0 +1,46 @@
+# Releasing Nowledge Mem for Codex
+
+This package has two surfaces:
+
+1. the Codex plugin itself under `.codex-plugin/` and `skills/`
+2. the optional host-level hook installer under `scripts/install_hooks.py`
+
+Codex does not currently load hook assets directly from the plugin directory. The installer bridges that gap by copying the bundled runtime hook into `~/.codex/hooks/`, merging `~/.codex/hooks.json`, and enabling `codex_hooks = true` in `~/.codex/config.toml`.
+
+## Preflight
+
+Run from the repository root:
+
+```bash
+node nowledge-mem-codex-plugin/scripts/validate-plugin.mjs
+```
+
+## Release Checklist
+
+- bump `.codex-plugin/plugin.json` version
+- add a top entry to `CHANGELOG.md`
+- bump `integrations.json` -> `integrations[id="codex-cli"].version`
+- update expected version checks in `scripts/validate-plugin.mjs`
+- keep install examples on `cp -r .../. ...` so `.codex-plugin/` is copied
+- keep `scripts/install_hooks.py` idempotent
+- keep the installer enforcing a Python runtime that can `import nmem_cli`
+- keep the copied hook pinned to the installer interpreter (`sys.executable`)
+- keep `hooks/nmem-stop-save.py` focused on direct transcript import via `transcript_path`
+- re-run `node nowledge-mem-codex-plugin/scripts/validate-plugin.mjs`
+
+## Manual Smoke Test
+
+After copying the plugin into `~/.codex/plugins/cache/local/nowledge-mem/local/`:
+
+```bash
+python3 -c "import nmem_cli, nmem_cli.session_import"
+python3 ~/.codex/plugins/cache/local/nowledge-mem/local/scripts/install_hooks.py
+codex exec -C . "Reply with exactly OK and nothing else."
+tail -n 20 ~/.codex/log/nowledge-mem-stop-hook.log
+```
+
+Expect:
+
+- `start event=Stop`
+- `nmem_exit=0`
+- a `created thread=...`, `appended thread=...`, or `skip: ...` outcome line in the hook log