afx-team · ch-liuzhide · Jun 30, 2026 · Jun 29, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "hebb-mind",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Neuroscience-inspired long-term memory for Claude Code — auto-captures and recalls cross-session context",
   "author": "afx-team",
   "homepage": "https://github.com/afx-team/hebb-mind",

diff --git a/.codex/hooks.json b/.codex/hooks.json
@@ -6,8 +6,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "hebb claude-code recall",
-            "timeout": 30
+            "command": "hebb codex recall",
+            "timeout": 30,
+            "statusMessage": "Recalling Hebb Mind context"
           }
         ]
       }
@@ -17,8 +18,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "hebb claude-code prompt",
-            "timeout": 10
+            "command": "hebb codex prompt",
+            "timeout": 10,
+            "statusMessage": "Searching Hebb Mind"
           }
         ]
       }
@@ -28,8 +30,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "hebb claude-code stop",
-            "timeout": 30
+            "command": "hebb codex stop",
+            "timeout": 30,
+            "statusMessage": "Saving turn to Hebb Mind"
           }
         ]
       }

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.2.1"
+  ".": "0.3.0"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
      3. Merge to main — publish.yml ships to PyPI on the pyproject.toml change
         and tags the release. -->
 
+## [0.3.0] - 2026-06-29
+
+### Added
+
+- **Codex-native memory integration**: `hebb codex install` now installs native
+  Codex MCP plus lifecycle hooks. Project scope is the default and writes
+  `.codex/config.toml` and `.codex/hooks.json`; `--scope user` registers MCP
+  through `codex mcp add` and writes user-level hooks.
+- **Codex lifecycle hooks**: `SessionStart` and `UserPromptSubmit` recall
+  relevant memories, while `Stop` captures the completed Codex turn into Hebb
+  Mind with Codex-specific metadata.
+- **Codex transcript parser**: rollout JSONL parsing now extracts the latest
+  user/assistant turn, tool calls, MCP calls, timestamps, and turn index for
+  reliable Stop-hook ingestion.
+
+### Documentation
+
+- Refreshed Codex public docs, quick starts, MCP integration notes, and CLI
+  reference in English and Chinese to document project-level install, user-level
+  install, hook trust flow, and the `--scope` behavior.
+
 ## [0.2.1] - 2026-06-24
 
 ### Added

diff --git a/README.md b/README.md
@@ -105,7 +105,7 @@ pipx install hebb-mind                 # recommended (isolated CLI install)
 pipx install 'hebb-mind[pg]'           # + PostgreSQL/pgvector
 pipx upgrade hebb-mind                 # upgrade later
 hebb claude-code install --scope user  # Claude Code: hooks-based recall + turn capture
