Skip to content

Commit 4400d7a

Browse files
cdeustclaude
andauthored
feat(codex): full profile and the same eleven lifecycle hooks under Codex (#620)
* feat(codex): full profile and the same eleven lifecycle hooks under Codex Cortex shipped two plugin packages with deliberately different exposure: the Claude Code plugin with all hooks and the full tool profile, and a reduced, MCP-only Codex package pinned to `--profile lean`. This reverses that. Codex gets the same product. - `.mcp.json` drops `--profile lean`, so the default full profile is served, exactly like the Claude manifest's server args, which carry no `--profile` flag at all. - New `hooks/hooks.json`, referenced from `.codex-plugin/plugin.json` by path the way `mcpServers` already is, wires all eleven `HOOK_MODULES` names. Each runs `uvx --from "hypermnesia-mcp[postgresql,sqlite]" hypermnesia-mcp-hook <module>`, the console script from #605, so the package still ships only its own directory, never this repository and never `scripts/launcher.py`, which is Claude-only. - Event names are Codex's own (learn.chatgpt.com/docs/hooks, read 2026-09-22). Codex has no `Notification` event, so `compaction_checkpoint` is wired on `PreCompact`, which is where a checkpoint taken before compaction belongs. `SessionEnd` takes Codex's documented 3-second maximum rather than the Claude manifest's 30; `session_lifecycle` survives that ceiling because it spawns its consolidation detached (#610). No other hook sets `timeout`: Codex's own 600s default applies, and this repository has no measurement of the `uvx` hook path that would justify a tighter number. - Matchers carry Codex's native tool names alongside Claude's, so the translations in `host_event.py` (#608) receive the events they translate: `apply_patch` on every Edit/Write-triggered hook, `exec_command` and `shell_command` on the Bash-triggered one. - Each command guards only what can actually fail at that command line: `uvx` on PATH. There is no `CLAUDE_PLUGIN_ROOT` to check (nothing resolves against the plugin root) and no interpreter to locate. The contract test now imports `HOOK_MODULES` instead of restating the eleven names, so a module added to or dropped from the allowlist cannot silently leave the Codex package behind the Claude one. CI's clean-cache host-contract run moves from `--profiles lean` to `--profiles full`, and the stale "exactly ten lean tools / 103.84s" claim is replaced by a re-measurement of the shipped full-profile command: 59 tools in 120.17s from a clean uv cache, 4.24s warm, macOS 26.6.2 arm64, uv 0.11.3, 2026-09-22. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * test(codex): split the hook-manifest contracts into their own file The craftsmanship gate failed in CI: test_codex_plugin_contract.py had grown to 323 lines, over the 300-line cap. I missed it locally because the gate scopes itself to `git diff --name-only --diff-filter=ACMR <base>...HEAD`, which only sees committed work. I ran it while the change was still in the working tree, so the target-file list was empty and the gate had nothing to scan. Running it after committing reproduces the CI failure exactly. This is not a difference between the local and CI comparison points; both resolve the same base ref. The five hook-manifest contracts move to a sibling test_codex_plugin_hooks_contract.py, which asserts hooks/hooks.json, while the original keeps the package identity, the marketplace entries and the MCP server command. No assertion was trimmed to fit the cap. The event-name test splits into one for the event vocabulary and one for the matchers, and gains an assertion that PostCompact stays unwired, so the count goes from 13 to 14. Shared traversal moves into `_every_hook` and `_dispatched` helpers rather than being repeated in each test. 214 and 153 lines, both under the cap. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * fix(ci): never bind a released artifact's surface to this checkout's bounds The mcp-host-config job failed with `ModuleNotFoundError: No module named 'mcp'`. Moving its codex-cli case to `--profiles full` in d39a92b made it call `full_tool_bounds()`, which reads the registries and pulls the MCP SDK that job deliberately never installs (ADR-1077). Installing the SDK there would be the wrong fix, because the call was wrong for a second reason that has nothing to do with dependencies. The bounds come from THIS checkout's registries, while that job's command is `uvx --from "hypermnesia-mcp[postgresql,sqlite]" ...`, which resolves the published release. A PR that adds a tool moves this checkout's bounds while the published wheel still advertises the old count, so the job would have failed on a correct change. That is the same defect ADR-1077 was written about, pointed the other way: a second source of truth waiting to disagree with the first. `--published-surface` marks a case whose command resolves a released artifact. It keeps every other full-profile check (the 'full' profile marker in the initialize instructions, a non-empty tools/list, memory_stats present and callable, the empty-resources and session_recall shims) and drops only the count bound, the one assertion that cannot be true of a foreign artifact. Keeping the call unreachable is also what preserves ADR-1077's SDK-less invariant for that job, so no dependency is added anywhere. Tool-count coverage for codex-cli at the full profile is unaffected. It lives in the two `python scripts/verify_mcp_hosts.py -- hypermnesia-mcp` calls in the test and release-deps jobs (ci.yml:271 and :553), which pass no --clients or --profiles and so exercise all three clients across both profiles against this checkout's installed entry point, in jobs that do install the SDK. ADR-1077's guard was too weak: it checked only that the script stays IMPORTABLE without the SDK, which never protected the call. The new `test_the_sdk_less_job_never_binds_a_release_to_this_checkouts_bounds` reads the job out of ci.yml and fails if a full-profile case there omits the flag. Verified to fail when the flag is removed. ADR-1077 carries a dated revision recording all of this, so the "verifies lean profiles only" claim is no longer left contradicting the code; the generated mirror is regenerated from the canonical wiki page. Reproduced both directions locally against a stub stdio server with `mcp` blocked by the same meta_path blocker tests_py/test_tool_surface.py uses: without the flag, `ImportError: mcp`, exit 1; with it, `PASS codex-cli/full: initialize + discovery + memory_stats (59 tools)`, exit 0. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs(codex): the shipped prose describes the plugin that ships An independent review found three docs still describing the reduced Codex design this PR removed. All three verified at the PR head before fixing. plugins/hypermnesia-mcp-codex/SECURITY.md was the serious one: it told a reviewer the package runs "the read-only or idempotent-write `lean` tool profile" and "installs no hooks", both false. It now discloses what the package can actually do: the full profile advertises and accepts `forget` and the wiki_purge/wiki_migrate class, and eleven hooks run, of which decision_gate reads patched files' contents and can block a tool call, post_tool_capture persists tool output by default, session_lifecycle spawns a detached subprocess, and post_commit_reindex may reindex the repository. It also says how to opt back down: --profile lean, or drop the hooks reference. README.md said "a 10-tool lean surface" 37 lines after the table in the same file already said "all 57 tools" for the same plugin. docs/shared-host-memory.md said the bundled plugin keeps a ten-tool lean profile and cannot author an ADR. It now separates the bundled plugin (full, can author) from a --profile lean process (cannot), which is what the test it cites actually exercises. The neighbouring claim that the hosts lack equivalent lifecycle hooks was stale the same way and is corrected. Two new guards, both mutation-checked by reintroducing each original sentence and confirming a failure: - test_codex_prose_does_not_contradict_the_shipped_manifests reads the manifests and fails if the prose claims no hooks while plugin.json declares them, or a ten-tool surface while .mcp.json passes no --profile. Conditioned on the manifests, so reverting the design relaxes the guard rather than stranding it. It bans the drifted wordings, not the words, so the docs can still explain --profile lean as an opt-in. - test_codex_security_doc_discloses_what_the_package_can_do fails if the security doc stops naming the destructive tools or the two hooks with effects beyond writing to the memory store. scripts/check_doc_claims.py could not have caught any of this, measured rather than assumed. Every one of its five patterns matches a NUMBER beside a keyword (TOOL_CLAIM wants "N memory|standalone|MCP tools"), and none matched any of the three sentences, README.md included, which that gate already scans. "installs no hooks" has no number at all; "10-tool" and "ten-tool" never take the keyword form. Separately, four of the five relevant files are not in SCANNED_FILES. Widening that tuple alone would have caught nothing and bought false confidence, so the gate is left alone and the gap is reported. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * fix(codex): restore the checks the last two rounds removed or never set Five findings from an independent review of the final state. All five verified against the PR head first; all five fixes mutation-checked. 1. --published-surface took the only tool-surface check with it. Dropping the checkout-derived bounds was right; leaving nothing but a memory_stats presence test was not, since a packaging regression that dropped whole registries from the published wheel would still have passed. A released full profile is a superset of that release's own lean profile, so LEAN_TOOL_NAMES is a floor that holds across versions. It needs no MCP SDK, so the ADR-1077 invariant is untouched. Confirmed against the real published wheel: PASS codex-cli/full (59 tools, 12.14s). 2. The denylist lost in the file split is back. The package's own SECURITY.md promises no skills, apps or agents and no installer, which is testable: test_codex_plugin_ships_an_mcp_server_and_hooks_and_nothing_else asserts it, with `hooks` moved from the denied set to the required one. 3. Ten of eleven hooks had no timeout and took Codex's 600-second default, against Claude's 5 to 30 on the same hooks. A latency budget is part of behaviour, so this PR's parity claim did not hold. Codex documents a special default and maximum only for SessionEnd and Interrupt, so every other budget is settable and is now the Claude manifest's own number. auto_recall on UserPromptSubmit is the sharp case: 5 seconds, where 600 would have let a stalled uvx resolve hold up every prompt for ten minutes. decision_gate and no_deps_gate still declare none, because the Claude manifest declares none for them either and both hosts default a command hook to 600 seconds; declaring nothing on both sides is the parity case. A cold cache will exceed these budgets, which costs one skipped enrichment: both hosts cancel a timed-out hook and discard its output, and Claude Code's reference is explicit that a timed-out PreToolUse hook "doesn't block the tool call". The test now derives every expected value from the Claude manifest instead of restating literals. 4. The ci.yml regression guard checked for --published-surface anywhere in the mcp-host-config job body, so a second --profiles full case added later would have been covered by the first one's flag. It now scopes to each invocation. Mutation-checked with exactly that shape: a second unflagged full-profile case, which the old check passed and the new one catches. 5. --published-surface was a blanket flag threaded into every case of a run. Rather than document the currently-safe scope, mcp_host_cli.check_selection refuses it outside a single client and single profile, following the --command-includes-profile precedent in the same file. It cannot widen silently now. scripts/verify_mcp_hosts.py had one line of headroom under the 300-line cap, so the CLI surface moves to scripts/mcp_host_cli.py: defining flags is a separate concern from driving the contract, nothing outside imported those four helpers, and full_tool_bounds() stays put so ADR-1077 and tests_py/test_tool_surface.py need no churn. 235 and 108 lines. Mutation results, each reverted after: CAUGHT 1 published full surface missing the lean names CAUGHT 2 plugin.json regrows an `agents` key CAUGHT 3 auto_recall loses its 5s budget CAUGHT 3b SessionEnd set to 30s (over the Codex maximum) CAUGHT 4 second --profiles full case, unflagged CAUGHT 5 --published-surface across two clients Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * fix(codex): a guard that matched nothing, and a hook count in three docs Round-4 review findings. Both confirmed ones reproduced before fixing. 1. The prose-drift guard's own regex was broken. `\b` after "tool" never matches the plural, because the `s` in "tools" is a word character, so LEAN_SURFACE_CLAIM matched only the singular forms: MISSED 'The lean profile is exactly these ten tools:' MISSED '10 tools' MISSED 'ten tools' MATCH 'a 10-tool lean surface' MATCH 'its ten-tool `lean` profile' The missed line is the exact historical wording the guard was written to catch. `tools?\b` now covers both, and a new test asserts every wording on both patterns, plus three benign lines this package really ships so the guard cannot become a tripwire on its own documentation. 2. README claimed "9 lifecycle hooks" in the banner and "nine" in prose while this PR put "eleven" in the same file, and docs/ROADMAP.md said 9 too. HOOK_MODULES has had 11 entries since #605, so this predates the PR but the PR made it a self-contradiction. Fixed in all three places, written as digits so the doc-claim gate can see them, and the gate gains a `lifecycle hooks` family counted from the allowlist rather than declared. That is the general fix: it covers both files and any future one, instead of pinning the banner line alone. 3. `--published-surface` paired with `--profiles lean` validated, and would have compared a released artifact against this checkout's LEAN_TOOL_NAMES: the same checkout-versus-release coupling ADR-1077's revision removed for full. check_selection now refuses the pairing. 5. Disclosed the per-edit cost, which neither docs/codex-plugin.md nor the package's SECURITY.md mentioned. One edit fires up to five `uvx` hook processes (two before the call, three after); a patch touching several files still costs five, since host_dispatch runs the module once per derived event inside one process. Measured 2026-09-22 (macOS 26.6.2 arm64, uv 0.11.3, warm cache, published 4.23.1): 0.18s to 0.21s per process in steady state, first invocation of a module 1.3s to 5.1s while its caches fill, roughly 0.4s of the total in the blocking path. 6, 7, 8. Shared helpers: tests_py/scripts/_codex_plugin_support.py now holds the paths, the JSON reader and one `hook_index` scan, following the `_craftsmanship_support.py` precedent in the same package. That removes the three independent module-name scans (`_claude_timeouts`, `_dispatched` and an inline `_matcher_for`) and the duplicated `_json`. The duplicated `PLUGIN_ROOT / "scripts"` assertion is now made once, where it belongs. test_cross_host_manifests.py keeps its own `_json`: different signature, different module, and folding it in would widen this change for nothing. The new pattern test pushed test_codex_plugin_contract.py to 318 lines, so the prose guards move to test_codex_plugin_docs_contract.py. They assert the docs; what stays asserts the manifests. 225 and 115 lines. 4 was already reported as a disclosed trade-off and is unchanged: the published floor proves a superset of the lean names, not an upper bound. I found no way to tighten it that does not reintroduce the coupling finding 3 just closed. While verifying, the "57 tools" drift I had been carrying since round 1 turned out not to be drift: `standalone_tool_names()` is 57 and UPSTREAM_TOOL_NAMES adds 3, so the live 59 I measured sits inside the 57..60 bounds. The docs are right and the item is withdrawn. Mutation results, each reverted after: CAUGHT 1 SECURITY.md regains 'these ten tools:' (plural) CAUGHT 2 README banner back to '9 lifecycle hooks' CAUGHT 2b ROADMAP back to '9 lifecycle hooks' CAUGHT 3 --published-surface with --profiles lean Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * fix(ci): read the hook allowlist as text, never import it The Lint job died on `ModuleNotFoundError: No module named 'mcp_server'` and gated out the whole pipeline. My fault, from the previous commit. I verified the diagnosis against the code rather than accepting it. The Lint job's only setup is `pip install --no-deps --require-hashes -r requirements/lint.txt`, and that file resolves to ruff alone: no editable install, no PYTHONPATH. `python scripts/check_doc_claims.py` puts `scripts/` on sys.path rather than the repository root, so `mcp_server` is not importable there at all. The ADR-1077 precedent I cited does not transfer, and that was the error. `full_tool_bounds()` is reached only from one case in `mcp-host-config`, which the previous commit made sure never calls it without the SDK. `canonical_hook_count()` is called unconditionally from `collect_failures`, so a late import buys nothing: the call always happens. Every sibling in doc_claim_sources.py takes `read_fn` and parses text; `canonical_hook_count` was the only one importing a module. It now reads `mcp_server/hooks/entry.py` as source and evaluates the HOOK_MODULES frozenset literal with `ast` (stdlib, no dependency). The source of truth is still the allowlist, and there is still no second copy of the number. Reproduced the job's constraint rather than trusting the dev environment: a fresh venv with only requirements/lint.txt installed, run with no PYTHONPATH from the repository root. That environment confirms `mcp_server` is unimportable as the gate sees it, and all three Lint steps now pass in it: ruff format --check . -> 3404 files already formatted, exit 0 ruff check . -> All checks passed!, exit 0 python scripts/check_doc_claims.py -> doc claims OK, exit 0 The repro is faithful, not merely green: putting the importing version back into that same venv reproduces the CI failure exactly, `ModuleNotFoundError: No module named 'mcp_server'`, exit 1. New LintJobEnvironmentTests pins it. One test blocks `mcp_server` with the same meta_path blocker tests_py/test_tool_surface.py uses for the SDK and runs `collect_failures` with `scripts/` on sys.path; the other checks the text parse still equals `len(HOOK_MODULES)`, so reading text did not trade correctness for portability. Mutation-checked: restoring the importing version fails the first test. The unit fixture gains its own `mcp_server/hooks/entry.py` stand-in with a four-name allowlist, the way it already carries CATALOGUE, PINNED_TEST and BIBLIOGRAPHY for the other families. Four rather than the live eleven so that adding a hook to Cortex does not edit this file. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * fix(codex): guard the claims that were only asserted in prose Round-6 review findings, all verified before fixing. A tautological assertion is replaced. `HOOKS_PATH.is_relative_to(PLUGIN_ROOT)` could never fail: the support module defines HOOKS_PATH AS `PLUGIN_ROOT / "hooks/hooks.json"`, so it tested a constant, not the ignore file it sat beside. The test now walks every file the Codex package ships and asserts each is covered by a directory entry in .mcpbignore, and separately that no `!` line re-includes one. Mutation-checked with a re-include, which the three neighbouring membership assertions all pass and only this catches. The doc-claim gate now scans the Codex package's own README and SECURITY.md and the two repository docs that describe it. Probed first: no claim pattern matches anything in those four files today, so this adds coverage without changing a verdict. The hook-count family only ever saw digits, and most claims were spelled out. Every claim family in this gate is digit-only by convention, so the seven remaining "eleven" occurrences become "11" rather than teaching one family to read number words. The gate went from seeing 2 hook-count claims to 10, across 6 files. `session_lifecycle` does NOT reliably survive Codex's 3-second SessionEnd ceiling, and the document said it did while also saying a cold cache could lose the run. Measured, warm uv cache, the manifest's own command against a SessionEnd event: 3.46s, 1.03s, 0.97s. The first run exceeds the maximum. Detaching consolidation (#610) makes the remaining work small enough to attempt, not small enough to guarantee. Recorded as a named limitation with the numbers rather than reconciled in prose: it costs the session record of the first session after an install or upgrade, and prewarming does not help because the measurement is already warm. It needs a decision, not an edit, and the report to the owner says so. decision_gate and no_deps_gate keep no timeout, and the reasoning is now written down instead of implied. A timeout on a gate fails OPEN: Claude Code's reference says a timed-out PreToolUse hook "doesn't block the tool call ... so don't count on a stalled hook to act as a gate." A tight ceiling would trade a rare long wait for silently ungated edits. Warm, these cost 0.16s to 0.26s; the long wait is only the first cold resolve. The same exposure exists on Claude Code today, so it belongs to both manifests, and narrowing it on one host would break the parity a test now enforces. preemptive_context's `Read` matcher has no Codex equivalent, and that is a host limitation rather than a wiring gap. Codex's tool table has no read tool: shell commands and unified exec both match as `Bash`. Reading a file there is a shell command, and preemptive_context keys on `tool_input.file_path`, which a shell event does not carry, so matching `Bash` would spawn a uvx process per shell command for a guaranteed no-op. Documented as a one-sided gap; the edit-triggered half still fires through apply_patch. The duplicated uvx guard string across all 11 entries is left as acknowledged debt with a note naming the test that keeps the copies honest. Generating both manifests from one template is the real fix and is out of scope here. Mutation results, each reverted after: CAUGHT .mcpbignore re-includes the hooks directory CAUGHT .mcpbignore loses the plugin directory entry CAUGHT codex README gains '9 lifecycle hooks' CAUGHT docs/codex-plugin.md gains '9 lifecycle hooks' Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH * docs: qualify Codex hook behavior claims (#620) Signed-off-by: cdeust <[email protected]> * docs: clarify remaining Codex parity claims (#620) Signed-off-by: cdeust <[email protected]> --------- Signed-off-by: cdeust <[email protected]> Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent 95f3bec commit 4400d7a

23 files changed

Lines changed: 1206 additions & 187 deletions

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -365,8 +365,9 @@ jobs:
365365
UV_TOOL_DIR="$RUNNER_TEMP/cortex-codex-cold-uv-tools" \
366366
PYTHONPATH="$GITHUB_WORKSPACE" \
367367
python scripts/verify_mcp_hosts.py \
368-
--timeout "$plugin_timeout" --clients codex-cli --profiles lean \
368+
--timeout "$plugin_timeout" --clients codex-cli --profiles full \
369369
--command-includes-profile \
370+
--published-surface \
370371
--allow-bootstrap-network \
371372
--storage-selection auto \
372373
-- "${plugin_command[@]}"

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,32 @@ adheres to [Semantic Versioning](https://semver.org/).
66

77
## [Unreleased]
88

9+
### Changed
10+
11+
- **Codex exposes the full tool profile and registers all eleven hook modules.**
12+
Host payloads and timeout limits still affect behavior; see
13+
[Codex hook limitations](docs/codex-plugin.md). The Codex
14+
plugin now serves the complete tool profile (`.mcp.json` drops
15+
`--profile lean`, matching the Claude manifest's server args, which carry
16+
no `--profile` flag) and installs the same eleven lifecycle hooks through
17+
a new `plugins/hypermnesia-mcp-codex/hooks/hooks.json`, referenced from
18+
`.codex-plugin/plugin.json` by path the way `mcpServers` already is. Each
19+
hook runs `uvx --from "hypermnesia-mcp[postgresql,sqlite]"
20+
hypermnesia-mcp-hook <module>` — the console script added in #605 — so the
21+
package still ships only its own directory, never this repository and never
22+
`scripts/launcher.py`. Event names are Codex's own: `compaction_checkpoint`
23+
moves to `PreCompact` because Codex has no `Notification` event, and
24+
`SessionEnd` takes Codex's documented 3-second maximum instead of the
25+
Claude manifest's 30. Every other hook carries the Claude manifest's own
26+
timeout, because a latency budget is part of behaviour: unset, Codex would
27+
let a stalled `UserPromptSubmit` hook hold a prompt for its 600-second
28+
default where Claude Code caps the same hook at 5 seconds. The two
29+
`PreToolUse` gates declare none on either host, which is the parity case.
30+
Matchers carry Codex's native tool names
31+
(`apply_patch`, `exec_command`, `shell_command`) alongside Claude's, so the
32+
translations in `host_event.py` (#608) actually receive the events they
33+
translate. This reverses the earlier "Codex is additive, reduced" design.
34+
935
## [4.23.1] - 2026-09-22
1036

1137
### Fixed

‎README.md‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ files. We hold that intent to the
4040
publish **no CO₂ or energy figure**, because we have not measured one.
4141
[What we do and do not claim ↓](#green-software-engineering)
4242

43-
> **36 neuroscience mechanisms · 57 memory tools · 9 lifecycle hooks · a self-curating per-project wiki — all local, all open-source, MIT.**
43+
> **36 neuroscience mechanisms · 57 memory tools · 11 lifecycle hooks · a self-curating per-project wiki — all local, all open-source, MIT.**
4444
4545
## Install
4646

@@ -204,8 +204,8 @@ prior analysis, the Redis decision, and the TTL lesson when their content matche
204204
**Three weeks later.** The sessions can consolidate into a pattern about authentication and
205205
TTL-based caches; some details may fade while the principle remains useful.
206206

207-
In Claude Code that is automatic: nine lifecycle hooks inject context at session start, recall
208-
per prompt, capture as you work, checkpoint before compaction, and run a per-project wiki that
207+
In Claude Code and Codex alike that is automatic: 11 lifecycle hooks inject context at session
208+
start, recall per prompt, capture as you work, checkpoint before compaction, and run a wiki that
209209
curates itself. In any other stdio MCP host you call the same 57 tools yourself, or 60 when
210210
the optional `ai-architect-mcp-codebase` and `ai-architect-mcp-spec` integrations are present.
211211

@@ -275,31 +275,31 @@ banners, auto-recall, auto-capture, checkpoints and every memory tool work on bo
275275
## Every other MCP host
276276

277277
The server is host-agnostic. Any host that can launch a stdio process gets the full tool
278-
surface on the default SQLite store. What is not portable are the nine lifecycle hooks, which
279-
are Claude Code plugin machinery; the server never imports or requires them at startup. The
280-
Codex plugin deliberately starts the server with `--profile lean`: the full tool surface is the
281-
largest fixed token cost a session pays before the user types anything (ADR-0693, issue #177),
282-
and the plugin keeps that cost to ten tools; the direct registration below gives Codex the full
283-
surface.
278+
surface on the default SQLite store. What is not portable are the lifecycle hooks — but they
279+
are no longer Claude-only: the Codex plugin registers the same 11 hook modules through the
280+
`hypermnesia-mcp-hook` console script. Host payloads and timeout limits affect their behavior:
281+
native Codex subagent starts receive no briefing, and session-end recording can exceed its
282+
timeout. See [Codex hook limitations](docs/codex-plugin.md). A direct `codex mcp add`
283+
registration gets the tool surface only; the hooks come with the plugin.
284284

285285
| Capability | Claude Code plugin | Codex plugin (`hypermnesia-mcp-codex`) | Codex `codex mcp add`, Gemini CLI, Cursor, Windsurf, VS Code, Agents SDK | ChatGPT web |
286286
|---|---|---|---|---|
287-
| Tool surface | all 57 tools | the 10-tool `lean` profile: `remember`, `recall`, `unified_search`, `recall_hierarchical`, `consolidate`, `memory_stats`, `check_setup`, `wiki_read`, `wiki_list`, `query_methodology` | all 57 tools (`full` is the default profile) | ❌ no remote HTTPS endpoint is shipped |
287+
| Tool surface | all 57 tools | all 57 tools (no `--profile` flag, same as Claude Code) | all 57 tools (`full` is the default profile) | ❌ no remote HTTPS endpoint is shipped |
288288
| SQLite default store / PostgreSQL opt-in | ✅ | ✅ | ✅ | ❌ would need a remote deployment and a per-user storage and auth model |
289289
| One store for Claude Code and Codex | ✅ writes the selection to `~/.claude/methodology/backend.json` | ✅ reads that selection at startup (#600, since 4.23.0) | ✅ same rule for any direct startup sharing the configuration root | ❌ |
290-
| Predictions and calibration (`predict`, `resolve_prediction`, `calibration`) | ✅ | ❌ not in `lean`; use the direct registration | ✅ | ❌ |
291-
| Wiki writes, ADRs, triggers, rules, codebase ingestion | ✅ | ❌ not in `lean` | ✅ | ❌ |
292-
| Auto-capture of significant tool output | ✅ PostToolUse hook | ❌ store explicitly with `remember` | ❌ same | ❌ |
293-
| Session-start context injection | ✅ SessionStart hook | ❌ call `recall` yourself | ❌ same | ❌ |
294-
| Per-prompt auto-recall | ✅ | ❌ | ❌ | ❌ |
295-
| Compaction checkpoints | ✅ | ❌ | ❌ | ❌ |
296-
| Autonomous wiki cycle | ✅ | ❌ `consolidate` by hand; `curate_wiki` needs the full profile | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
290+
| Predictions and calibration (`predict`, `resolve_prediction`, `calibration`) | ✅ | ✅ | ✅ | ❌ |
291+
| Wiki writes, ADRs, triggers, rules, codebase ingestion | ✅ | ✅ | ✅ | ❌ |
292+
| Auto-capture of significant tool output | ✅ PostToolUse hook | ✅ PostToolUse hook | ❌ store explicitly with `remember` | ❌ |
293+
| Session-start context injection | ✅ SessionStart hook | ✅ SessionStart hook | ❌ call `recall` yourself | ❌ |
294+
| Per-prompt auto-recall | ✅ | ✅ UserPromptSubmit hook | ❌ | ❌ |
295+
| Compaction checkpoints | ✅ `Notification: compacted` | ✅ `PreCompact` (Codex has no `Notification` event) | ❌ | ❌ |
296+
| Autonomous wiki cycle | ✅ | ✅ | ❌ run `consolidate` / `curate_wiki` manually | ❌ |
297297
| Cognitive profiling (`query_methodology`) | ✅ | ⚠️ profiles are mined from Claude Code session logs under `~/.claude/`; without them the profile is empty | ⚠️ same | ❌ |
298298
| Worktree directory | `.claude/worktrees/<name>/`, the location `docs/agent-guidance.md` names | `.Codex/worktrees/<name>/`, where Codex puts its own; ignored at the repository root since #601 | n/a | n/a |
299299

300-
On Claude Code memory is ambient: hooks capture and inject automatically. On every other host
301-
memory is tool-driven: the agent stores and retrieves when instructed, and nothing happens
302-
between prompts.
300+
The Claude Code and Codex plugins use hooks to capture and inject memory automatically,
301+
subject to the host limitations above. With a direct MCP registration without plugin hooks,
302+
memory is tool-driven: the agent explicitly calls tools to store and retrieve it.
303303

304304
The launch command on every host is the PyPI package. The `[sqlite]` extra enables
305305
sqlite-vec vector search; without it the store still works, with vector search disabled.
@@ -314,7 +314,8 @@ uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp
314314
gemini extensions install https://github.com/cdeust/Cortex
315315
```
316316

317-
**Codex and ChatGPT desktop** have a native plugin with a 10-tool lean surface. It reads the
317+
**Codex and ChatGPT desktop** have a native plugin with the full tool surface and the same
318+
11 lifecycle hooks the Claude Code plugin installs. It reads the
318319
same saved backend selection as the Claude Code launcher (`~/.claude/methodology/backend.json`),
319320
so both hosts write to one store (since 4.23.0); explicit `CORTEX_MEMORY_STORE_BACKEND`, `CORTEX_BACKEND` or a database URL
320321
still wins. Pre-install

‎docs/ROADMAP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ deliberately absent; the ordering is the promise.
1010
## Where the project is today
1111

1212
v4.17.1, released 2026-08-02. 57 standalone MCP tools (60 with the optional
13-
upstream integrations), 9 lifecycle hooks, 36 neuroscience-grounded mechanisms
13+
upstream integrations), 11 lifecycle hooks, 36 neuroscience-grounded mechanisms
1414
against a 97-reference bibliography, running on a local SQLite store by
1515
default or PostgreSQL + pgvector when configured. The OpenSSF Best Practices
1616
**passing** badge was earned 2026-07-27.

‎docs/adr/ADR-1077-the-advertised-tool-count-is-read-from-the-registries.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,17 @@ A literal that is right for a while, then wrong, and only caught when it drifts
2626

2727
`mcp_server/tool_surface.py` reads the surface from the registry modules themselves: `standalone_tool_names()` is the union of their `SCHEMAS` maps minus the three gated names, and `UPSTREAM_TOOL_NAMES` holds those three. It imports registries only, never the server, so a caller pays no MCP startup for a count.
2828

29-
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them, through a thin `full_tool_bounds()` that imports it late. The late import is load-bearing: reading the registries pulls the MCP SDK, and the `mcp-host-config` CI job installs the three host CLIs with no Python dependencies and verifies lean profiles only. A module-scope import broke that job, and a test now imports the script with `mcp` blocked to keep it importable without the SDK. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
29+
`scripts/verify_mcp_hosts.py` derives its bounds from that module rather than stating them, through a thin `full_tool_bounds()` that imports it late. The late import is load-bearing: reading the registries pulls the MCP SDK, and the `mcp-host-config` CI job installs the three host CLIs with no Python dependencies. A module-scope import broke that job, and a test now imports the script with `mcp` blocked to keep it importable without the SDK. The remaining copies are prose for humans, and the doc-claim gate already cross-checks them against the pinned test name.
30+
31+
### Revision 2026-09-22: importable is not the same as unreached
32+
33+
The paragraph above said the job "verifies lean profiles only", and the guard built for it only checked that the script stays *importable* without the SDK. Both were too weak. When the Codex plugin stopped shipping a lean profile (PR #620), that job's codex-cli case moved to `--profiles full`, which *calls* `full_tool_bounds()`, and the job failed on `ModuleNotFoundError: No module named 'mcp'` again. Importability never protected the call.
34+
35+
There is a second, independent reason that call did not belong there, and it is the same defect this ADR was written about, pointed the other way. The bounds are derived from **this checkout's** registries, while that job's command is `uvx --from "hypermnesia-mcp[postgresql,sqlite]" ...`, which resolves the **published release**. A PR that adds a tool moves this checkout's bounds while the published wheel keeps advertising the old count, so the job would have failed on a correct change. Binding an artifact's surface to a different tree's registries is a second source of truth waiting to disagree with the first.
36+
37+
`--published-surface` therefore marks a case whose command resolves a released artifact. It keeps every other full-profile check (the `'full' profile` marker in the initialize instructions, a non-empty `tools/list`, `memory_stats` present and callable, the empty-resources and `session_recall` shims) and drops only the count bound, which is the one assertion that cannot be true of a foreign artifact. Tool-count coverage for codex-cli at the full profile is unaffected: it lives in the two `python scripts/verify_mcp_hosts.py -- hypermnesia-mcp` calls in the `test` and `release-deps` jobs, which pass no `--clients` or `--profiles` and so exercise all three clients across both profiles against this checkout's own installed entry point, in jobs that do install the SDK.
38+
39+
The guard is now `test_the_sdk_less_job_never_binds_a_release_to_this_checkouts_bounds`, which reads the job out of `ci.yml` and fails if a full-profile case there omits the flag.
3040

3141
## Consequences
3242

0 commit comments

Comments
 (0)