-hebb codex install --scope user        # Codex: MCP memory tools
+hebb codex install                     # Codex: project MCP + automatic memory hooks
 ```
 
 Docker, one-line install, and source build: [Installation Guide](https://afx-team.github.io/hebb-mind/guide/installation.html).

diff --git a/README_ZH.md b/README_ZH.md
@@ -105,7 +105,7 @@ pipx install hebb-mind                 # 推荐方式（隔离的 CLI 安装）
 pipx install 'hebb-mind[pg]'           # 启用 PostgreSQL/pgvector
 pipx upgrade hebb-mind                 # 后续升级
 hebb claude-code install --scope user  # Claude Code：基于 hooks 的召回 + 回合写入
-hebb codex install --scope user        # Codex：MCP 记忆工具
+hebb codex install                     # Codex：项目级 MCP + 自动记忆 hooks
 ```
 
 Docker、一键脚本、源码安装详见 [安装指南](https://afx-team.github.io/hebb-mind/zh/guide/installation.html)。

diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ name = "hebb-mind"
 # with src/hebb/__init__.py, .release-please-manifest.json, and
 # .claude-plugin/plugin.json. publish.yml ships to PyPI when this version
 # changes on main.
-version = "0.2.1"
+version = "0.3.0"
 description = "Hebb Mind — neuroscience-inspired long-term memory framework for AI agents (neurons that fire together, wire together)"
 readme = "README.md"
 license = {text = "MIT"}

diff --git a/repo_pages/api/cli.md b/repo_pages/api/cli.md
@@ -189,14 +189,24 @@ The hooks are recall-and-capture, not consolidation. `recall` and `prompt` **rea
 
 ## hebb codex
 
-Codex CLI integration via `codex mcp add`/`remove`. Codex registers MCP servers globally — there is no per-project scope, so only `--scope user` (global) is supported.
+Native Codex integration with MCP plus `SessionStart`, `UserPromptSubmit`,
+and `Stop` hooks. Project scope writes `.codex/config.toml` and
+`.codex/hooks.json`; user scope uses `codex mcp add` and
+`~/.codex/hooks.json`.
 
 ```bash
-hebb codex install   [--scope user]   # default: user (global-only)
-hebb codex uninstall
+hebb codex install   [--scope project|user]   # default: project; current project
+hebb codex uninstall [--scope project|user]   # default: project; current project
+hebb codex recall    # SessionStart hook entry point
+hebb codex prompt    # UserPromptSubmit hook entry point
+hebb codex stop      # Stop hook entry point
 ```
 
-Verify with `codex mcp list`.
+`--scope user` means user-level configuration for the current OS user and
+applies to all of that user's Codex projects. Omitting it is equivalent to
+`--scope project`, which writes only the current directory's `.codex/`.
+
+Verify MCP with `codex mcp list` and review hooks with `/hooks`.
 
 ## hebb config
 

diff --git a/repo_pages/guide/codex.md b/repo_pages/guide/codex.md
@@ -1,73 +1,122 @@
 ---
-description: "Give the Codex CLI persistent AI agent memory via MCP: install the hebb-mcp server so Codex can write, search, and consolidate memories across coding sessions."
+description: "Give Codex automatic persistent memory with native lifecycle hooks and MCP: project-scoped recall, turn capture, search, write, and consolidation."
 ---
 
 # Codex Integration
 
-Hebb Mind integrates with Codex through MCP tools. Codex can call `write_memory`, `search_memory`, `consolidate`, and `ingest_conversation` when useful.
+Hebb Mind integrates with Codex through native lifecycle hooks and MCP.
+`SessionStart` recalls cross-session context, `UserPromptSubmit` searches for
+prompt-relevant memories, and `Stop` captures the completed turn. MCP also
+exposes `write_memory`, `search_memory`, `consolidate`, and
+`ingest_conversation` for explicit operations.
 
 ## Prerequisites
 
-- **Python >= 3.10** and `pipx` (or a venv) — see [Installation](./installation.md).
-- The **`codex` CLI** must be on your `PATH`. `hebb codex install` registers the MCP server by running `codex mcp add`; without the `codex` CLI it cannot complete.
+- The **`codex` CLI** must be on `PATH`.
+- Install and initialize Hebb Mind.
+- Install the background service because hooks and MCP forward requests to
+  the local REST API.
 
-## Install
+## Project installation
+
+Run this from the repository you want to equip with memory:
 
 ```bash
-pipx install hebb-mind         # use `pipx upgrade hebb-mind` to update later
-hebb setup                     # initialize + download the embedding model
-hebb service install           # register + start the background service (MCP tools talk to it)
-hebb codex install             # register Hebb Mind as a Codex MCP server (global-only)
+pipx install hebb-mind
+hebb setup
+hebb service install
+hebb codex install
 ```
 
-No `pipx`? See [Installation → Install pipx](./installation.md#install-pipx-if-you-don-t-have-it).
-
-`hebb service install` is required: the MCP tools forward to the local Hebb Mind service on `127.0.0.1:8321`. Skip it and Codex's first memory tool call fails with an opaque connection error.
+Project scope is the default. The installer writes:
 
-Verify:
+- `.codex/config.toml` — the project-scoped `hebb` MCP server
+- `.codex/hooks.json` — automatic recall and turn-capture hooks
 
-```bash
-codex mcp list
-```
+Existing unrelated Codex config and hooks are preserved. Re-running the
+installer replaces only Hebb-managed entries.
 
-## Use it in Codex
+`--scope` controls where the integration is written:
 
-Once installed, just talk to Codex naturally — it decides when to call the memory tools. Concrete prompts that exercise each tool:
+| Command | Applies to | Writes |
+|---|---|---|
+| `hebb codex install` | Current project | `.codex/config.toml` and `.codex/hooks.json` |
+| `hebb codex install --scope project` | Current project | Same as above |
+| `hebb codex install --scope user` | Every Codex project for the current OS user | User-level Codex MCP config and `~/.codex/hooks.json` |
 
-- **Store**: "Remember that I deploy with `make release` and prefer pnpm over npm."
-- **Recall**: "What do you remember about how I deploy this project?"
-- **Organize**: "Consolidate what you've learned about my preferences."
+## Activate and verify
 
-To nudge Codex toward durable memory, add project guidance (see [Capability Boundary](#capability-boundary) below).
+Codex loads project configuration only for trusted projects, and command
+hooks require explicit review. Start a new Codex thread in the project, then:
 
-## Native Codex Command
+```text
+/hooks
+```
 
-If you prefer to manage MCP servers directly, pass the **absolute path** to `hebb-mcp` (from `which hebb-mcp`) so it resolves regardless of how Codex is launched:
+Review and trust the three Hebb hooks. Verify MCP from a terminal:
 
 ```bash
-codex mcp add hebb -- "$(which hebb-mcp)"
+codex mcp list
 ```
 
-For a remote Hebb Mind service, point `HEBB_URL` at the remote host:
+## User-wide installation
+
+To make Hebb Mind available in every project:
 
 ```bash
-codex mcp add hebb --env HEBB_URL=http://192.168.1.100:8321 -- "$(which hebb-mcp)"
+hebb codex install --scope user
 ```
 
-## Capability Boundary
+This registers MCP through `codex mcp add` and writes hooks to
+`~/.codex/hooks.json`. User hooks also require review through `/hooks`.
 
-Codex uses MCP tools for explicit memory operations. Claude Code has an additional hooks layer that recalls memories on session lifecycle events and captures each completed turn to the working-memory inbox. Codex does not currently provide that hooks flow through this integration, so with Codex you (or your project guidance) drive the memory tools explicitly.
+## Lifecycle behavior
 
-For best results, add project guidance that tells Codex when durable memory should be used:
+| Event | Hebb command | Behavior |
+|---|---|---|
+| `SessionStart` | `hebb codex recall` | Adds recent cross-session context and preferences |
+| `UserPromptSubmit` | `hebb codex prompt` | Adds memories relevant to the current prompt |
+| `Stop` | `hebb codex stop` | Parses the Codex rollout and writes the completed turn |
 
-```text
-Use the Hebb Mind MCP server when durable user preferences, project facts, or cross-session decisions should be remembered or recalled.
+Hook failures degrade to a no-op so a stopped Hebb service does not block
+Codex. The next hook or MCP launch asks the installed OS service manager to
+start Hebb Mind.
+
+## MCP tools
+
+You can still request explicit memory operations:
+
+- “Remember that this project uses pnpm, not npm.”
+- “Search long-term memory for the authentication decision.”
+- “Consolidate the memories collected today.”
+
+Project guidance in `AGENTS.md` can define which decisions should be stored,
+but normal cross-session recall and turn capture no longer depend on the
+model deciding to call an MCP tool.
+
+## Remote Hebb Mind service
+
+For a remote service, user-level MCP can still be registered directly:
+
+```bash
+codex mcp add hebb \
+  --env HEBB_URL=http://192.168.1.100:8321 \
+  -- "$(which hebb-mcp)"
 ```
 
+If lifecycle hooks should use the same remote service, export `HEBB_URL` in
+the environment that launches Codex.
+
 ## Uninstall
 
-Codex stores MCP servers globally, so uninstall is global-only (there is no per-project scope):
+Remove the current project's integration:
 
 ```bash
 hebb codex uninstall
 ```
+
+Remove the user-wide integration:
+
+```bash
+hebb codex uninstall --scope user
+```
diff --git a/repo_pages/guide/installation.md b/repo_pages/guide/installation.md
@@ -111,5 +111,5 @@ See [Storage Backends](../advanced/storage-backends.md) for details.
 
 - [Configuration](./configuration.md) — full config reference
 - [Claude Code](./claude-code.md) — automatic cross-session memory for Claude Code
-- [Codex](./codex.md) — MCP memory tools for Codex
+- [Codex](./codex.md) — automatic memory hooks and MCP tools for Codex
 - [MCP Integration](./mcp-integration.md) — use Hebb Mind as MCP tools in any client
diff --git a/repo_pages/guide/mcp-integration.md b/repo_pages/guide/mcp-integration.md
@@ -78,7 +78,7 @@ If the service runs on a non-default address, set the URL explicitly:
 Recommended:
 
 ```bash
-hebb codex install   # Codex registers MCP servers globally (global-only)
+hebb codex install   # project MCP + lifecycle hooks (default)
 codex mcp list
 ```
 

diff --git a/repo_pages/index.md b/repo_pages/index.md
@@ -37,7 +37,7 @@ features:
     details: Single-page app for memory CRUD, search, partitions, and graph view. Lives at http://localhost:8321/ — no separate deploy.
   - icon: 🔌
     title: REST + MCP + Claude Code hooks
-    details: Three-line install gives Claude Code cross-session memory; hebb codex install adds the same as MCP tools. REST docs at /docs.
+    details: Three-line install gives Claude Code or Codex automatic cross-session recall and turn capture, backed by MCP memory tools. REST docs at /docs.
 ---
 
 <div class="hippo-home">

diff --git a/repo_pages/public/llms.txt b/repo_pages/public/llms.txt
@@ -18,7 +18,7 @@ Headline benchmark results (reproducible via the `eval/` harness): LongMemEval r
 - [Configuration](https://afx-team.github.io/hebb-mind/guide/configuration.html): One `hebb.json` controls everything — CLI config commands, workspace resolution, embedding model, and LLM/consolidation setup.
 - [Switch the Embedding Model](https://afx-team.github.io/hebb-mind/guide/switch-embedding-model.html): Use local sentence-transformers or a LiteLLM API embedding provider, handle dimension changes, and re-embed with resume.
 - [Claude Code Integration](https://afx-team.github.io/hebb-mind/guide/claude-code.html): Give Claude Code cross-session memory via the MCP server plus session hooks for automatic recall, turn capture, and consolidation.
-- [Codex Integration](https://afx-team.github.io/hebb-mind/guide/codex.html): Give the Codex CLI persistent memory over MCP via the `hebb-mcp` server.
+- [Codex Integration](https://afx-team.github.io/hebb-mind/guide/codex.html): Give Codex automatic cross-session recall and turn capture with native hooks, plus explicit memory tools over MCP.
 - [MCP Integration](https://afx-team.github.io/hebb-mind/guide/mcp-integration.html): Connect Claude Code, Codex, Cursor, and Claude Desktop to long-term memory over MCP — write, recall, and consolidate.
 - [Web Console](https://afx-team.github.io/hebb-mind/guide/web-console.html): Browser UI bundled with the service (port 8321) — memory CRUD, hybrid search, partitions, a knowledge-graph view, and live config.
 - [Migration from mem0 / Letta / Zep](https://afx-team.github.io/hebb-mind/guide/migration.html): Concept and API mapping, before/after code, data import, and an honest gap analysis.

diff --git a/repo_pages/quick-start.md b/repo_pages/quick-start.md
@@ -155,7 +155,7 @@ For Docker, see [Storage Backends](./advanced/storage-backends.md#docker-deploym
 
 ```bash
 hebb claude-code install --scope user   # Claude Code: hooks-based auto memory
-hebb codex install                       # Codex: MCP memory tools (global-only)
+hebb codex install                       # Codex: project MCP + automatic memory hooks
 codex mcp list                           # verify
 ```
 

diff --git a/repo_pages/zh/api/cli.md b/repo_pages/zh/api/cli.md
@@ -187,14 +187,22 @@ hebb claude-code stop        # Stop 钩子：记录本轮对话
 
 ## hebb codex
 
-Codex CLI 集成（封装 `codex mcp add/remove`）。Codex 只在全局注册 MCP server，没有按项目区分的 scope，因此这两个命令均为全局生效。
+Codex 原生 MCP 与生命周期 hooks 集成。项目 scope 写入
+`.codex/config.toml` 和 `.codex/hooks.json`；用户 scope 通过
+`codex mcp add` 注册 MCP，并写入 `~/.codex/hooks.json`。
 
 ```bash
-hebb codex install     # 仅支持全局（--scope user，默认且唯一取值）
-hebb codex uninstall   # 全局卸载
+hebb codex install   [--scope project|user]   # 默认 project；当前项目
+hebb codex uninstall [--scope project|user]   # 默认 project；当前项目
+hebb codex recall    # SessionStart hook 入口
+hebb codex prompt    # UserPromptSubmit hook 入口
+hebb codex stop      # Stop hook 入口
 ```
 
-可通过 `codex mcp list` 验证。
+`--scope user` 表示当前 OS 用户级配置，对该用户的所有 Codex 项目生效；
+不加时等价于 `--scope project`，只写当前目录的 `.codex/`。
+
+通过 `codex mcp list` 验证 MCP，并在 Codex 中通过 `/hooks` 审核 hooks。
 
 ## hebb config