memory-seed 2.3.0__tar.gz → 2.4.0__tar.gz

{memory_seed-2.3.0 → memory_seed-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.3.0
+Version: 2.4.0
 Summary: Portable local memory seed for file-reading AI coding agents
 Author: Jean Nathan Tshibuyi
 License: MIT
@@ -135,7 +135,7 @@ The result is a lightweight memory workflow you can understand, commit, review,
 
 | Agent or client | Support path |
 | --- | --- |
-| Codex | Starts from `AGENTS.md`; can use MCP when the client supports stdio MCP servers. |
+| Codex | Starts from `AGENTS.md`; MCP server auto-registered in `.codex/config.toml` (loads once the project directory is trusted). |
 | Claude Code | Starts from `CLAUDE.md`; MCP server auto-registered via `uvx --from memory-seed`. |
 | Gemini CLI | Starts from `GEMINI.md`. |
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
@@ -365,7 +365,11 @@ For the version distinction (`pip show memory-seed` reports the package version;
 
 Memory Seed also includes a lightweight MCP server that lets agents search local session memory through structured tool calls instead of shelling out to broad compact summaries.
 
-**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's config — `.claude/settings.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.gemini/settings.json` (Gemini CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's MCP config — `.mcp.json` at the project root (Claude Code), `.cursor/mcp.json` (Cursor), `.gemini/settings.json` (Gemini CLI), and `.codex/config.toml` (Codex CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+
+> **Claude Code reads project-scope MCP servers from `.mcp.json`, not `.claude/settings.json`** — the latter is for hooks and permissions only. Versions 2.2.0–2.3.0 wrote the server into `.claude/settings.json`, where Claude Code silently ignored it; `memory-seed update` now writes `.mcp.json` and removes the dead entry. Restart Claude Code and approve the project server, then confirm with `claude mcp list`.
+
+> **Codex loads a project `.codex/config.toml` only for *trusted* directories.** Memory Seed writes the `[mcp_servers.memory-seed]` table there, but Codex ignores it until you trust the project (Codex prompts on first use of a directory, or set trust in Codex settings). After trusting, confirm with `codex mcp list`. `memory-seed doctor` warns if Codex hooks are present without this registration. If you hand-wrote the `memory-seed` entry in a non-standard TOML form (dotted keys, an inline table, or a header with a trailing comment) and it is outdated, `memory-seed update` will not auto-migrate it — `memory-seed doctor` flags it as needing a manual fix instead of silently leaving stale settings in place.
 
 If you are configuring the server manually, run it over stdio:
 
@@ -422,6 +426,14 @@ memory_get_chunk(chunk_id, cwd=".")
 
 The ranking engine stays local and CPU-friendly. MCP search uses a Model2Vec static embedding provider by default with the general-purpose `minishlab/potion-base-8M` model, combines semantic score with lexical and metadata scoring, then applies recency. If Model2Vec or the model cannot load or score a query, the server falls back to lexical, metadata, and recency ranking without failing the request. Use `--no-semantic` on `memory-seed-mcp --stdio` or `semantic_enabled=false` in `memory_search` to force fallback behavior.
 
+### Performance characteristics
+
+`memory_search` is a relevance-and-recall tool, not a faster `grep`. A plain `grep` will out-scan it on raw exact-match throughput; the search wins instead on *semantic recall* over session history (surfacing relevant entries that lack the literal query words) and on *agent-token efficiency* (returning a small ranked set of self-contained chunks with stable `chunk_id`s, so an agent fetches only the one or two full entries worth reading). The two are complementary: use `memory_search` for "what did we decide and why," and `grep` for exact-string scans across the whole repo.
+
+Per-query latency, measured in-process on this repo (81 chunks across the session logs), is roughly **30 ms**, of which about **22 ms is reading and parsing the session `.md` files** — the search re-reads and re-parses every `sessions/*.md` on each call, with no persistent chunk or vector cache — and the embed + cosine + rank step adds only a few ms on top. Cold start adds a one-time cost on the *first ever* call on a machine: the Model2Vec weights download into the local HuggingFace cache (tens of MB); afterwards the static model loads in a few ms. Because the static model has no transformer forward pass, the dominant cost is file I/O, so per-query time grows linearly with total session-log size rather than with model complexity.
+
+When driving the server through an MCP client (Claude Code, Cursor, Gemini), the latency you actually perceive is dominated by one-time startup, not per-query work: spawning `uvx --from memory-seed memory-seed-mcp` resolves and may install the package into an ephemeral environment the first time the server launches in a session. Once the server is up, each `memory_search` is the ~30 ms compute above plus a small JSON-RPC round-trip. At current log sizes there is no need to optimize; should logs grow large enough that the ~22 ms parse cost becomes noticeable, caching parsed chunks and their vectors keyed by file modification time would remove most of the per-query cost.
+
 Session entries should include a YAML metadata block with `entry_id`, `user_initials`, `agent_type`, `project_path`, and `subproject_path`. Session entry headings may include optional minute-level timestamps, such as `## 2026-05-19 20:42 - Durable memory consolidation`. Session filenames stay date-only. Timestamped headings are backward compatible with older untimed headings and are exposed as `entry_datetime` in MCP search results when present.
 
 For human-validatable search behavior, see the fixture-style tests in `tests/test_mcp_server.py`. They assert that specific queries return expected dated session entries first and include enough evidence for manual review.

{memory_seed-2.3.0 → memory_seed-2.4.0}/README.md

@@ -114,7 +114,7 @@ The result is a lightweight memory workflow you can understand, commit, review,
 
 | Agent or client | Support path |
 | --- | --- |
-| Codex | Starts from `AGENTS.md`; can use MCP when the client supports stdio MCP servers. |
+| Codex | Starts from `AGENTS.md`; MCP server auto-registered in `.codex/config.toml` (loads once the project directory is trusted). |
 | Claude Code | Starts from `CLAUDE.md`; MCP server auto-registered via `uvx --from memory-seed`. |
 | Gemini CLI | Starts from `GEMINI.md`. |
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
@@ -344,7 +344,11 @@ For the version distinction (`pip show memory-seed` reports the package version;
 
 Memory Seed also includes a lightweight MCP server that lets agents search local session memory through structured tool calls instead of shelling out to broad compact summaries.
 
-**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's config — `.claude/settings.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.gemini/settings.json` (Gemini CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's MCP config — `.mcp.json` at the project root (Claude Code), `.cursor/mcp.json` (Cursor), `.gemini/settings.json` (Gemini CLI), and `.codex/config.toml` (Codex CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+
+> **Claude Code reads project-scope MCP servers from `.mcp.json`, not `.claude/settings.json`** — the latter is for hooks and permissions only. Versions 2.2.0–2.3.0 wrote the server into `.claude/settings.json`, where Claude Code silently ignored it; `memory-seed update` now writes `.mcp.json` and removes the dead entry. Restart Claude Code and approve the project server, then confirm with `claude mcp list`.
+
+> **Codex loads a project `.codex/config.toml` only for *trusted* directories.** Memory Seed writes the `[mcp_servers.memory-seed]` table there, but Codex ignores it until you trust the project (Codex prompts on first use of a directory, or set trust in Codex settings). After trusting, confirm with `codex mcp list`. `memory-seed doctor` warns if Codex hooks are present without this registration. If you hand-wrote the `memory-seed` entry in a non-standard TOML form (dotted keys, an inline table, or a header with a trailing comment) and it is outdated, `memory-seed update` will not auto-migrate it — `memory-seed doctor` flags it as needing a manual fix instead of silently leaving stale settings in place.
 
 If you are configuring the server manually, run it over stdio:
 
@@ -401,6 +405,14 @@ memory_get_chunk(chunk_id, cwd=".")
 
 The ranking engine stays local and CPU-friendly. MCP search uses a Model2Vec static embedding provider by default with the general-purpose `minishlab/potion-base-8M` model, combines semantic score with lexical and metadata scoring, then applies recency. If Model2Vec or the model cannot load or score a query, the server falls back to lexical, metadata, and recency ranking without failing the request. Use `--no-semantic` on `memory-seed-mcp --stdio` or `semantic_enabled=false` in `memory_search` to force fallback behavior.
 
+### Performance characteristics
+
+`memory_search` is a relevance-and-recall tool, not a faster `grep`. A plain `grep` will out-scan it on raw exact-match throughput; the search wins instead on *semantic recall* over session history (surfacing relevant entries that lack the literal query words) and on *agent-token efficiency* (returning a small ranked set of self-contained chunks with stable `chunk_id`s, so an agent fetches only the one or two full entries worth reading). The two are complementary: use `memory_search` for "what did we decide and why," and `grep` for exact-string scans across the whole repo.
+
+Per-query latency, measured in-process on this repo (81 chunks across the session logs), is roughly **30 ms**, of which about **22 ms is reading and parsing the session `.md` files** — the search re-reads and re-parses every `sessions/*.md` on each call, with no persistent chunk or vector cache — and the embed + cosine + rank step adds only a few ms on top. Cold start adds a one-time cost on the *first ever* call on a machine: the Model2Vec weights download into the local HuggingFace cache (tens of MB); afterwards the static model loads in a few ms. Because the static model has no transformer forward pass, the dominant cost is file I/O, so per-query time grows linearly with total session-log size rather than with model complexity.
+
+When driving the server through an MCP client (Claude Code, Cursor, Gemini), the latency you actually perceive is dominated by one-time startup, not per-query work: spawning `uvx --from memory-seed memory-seed-mcp` resolves and may install the package into an ephemeral environment the first time the server launches in a session. Once the server is up, each `memory_search` is the ~30 ms compute above plus a small JSON-RPC round-trip. At current log sizes there is no need to optimize; should logs grow large enough that the ~22 ms parse cost becomes noticeable, caching parsed chunks and their vectors keyed by file modification time would remove most of the per-query cost.
+
 Session entries should include a YAML metadata block with `entry_id`, `user_initials`, `agent_type`, `project_path`, and `subproject_path`. Session entry headings may include optional minute-level timestamps, such as `## 2026-05-19 20:42 - Durable memory consolidation`. Session filenames stay date-only. Timestamped headings are backward compatible with older untimed headings and are exposed as `entry_datetime` in MCP search results when present.
 
 For human-validatable search behavior, see the fixture-style tests in `tests/test_mcp_server.py`. They assert that specific queries return expected dated session entries first and include enough evidence for manual review.

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/cli.py

@@ -118,6 +118,8 @@ def main(argv: list[str] | None = None) -> int:
             print("Memory Seed bootstrap is complete.")
         else:
             print("Memory Seed bootstrap is incomplete.")
+        for warning in result.warnings:
+            print(f"Warning: {warning}")
         if result.ok:
             return 0
         for missing in result.missing:

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/core.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import re
 import hashlib
+import tomllib
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from pathlib import Path
@@ -10,7 +11,7 @@ from pathlib import Path
 
 PACKAGE_ROOT = Path(__file__).resolve().parent
 SEED_ROOT = PACKAGE_ROOT / "seed"
-VERSION = "2.3"
+VERSION = "2.4"
 MEMORY_DIR_NAME = ".memory-seed"
 LEGACY_MEMORY_DIR_NAME = ".AGENTS"
 BACKUP_IGNORE_ENTRY = ".memory-seed/backups/"
@@ -49,6 +50,7 @@ class DoctorResult:
     missing: list[str] = field(default_factory=list)
     version_mismatches: list[dict[str, str]] = field(default_factory=list)
     bootstrap_missing: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
 
 
 @dataclass
@@ -350,14 +352,19 @@ def _merge_cursor_retrieval_hook(target_root: Path) -> bool:
 
 
 def _merge_claude_mcp(target_root: Path) -> bool:
-    """Upsert the memory-seed-mcp stdio server entry in .claude/settings.json."""
-    settings_path = target_root / ".claude" / "settings.json"
-    expected = {"command": _MCP_SERVER_COMMAND, "args": _MCP_SERVER_ARGS, "type": "stdio"}
+    """Upsert the memory-seed-mcp stdio server entry in the project-root .mcp.json.
+
+    Claude Code discovers project-scope MCP servers from .mcp.json, not from
+    .claude/settings.json (that key is silently ignored by Claude Code).
+    _strip_claude_settings_mcp removes the legacy settings.json entry.
+    """
+    mcp_path = target_root / ".mcp.json"
+    expected = {"command": _MCP_SERVER_COMMAND, "args": _MCP_SERVER_ARGS}
 
     data: dict = {}
-    if settings_path.exists():
+    if mcp_path.exists():
         try:
-            with open(settings_path) as f:
+            with open(mcp_path) as f:
                 data = json.load(f)
         except (json.JSONDecodeError, OSError):
             data = {}
@@ -371,7 +378,44 @@ def _merge_claude_mcp(target_root: Path) -> bool:
 
     data.setdefault("mcpServers", {})[_MCP_SERVER_KEY] = expected
 
-    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    mcp_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(mcp_path, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+    return True
+
+
+def _strip_claude_settings_mcp(target_root: Path) -> bool:
+    """Remove the legacy memory-seed MCP entry from .claude/settings.json.
+
+    Versions 2.2.0-2.3.0 wrote the server into .claude/settings.json > mcpServers,
+    which Claude Code never reads. Now that the server lives in .mcp.json, drop the
+    dead entry so it does not mislead. Only our own entry is removed; a foreign
+    server under the same key is left untouched.
+    """
+    settings_path = target_root / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return False
+    try:
+        with open(settings_path) as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return False
+
+    servers = data.get("mcpServers")
+    if not isinstance(servers, dict) or _MCP_SERVER_KEY not in servers:
+        return False
+
+    existing = servers.get(_MCP_SERVER_KEY, {})
+    is_ours = existing.get("command") in _OWN_MCP_COMMANDS or "memory-seed-mcp" in existing.get("args", [])
+    if not is_ours:
+        return False  # foreign server under the same key; leave it alone
+
+    del servers[_MCP_SERVER_KEY]
+    if not servers:
+        del data["mcpServers"]
+
     with open(settings_path, "w") as f:
         json.dump(data, f, indent=2)
         f.write("\n")
@@ -439,6 +483,120 @@ def _merge_gemini_mcp(target_root: Path) -> bool:
     return True
 
 
+# Header line for our entry in .codex/config.toml. Codex accepts both the bare
+# and quoted single-segment table-key forms; we write the bare form.
+_CODEX_MCP_HEADER_RE = re.compile(
+    r'^\[mcp_servers\.(?:memory-seed|"memory-seed")\]\s*$'
+)
+
+
+def _codex_expected() -> dict:
+    """The MCP table we want present under [mcp_servers.memory-seed]."""
+    return {"command": _MCP_SERVER_COMMAND, "args": _MCP_SERVER_ARGS}
+
+
+def _codex_standard_header_index(lines: list[str]) -> int | None:
+    """Index of the standard ``[mcp_servers.memory-seed]`` header line, or None.
+
+    The in-place stale-update path can only rewrite an entry written with this
+    header form. Shared by _merge_codex_mcp (to decide whether it can migrate)
+    and _codex_mcp_status (to decide stale-fixable vs stale-manual), so the two
+    always agree on what counts as auto-fixable.
+    """
+    return next(
+        (i for i, ln in enumerate(lines) if _CODEX_MCP_HEADER_RE.match(ln)),
+        None,
+    )
+
+
+def _render_codex_mcp_block() -> str:
+    """Render our fixed [mcp_servers.memory-seed] TOML table.
+
+    args is a TOML array of strings, which is JSON-compatible, so json.dumps
+    produces valid TOML for it.
+    """
+    return (
+        f"[mcp_servers.{_MCP_SERVER_KEY}]\n"
+        f'command = "{_MCP_SERVER_COMMAND}"\n'
+        f"args = {json.dumps(_MCP_SERVER_ARGS)}\n"
+    )
+
+
+def _merge_codex_mcp(target_root: Path) -> bool:
+    """Upsert the memory-seed-mcp stdio server in the project .codex/config.toml.
+
+    Codex reads project-scoped MCP servers from .codex/config.toml under
+    [mcp_servers.<name>] (trusted projects only). This is a zero-dependency text
+    upsert: tomllib (stdlib, Python >=3.11) is used only to *inspect* current
+    state; writes are line-based so existing content and comments are preserved.
+
+    Returns True if the file was written, False if already current.
+
+    Known limitation (in-place stale-entry update only): rewriting a present-but-
+    outdated entry while preserving comments relies on finding the standard
+    ``[mcp_servers.memory-seed]`` header line. Detection itself is robust (tomllib
+    parses semantically), but if a user *hand-wrote* the entry in a form that has
+    no such header line — dotted keys (``mcp_servers.memory-seed.command = ...``),
+    an inline subtable under ``[mcp_servers]``, a fully inline
+    ``mcp_servers = { ... }``, or a header with a trailing comment / leading
+    indentation — and the entry is stale, this no-ops (returns False) rather than
+    risk a duplicate-key / invalid-TOML write. The no-op is intentionally not
+    silent: ``doctor`` classifies this case via _codex_mcp_status as a
+    ``stale-manual`` warning telling the user to fix it by hand. Memory Seed only
+    ever writes the standard header form, so this path is only reachable through
+    manual edits.
+    """
+    config_path = target_root / ".codex" / "config.toml"
+    block = _render_codex_mcp_block()
+
+    text = ""
+    parsed: dict = {}
+    if config_path.exists():
+        try:
+            text = config_path.read_text(encoding="utf-8")
+            parsed = tomllib.loads(text)
+        except (tomllib.TOMLDecodeError, OSError):
+            text = ""
+            parsed = {}
+
+    existing = parsed.get("mcp_servers", {}).get(_MCP_SERVER_KEY, {})
+    if existing == _codex_expected():
+        return False
+    if existing:
+        is_ours = (
+            existing.get("command") in _OWN_MCP_COMMANDS
+            or "memory-seed-mcp" in existing.get("args", [])
+        )
+        if not is_ours:
+            return False  # a different server holds this key; don't overwrite
+
+    if not existing:
+        # Append our block, preserving everything above it.
+        new_text = text
+        if new_text and not new_text.endswith("\n"):
+            new_text += "\n"
+        if new_text:
+            new_text += "\n"
+        new_text += block
+    else:
+        # Stale entry: replace just our table's lines (header to next table/EOF).
+        lines = text.splitlines(keepends=True)
+        start = _codex_standard_header_index(lines)
+        if start is None:
+            # No standard header to anchor the rewrite. Don't risk a duplicate
+            # key; leave it for the user. doctor() flags this as stale-manual.
+            return False
+        end = start + 1
+        while end < len(lines) and not lines[end].lstrip().startswith("["):
+            end += 1
+        replacement = block if block.endswith("\n") else block + "\n"
+        new_text = "".join(lines[:start]) + replacement + "".join(lines[end:])
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(new_text, encoding="utf-8")
+    return True
+
+
 def init_project(cwd: str | Path = ".", dry_run: bool = False, force: bool = False) -> InitResult:
     target_root = Path(cwd).resolve()
     planned = [seed_file.destination for seed_file in SEED_FILES]
@@ -484,9 +642,11 @@ def init_project(cwd: str | Path = ".", dry_run: bool = False, force: bool = Fal
         (_merge_codex_retrieval_hook, ".codex/hooks.json"),
         (_merge_cursor_retrieval_hook, ".cursor/hooks.json"),
         (_merge_gemini_retrieval_hook, ".gemini/settings.json"),
-        (_merge_claude_mcp, ".claude/settings.json"),
+        (_merge_claude_mcp, ".mcp.json"),
+        (_strip_claude_settings_mcp, ".claude/settings.json"),
         (_merge_cursor_mcp, ".cursor/mcp.json"),
         (_merge_gemini_mcp, ".gemini/settings.json"),
+        (_merge_codex_mcp, ".codex/config.toml"),
     )
     for merge, destination in hook_merges:
         if merge(target_root) and destination not in created:
@@ -551,9 +711,11 @@ def update_project(cwd: str | Path = ".", dry_run: bool = False) -> InitResult:
         (_merge_codex_retrieval_hook, ".codex/hooks.json"),
         (_merge_cursor_retrieval_hook, ".cursor/hooks.json"),
         (_merge_gemini_retrieval_hook, ".gemini/settings.json"),
-        (_merge_claude_mcp, ".claude/settings.json"),
+        (_merge_claude_mcp, ".mcp.json"),
+        (_strip_claude_settings_mcp, ".claude/settings.json"),
         (_merge_cursor_mcp, ".cursor/mcp.json"),
         (_merge_gemini_mcp, ".gemini/settings.json"),
+        (_merge_codex_mcp, ".codex/config.toml"),
     )
     for merge, destination in hook_merges:
         if merge(target_root) and destination not in created:
@@ -600,6 +762,28 @@ def doctor(cwd: str | Path = ".") -> DoctorResult:
     control_plane_ok = not missing and not version_mismatches
     bootstrap_complete = not bootstrap_missing
 
+    warnings: list[str] = []
+    codex_status = _codex_mcp_status(target_root)
+    if (target_root / ".codex" / "hooks.json").exists() and codex_status == "absent":
+        warnings.append(
+            "Codex hooks are installed but .codex/config.toml has no memory-seed MCP "
+            "entry. Run `memory-seed update`, then trust this directory in Codex so it "
+            "loads the project MCP server (memory_search / memory_get_chunk)."
+        )
+    elif codex_status == "stale-fixable":
+        warnings.append(
+            "Codex .codex/config.toml has an outdated memory-seed MCP entry. Run "
+            "`memory-seed update` to migrate it to `uvx --from memory-seed "
+            "memory-seed-mcp --stdio`."
+        )
+    elif codex_status == "stale-manual":
+        warnings.append(
+            "Codex .codex/config.toml has an outdated memory-seed MCP entry written in "
+            "a non-standard TOML form that `memory-seed update` cannot safely auto-fix. "
+            'Set it by hand to: command = "uvx", args = ["--from", "memory-seed", '
+            '"memory-seed-mcp", "--stdio"].'
+        )
+
     return DoctorResult(
         ok=control_plane_ok and bootstrap_complete,
         control_plane_ok=control_plane_ok,
@@ -607,7 +791,45 @@ def doctor(cwd: str | Path = ".") -> DoctorResult:
         missing=missing,
         version_mismatches=version_mismatches,
         bootstrap_missing=bootstrap_missing,
+        warnings=warnings,
+    )
+
+
+def _codex_mcp_status(target_root: Path) -> str:
+    """Classify our memory-seed entry in .codex/config.toml.
+
+    Returns one of:
+      "absent"        - no entry (or no/unparseable file)
+      "current"       - present and matches the expected uvx command + args
+      "foreign"       - present but owned by a different server
+      "stale-fixable" - ours but outdated, written with a standard header that
+                        `memory-seed update` can auto-migrate
+      "stale-manual"  - ours but outdated, written in a form with no standard
+                        header line, so update no-ops and the user must edit it
+    """
+    config_path = target_root / ".codex" / "config.toml"
+    if not config_path.exists():
+        return "absent"
+    try:
+        text = config_path.read_text(encoding="utf-8")
+        parsed = tomllib.loads(text)
+    except (tomllib.TOMLDecodeError, OSError):
+        return "absent"
+
+    existing = parsed.get("mcp_servers", {}).get(_MCP_SERVER_KEY, {})
+    if not existing:
+        return "absent"
+    if existing == _codex_expected():
+        return "current"
+    is_ours = (
+        existing.get("command") in _OWN_MCP_COMMANDS
+        or "memory-seed-mcp" in existing.get("args", [])
     )
+    if not is_ours:
+        return "foreign"
+    if _codex_standard_header_index(text.splitlines()) is not None:
+        return "stale-fixable"
+    return "stale-manual"
 
 
 def compact_sessions(

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/agent-rules.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - agent-rules
@@ -366,7 +366,7 @@ tags:
 session_date: 2026-05-02
 ---
 
-## 2026-05-02 14:35 - Project setup and workflow update
+## 2026-05-02 14:35 - Switch cache key to content hash
 
 ```yaml
 entry_id: ms-8charhash
@@ -375,14 +375,17 @@ agent_type: codex
 project_path: .
 subproject_path: null
 ```
-
 ### Summary
 
-- Updated the project workflow or implementation area touched today.
+- What changed or what was checked.
 
-### Validation
+### Decision
 
-- Ran the smallest relevant verification.
+- D: State the decision that was made or implemented. (mandatory)
+- R: Explain the decisive reason in 1-3 bullets. (mandatory)
+- A: Alternative considered or rejected, with reason, if it mattered. (optional)
+- F: Files, artifacts, or behaviors changed. (optional)
+- T: Tests or validation outcome. (optional)
 
 ### Follow-up
 
@@ -393,13 +396,13 @@ Keep session filenames date-only, such as `.memory-seed/sessions/2026-05-02.md`.
 
 ### Reason Rules
 
-**DRAFT** is the compact decision-record format used inside session entries. Use it whenever a meaningful decision was made or implemented.
+**DRAFT** is the baseline decision-record format for session entries: default to it whenever a turn produced a decision or a durable change. Route to a simpler or richer shape only as the exception (see Entry Shapes), and never invent a decision just to fill the baseline.
 
 A DRAFT decision record uses compact labels:
 
-- D = Decision — what was chosen
-- R = Reason — the decisive reason, 1–3 bullets; **required**
-- A = Alternatives considered or rejected, with reason (optional unless it shaped the tradeoff)
+- D = Decision (mandatory) — what was chosen
+- R = Reason (mandatory) — the decisive reason, 1–3 bullets
+- A = Alternatives considered or rejected (optional) — with reason, when it shaped the tradeoff
 - F = Files, artifacts, or behaviors changed (optional)
 - T = Tests or validation outcome (optional; may appear inline as `- T:` or as a separate `### Validation` section)
 
@@ -414,11 +417,32 @@ A DRAFT decision record uses compact labels:
 
 ### Entry Shapes
 
-Use the lightest entry shape that preserves future usefulness.
+Default to the **Meaningful decision entry** — a single DRAFT record. Route away from it only when the work does not fit:
+
+- down to the **Small work entry** for routine edits, small fixes, or verification-only work with no real decision (do not invent reason — see Reason Rules);
+- up to the **Multi-decision session entry** when one coherent task produced several decisions.
+
+#### Meaningful decision entry
+
+The baseline shape: use when a turn produced one durable decision.
+
+```markdown
+### Summary
+
+- Summarize the coherent task.
+
+### Decision
+
+- D: State the decision. (mandatory)
+- R: Explain the decisive reason in 1-3 bullets. (mandatory)
+- A: Alternative considered or rejected, with reason, if it mattered. (optional)
+- F: Files, artifacts, or behaviors changed. (optional)
+- T: Tests or validation outcome. (optional)
+```
 
 #### Small work entry
 
-Use for routine edits, small fixes, or verification-only work.
+Simpler alternative — for routine edits, small fixes, or verification-only work with no real decision.
 
 ```markdown
 ### Summary
@@ -434,23 +458,9 @@ Use for routine edits, small fixes, or verification-only work.
 - Only include if there is residual risk or a next action.
 ```
 
-#### Meaningful decision entry
-
-Use when one durable decision was made or implemented.
-
-```markdown
-### Decision
-
-- D: State the decision.
-- R: Explain the decisive reason in 1-3 bullets.
-- A: Alternative considered or rejected, with reason, if it mattered.
-- F: Files, artifacts, or behaviors changed.
-- T: Tests or validation outcome.
-```
-
 #### Multi-decision session entry
 
-Use one entry when several decisions belong to one coherent task, plan, or user goal. Split entries when decisions affect unrelated subsystems, sub-projects, or goals.
+Richer alternative — use one entry when several decisions belong to one coherent task, plan, or user goal. Split entries when decisions affect unrelated subsystems, sub-projects, or goals.
 
 ```markdown
 ### Summary
@@ -461,16 +471,16 @@ Use one entry when several decisions belong to one coherent task, plan, or user
 
 #### D1 - Short decision name
 
-- D: State the choice.
-- R: Explain the decisive reason in 1-3 bullets.
-- A: Alternative considered or rejected, with reason, if it mattered.
-- F: Files, artifacts, or behaviors changed.
-- T: Tests or validation outcome.
+- D: State the choice. (mandatory)
+- R: Explain the decisive reason in 1-3 bullets. (mandatory)
+- A: Alternative considered or rejected, with reason, if it mattered. (optional)
+- F: Files, artifacts, or behaviors changed. (optional)
+- T: Tests or validation outcome. (optional)
 
 #### D2 - Short decision name
 
-- D: State the choice.
-- R: Explain the decisive reason in 1-3 bullets.
+- D: State the choice. (mandatory)
+- R: Explain the decisive reason in 1-3 bullets. (mandatory)
 
 ### Implementation
 

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/hooks/memory-retrieval-check.py

@@ -52,8 +52,13 @@ else:
     )
 
 if agent == "codex":
-    # Codex CLI UserPromptSubmit: systemMessage shown in UI
-    print(json.dumps({"systemMessage": reminder, "continue": True}))
+    # Codex CLI UserPromptSubmit: systemMessage shown in UI.
+    # Project .codex/config.toml MCP servers load only for trusted directories.
+    codex_reminder = (
+        reminder + " (Codex loads the project memory_search MCP server from "
+        ".codex/config.toml only if this directory is trusted.)"
+    )
+    print(json.dumps({"systemMessage": codex_reminder, "continue": True}))
 elif agent == "cursor":
     # Cursor sessionStart: additional_context (snake_case) injects into the
     # conversation's initial system context. beforeSubmitPrompt cannot inject.

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/project-bootstrap.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - project-bootstrap

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/code_search.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/data_architecture.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/index.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill-registry

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/local_compilation.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/memory_consolidation.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/memory_doctor.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/release_publishing.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/.memory-seed/skills/security_triage.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - memory-seed
   - skill

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/AGENTS.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - agent-entry
   - ai-memory

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/CLAUDE.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - agent-entry
   - ai-memory

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed/seed/GEMINI.md

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.3
+memory-system-version: 2.4
 tags:
   - agent-entry
   - ai-memory

{memory_seed-2.3.0 → memory_seed-2.4.0}/memory_seed.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.3.0
+Version: 2.4.0
 Summary: Portable local memory seed for file-reading AI coding agents
 Author: Jean Nathan Tshibuyi
 License: MIT
@@ -135,7 +135,7 @@ The result is a lightweight memory workflow you can understand, commit, review,
 
 | Agent or client | Support path |
 | --- | --- |
-| Codex | Starts from `AGENTS.md`; can use MCP when the client supports stdio MCP servers. |
+| Codex | Starts from `AGENTS.md`; MCP server auto-registered in `.codex/config.toml` (loads once the project directory is trusted). |
 | Claude Code | Starts from `CLAUDE.md`; MCP server auto-registered via `uvx --from memory-seed`. |
 | Gemini CLI | Starts from `GEMINI.md`. |
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
@@ -365,7 +365,11 @@ For the version distinction (`pip show memory-seed` reports the package version;
 
 Memory Seed also includes a lightweight MCP server that lets agents search local session memory through structured tool calls instead of shelling out to broad compact summaries.
 
-**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's config — `.claude/settings.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.gemini/settings.json` (Gemini CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `uvx --from memory-seed memory-seed-mcp --stdio` in each supported vendor's MCP config — `.mcp.json` at the project root (Claude Code), `.cursor/mcp.json` (Cursor), `.gemini/settings.json` (Gemini CLI), and `.codex/config.toml` (Codex CLI). No manual config is needed for projects initialised with Memory Seed. The `uvx --from` form is used so the command works regardless of whether `~/.local/bin` is on the agent's PATH.
+
+> **Claude Code reads project-scope MCP servers from `.mcp.json`, not `.claude/settings.json`** — the latter is for hooks and permissions only. Versions 2.2.0–2.3.0 wrote the server into `.claude/settings.json`, where Claude Code silently ignored it; `memory-seed update` now writes `.mcp.json` and removes the dead entry. Restart Claude Code and approve the project server, then confirm with `claude mcp list`.
+
+> **Codex loads a project `.codex/config.toml` only for *trusted* directories.** Memory Seed writes the `[mcp_servers.memory-seed]` table there, but Codex ignores it until you trust the project (Codex prompts on first use of a directory, or set trust in Codex settings). After trusting, confirm with `codex mcp list`. `memory-seed doctor` warns if Codex hooks are present without this registration. If you hand-wrote the `memory-seed` entry in a non-standard TOML form (dotted keys, an inline table, or a header with a trailing comment) and it is outdated, `memory-seed update` will not auto-migrate it — `memory-seed doctor` flags it as needing a manual fix instead of silently leaving stale settings in place.
 
 If you are configuring the server manually, run it over stdio:
 
@@ -422,6 +426,14 @@ memory_get_chunk(chunk_id, cwd=".")
 
 The ranking engine stays local and CPU-friendly. MCP search uses a Model2Vec static embedding provider by default with the general-purpose `minishlab/potion-base-8M` model, combines semantic score with lexical and metadata scoring, then applies recency. If Model2Vec or the model cannot load or score a query, the server falls back to lexical, metadata, and recency ranking without failing the request. Use `--no-semantic` on `memory-seed-mcp --stdio` or `semantic_enabled=false` in `memory_search` to force fallback behavior.
 
+### Performance characteristics
+
+`memory_search` is a relevance-and-recall tool, not a faster `grep`. A plain `grep` will out-scan it on raw exact-match throughput; the search wins instead on *semantic recall* over session history (surfacing relevant entries that lack the literal query words) and on *agent-token efficiency* (returning a small ranked set of self-contained chunks with stable `chunk_id`s, so an agent fetches only the one or two full entries worth reading). The two are complementary: use `memory_search` for "what did we decide and why," and `grep` for exact-string scans across the whole repo.
+
+Per-query latency, measured in-process on this repo (81 chunks across the session logs), is roughly **30 ms**, of which about **22 ms is reading and parsing the session `.md` files** — the search re-reads and re-parses every `sessions/*.md` on each call, with no persistent chunk or vector cache — and the embed + cosine + rank step adds only a few ms on top. Cold start adds a one-time cost on the *first ever* call on a machine: the Model2Vec weights download into the local HuggingFace cache (tens of MB); afterwards the static model loads in a few ms. Because the static model has no transformer forward pass, the dominant cost is file I/O, so per-query time grows linearly with total session-log size rather than with model complexity.
+
+When driving the server through an MCP client (Claude Code, Cursor, Gemini), the latency you actually perceive is dominated by one-time startup, not per-query work: spawning `uvx --from memory-seed memory-seed-mcp` resolves and may install the package into an ephemeral environment the first time the server launches in a session. Once the server is up, each `memory_search` is the ~30 ms compute above plus a small JSON-RPC round-trip. At current log sizes there is no need to optimize; should logs grow large enough that the ~22 ms parse cost becomes noticeable, caching parsed chunks and their vectors keyed by file modification time would remove most of the per-query cost.
+
 Session entries should include a YAML metadata block with `entry_id`, `user_initials`, `agent_type`, `project_path`, and `subproject_path`. Session entry headings may include optional minute-level timestamps, such as `## 2026-05-19 20:42 - Durable memory consolidation`. Session filenames stay date-only. Timestamped headings are backward compatible with older untimed headings and are exposed as `entry_datetime` in MCP search results when present.
 
 For human-validatable search behavior, see the fixture-style tests in `tests/test_mcp_server.py`. They assert that specific queries return expected dated session entries first and include enough evidence for manual review.

{memory_seed-2.3.0 → memory_seed-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memory-seed"
-version = "2.3.0"
+version = "2.4.0"
 description = "Portable local memory seed for file-reading AI coding agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memory_seed-2.3.0 → memory_seed-2.4.0}/tests/test_memory_seed.py

@@ -23,7 +23,7 @@ class MemorySeedTests(unittest.TestCase):
         return path
 
     def test_version_reads_reusable_control_plane_version(self):
-        self.assertEqual(get_version(), "2.3")
+        self.assertEqual(get_version(), "2.4")
 
     def test_version_at_least_orders_versions_numerically(self):
         from memory_seed.core import _version_at_least
@@ -100,7 +100,7 @@ class MemorySeedTests(unittest.TestCase):
         self.assertTrue(result.backed_up[0].startswith(".memory-seed/backups/"))
         self.assertEqual((cwd / result.backed_up[0]).read_text(encoding="utf-8"), "existing")
         self.assertIn(
-            "memory-system-version: 2.3",
+            f"memory-system-version: {get_version()}",
             (cwd / "AGENTS.md").read_text(encoding="utf-8"),
         )
         self.assertIn(".memory-seed/backups/", (cwd / ".gitignore").read_text(encoding="utf-8"))
@@ -121,7 +121,7 @@ class MemorySeedTests(unittest.TestCase):
         init_project(cwd=cwd)
         gemini = cwd / "GEMINI.md"
         gemini.write_text(
-            gemini.read_text(encoding="utf-8").replace("2.3", "1.1"),
+            gemini.read_text(encoding="utf-8").replace(get_version(), "1.1"),
             encoding="utf-8",
         )
         (cwd / "CLAUDE.md").unlink()
@@ -138,7 +138,7 @@ class MemorySeedTests(unittest.TestCase):
         )
         self.assertEqual(
             result.version_mismatches,
-            [{"file": "GEMINI.md", "expected": "2.3", "actual": "1.1"}],
+            [{"file": "GEMINI.md", "expected": get_version(), "actual": "1.1"}],
         )
 
     def test_doctor_distinguishes_bootstrap_completeness_from_control_plane_health(self):
@@ -221,11 +221,11 @@ class MemorySeedTests(unittest.TestCase):
         self.assertIn("CLAUDE.md", result.created)
         self.assertTrue(any(path.endswith("/AGENTS.md") for path in result.backed_up))
         self.assertIn(
-            "memory-system-version: 2.3",
+            f"memory-system-version: {get_version()}",
             (cwd / "AGENTS.md").read_text(encoding="utf-8"),
         )
         self.assertIn(
-            "memory-system-version: 2.3",
+            f"memory-system-version: {get_version()}",
             (cwd / "CLAUDE.md").read_text(encoding="utf-8"),
         )
         self.assertEqual(
@@ -239,7 +239,7 @@ class MemorySeedTests(unittest.TestCase):
         init_project(cwd=cwd)
         agents = cwd / "AGENTS.md"
         agents.write_text(
-            agents.read_text(encoding="utf-8").replace("2.3", "1.4"),
+            agents.read_text(encoding="utf-8").replace(get_version(), "1.4"),
             encoding="utf-8",
         )
 
@@ -343,14 +343,29 @@ class MemorySeedTests(unittest.TestCase):
         self.assertTrue(
             any(path.endswith("/.memory-seed/agent-rules.md") for path in result.backed_up)
         )
-        self.assertIn("memory-system-version: 2.3", rules.read_text(encoding="utf-8"))
+        self.assertIn(f"memory-system-version: {get_version()}", rules.read_text(encoding="utf-8"))
 
     def test_control_plane_files_report_current_version(self):
         for seed_file in SEED_FILES:
             if not seed_file.source.suffix == ".md":
                 continue
             content = seed_file.source.read_text(encoding="utf-8")
-            self.assertIn("memory-system-version: 2.3", content, seed_file.destination)
+            self.assertIn(f"memory-system-version: {get_version()}", content, seed_file.destination)
+
+    def test_repo_root_control_plane_files_match_version(self):
+        # Guards the recurring release trap: the frontmatter version-bump sed is
+        # scoped to memory_seed/seed/ and .memory-seed/, so it silently skips
+        # this self-hosting repo's own root routing files (AGENTS/CLAUDE/GEMINI.md).
+        # doctor() catches the drift at runtime; this pins it in the suite so a
+        # missed root file fails CI instead of shipping (happened in 2.2.3 / 2.3.0).
+        repo_root = Path(__file__).resolve().parent.parent
+        expected = f"memory-system-version: {get_version()}"
+        for seed_file in SEED_FILES:
+            if not seed_file.source.suffix == ".md":
+                continue
+            live = repo_root / seed_file.destination
+            self.assertTrue(live.exists(), f"missing live control-plane file: {seed_file.destination}")
+            self.assertIn(expected, live.read_text(encoding="utf-8"), seed_file.destination)
 
     def test_seed_files_use_memory_seed_runtime(self):
         destinations = sorted(seed_file.destination for seed_file in SEED_FILES)
@@ -632,9 +647,14 @@ class SessionLogOrderingHookTests(unittest.TestCase):
         import datetime
 
         cwd = self.make_project()
-        today = datetime.date.today().isoformat()
-        (cwd / ".memory-seed" / "sessions" / f"{today}.md").write_text(
-            f"## {today} 01:00 - old entry\n\ntext\n",
+        # Use a timestamp 30 min in the past (> the 15 min staleness threshold)
+        # relative to the actual clock, so the test is not brittle near midnight
+        # where a hardcoded early-morning time would read as a future entry.
+        old = datetime.datetime.now() - datetime.timedelta(minutes=30)
+        day = old.strftime("%Y-%m-%d")
+        stamp = old.strftime("%H:%M")
+        (cwd / ".memory-seed" / "sessions" / f"{day}.md").write_text(
+            f"## {day} {stamp} - old entry\n\ntext\n",
             encoding="utf-8",
         )
         self.assertIn("SESSION LOG REMINDER", self._run(cwd))
@@ -657,10 +677,12 @@ class SessionLogOrderingHookTests(unittest.TestCase):
         import os
 
         cwd = self.make_project()
-        today = datetime.date.today().isoformat()
-        session_file = cwd / ".memory-seed" / "sessions" / f"{today}.md"
+        old = datetime.datetime.now() - datetime.timedelta(minutes=30)
+        day = old.strftime("%Y-%m-%d")
+        stamp = old.strftime("%H:%M")
+        session_file = cwd / ".memory-seed" / "sessions" / f"{day}.md"
         session_file.write_text(
-            f"## {today} 01:00 - old entry\n\ntext\n",
+            f"## {day} {stamp} - old entry\n\ntext\n",
             encoding="utf-8",
         )
         # Touch the file to update mtime to now — simulating what git commit does.
@@ -681,12 +703,17 @@ class McpMergeTests(unittest.TestCase):
         cwd = self.make_project()
         init_project(cwd=cwd)
 
-        data = json.loads((cwd / ".claude" / "settings.json").read_text())
+        # Claude Code reads project-scope MCP servers from .mcp.json, not settings.json.
+        data = json.loads((cwd / ".mcp.json").read_text())
         self.assertIn("memory-seed", data["mcpServers"])
         entry = data["mcpServers"]["memory-seed"]
         self.assertEqual(entry["command"], "uvx")
         self.assertEqual(entry["args"], ["--from", "memory-seed", "memory-seed-mcp", "--stdio"])
-        self.assertEqual(entry["type"], "stdio")
+        self.assertNotIn("type", entry)
+
+        # The dead settings.json mcpServers block must not be created.
+        settings = json.loads((cwd / ".claude" / "settings.json").read_text())
+        self.assertNotIn("mcpServers", settings)
 
     def test_init_installs_mcp_for_cursor(self):
         import json
@@ -718,6 +745,7 @@ class McpMergeTests(unittest.TestCase):
             _merge_claude_mcp,
             _merge_cursor_mcp,
             _merge_gemini_mcp,
+            _merge_codex_mcp,
         )
 
         cwd = self.make_project()
@@ -727,15 +755,17 @@ class McpMergeTests(unittest.TestCase):
         self.assertFalse(_merge_cursor_mcp(cwd))
         self.assertTrue(_merge_gemini_mcp(cwd))
         self.assertFalse(_merge_gemini_mcp(cwd))
+        self.assertTrue(_merge_codex_mcp(cwd))
+        self.assertFalse(_merge_codex_mcp(cwd))
 
     def test_mcp_merge_updates_stale_args(self):
         import json
 
         cwd = self.make_project()
-        settings = cwd / ".claude" / "settings.json"
-        settings.parent.mkdir(parents=True, exist_ok=True)
-        settings.write_text(
-            json.dumps({"mcpServers": {"memory-seed": {"command": "memory-seed-mcp", "args": ["--old"], "type": "stdio"}}}),
+        mcp_path = cwd / ".mcp.json"
+        # Legacy bare-command form (pre-uvx) under our key must migrate forward.
+        mcp_path.write_text(
+            json.dumps({"mcpServers": {"memory-seed": {"command": "memory-seed-mcp", "args": ["--old"]}}}),
             encoding="utf-8",
         )
 
@@ -743,7 +773,7 @@ class McpMergeTests(unittest.TestCase):
         result = _merge_claude_mcp(cwd)
         self.assertTrue(result)
 
-        data = json.loads(settings.read_text())
+        data = json.loads(mcp_path.read_text())
         entry = data["mcpServers"]["memory-seed"]
         self.assertEqual(entry["command"], "uvx")
         self.assertEqual(entry["args"], ["--from", "memory-seed", "memory-seed-mcp", "--stdio"])
@@ -752,9 +782,8 @@ class McpMergeTests(unittest.TestCase):
         import json
 
         cwd = self.make_project()
-        settings = cwd / ".claude" / "settings.json"
-        settings.parent.mkdir(parents=True, exist_ok=True)
-        settings.write_text(
+        mcp_path = cwd / ".mcp.json"
+        mcp_path.write_text(
             json.dumps({"mcpServers": {"other-server": {"command": "other-cmd", "args": []}}}),
             encoding="utf-8",
         )
@@ -762,9 +791,58 @@ class McpMergeTests(unittest.TestCase):
         from memory_seed.core import _merge_claude_mcp
         _merge_claude_mcp(cwd)
 
-        data = json.loads(settings.read_text())
+        data = json.loads(mcp_path.read_text())
         self.assertIn("other-server", data["mcpServers"])
         self.assertEqual(data["mcpServers"]["other-server"]["command"], "other-cmd")
+        self.assertIn("memory-seed", data["mcpServers"])
+
+    def test_strip_removes_legacy_claude_settings_mcp(self):
+        import json
+
+        cwd = self.make_project()
+        settings = cwd / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True, exist_ok=True)
+        # A project seeded by 2.2.0-2.3.0: dead mcpServers block alongside a real hook.
+        settings.write_text(
+            json.dumps(
+                {
+                    "hooks": {"Stop": [{"hooks": [{"type": "command", "command": "keep-me"}]}]},
+                    "mcpServers": {
+                        "memory-seed": {
+                            "command": "uvx",
+                            "args": ["--from", "memory-seed", "memory-seed-mcp", "--stdio"],
+                            "type": "stdio",
+                        }
+                    },
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _strip_claude_settings_mcp
+        self.assertTrue(_strip_claude_settings_mcp(cwd))
+
+        data = json.loads(settings.read_text())
+        self.assertNotIn("mcpServers", data)  # dead block removed, empty parent pruned
+        self.assertEqual(data["hooks"]["Stop"][0]["hooks"][0]["command"], "keep-me")  # rest preserved
+        self.assertFalse(_strip_claude_settings_mcp(cwd))  # idempotent
+
+    def test_strip_preserves_foreign_settings_mcp(self):
+        import json
+
+        cwd = self.make_project()
+        settings = cwd / ".claude" / "settings.json"
+        settings.parent.mkdir(parents=True, exist_ok=True)
+        # A different server squatting our key must not be deleted.
+        settings.write_text(
+            json.dumps({"mcpServers": {"memory-seed": {"command": "some-other-server", "args": []}}}),
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _strip_claude_settings_mcp
+        self.assertFalse(_strip_claude_settings_mcp(cwd))
+        data = json.loads(settings.read_text())
+        self.assertEqual(data["mcpServers"]["memory-seed"]["command"], "some-other-server")
 
     def test_gemini_mcp_merge_preserves_existing_hooks(self):
         import json
@@ -785,6 +863,166 @@ class McpMergeTests(unittest.TestCase):
         self.assertIn("Stop", data["hooks"])
         self.assertEqual(data["hooks"]["Stop"][0]["hooks"][0]["command"], "existing")
 
+    def test_init_installs_mcp_for_codex(self):
+        import tomllib
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)
+
+        # Codex reads project-scope MCP servers from .codex/config.toml.
+        data = tomllib.loads((cwd / ".codex" / "config.toml").read_text(encoding="utf-8"))
+        self.assertIn("memory-seed", data["mcp_servers"])
+        entry = data["mcp_servers"]["memory-seed"]
+        self.assertEqual(entry["command"], "uvx")
+        self.assertEqual(entry["args"], ["--from", "memory-seed", "memory-seed-mcp", "--stdio"])
+
+    def test_codex_mcp_merge_updates_stale_args(self):
+        import tomllib
+
+        cwd = self.make_project()
+        config_path = cwd / ".codex" / "config.toml"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # Legacy bare-command form (pre-uvx) under our key must migrate forward.
+        config_path.write_text(
+            '[mcp_servers.memory-seed]\n'
+            'command = "memory-seed-mcp"\n'
+            'args = ["--old"]\n',
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_codex_mcp
+        self.assertTrue(_merge_codex_mcp(cwd))
+
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        entry = data["mcp_servers"]["memory-seed"]
+        self.assertEqual(entry["command"], "uvx")
+        self.assertEqual(entry["args"], ["--from", "memory-seed", "memory-seed-mcp", "--stdio"])
+
+    def test_codex_mcp_merge_preserves_existing_config(self):
+        import tomllib
+
+        cwd = self.make_project()
+        config_path = cwd / ".codex" / "config.toml"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # Unrelated setting + comment + a foreign MCP server must all survive.
+        config_path.write_text(
+            "# my codex config\n"
+            'model = "gpt-5-codex"\n'
+            "\n"
+            "[mcp_servers.other]\n"
+            'command = "other-cmd"\n'
+            'args = []\n',
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_codex_mcp
+        self.assertTrue(_merge_codex_mcp(cwd))
+
+        text = config_path.read_text(encoding="utf-8")
+        self.assertIn("# my codex config", text)  # comment preserved
+        data = tomllib.loads(text)
+        self.assertEqual(data["model"], "gpt-5-codex")  # unrelated setting preserved
+        self.assertEqual(data["mcp_servers"]["other"]["command"], "other-cmd")  # foreign server kept
+        self.assertIn("memory-seed", data["mcp_servers"])  # ours appended
+
+    def test_codex_mcp_merge_preserves_foreign_server_on_our_key(self):
+        import tomllib
+
+        cwd = self.make_project()
+        config_path = cwd / ".codex" / "config.toml"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # A different server squatting our key must not be overwritten.
+        config_path.write_text(
+            "[mcp_servers.memory-seed]\n"
+            'command = "some-other-server"\n'
+            "args = []\n",
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_codex_mcp
+        self.assertFalse(_merge_codex_mcp(cwd))
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        self.assertEqual(data["mcp_servers"]["memory-seed"]["command"], "some-other-server")
+
+    def test_doctor_warns_when_codex_hooks_without_mcp(self):
+        from memory_seed.core import doctor, _merge_codex_mcp
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)
+        # Simulate a project that has Codex hooks but no MCP registration yet.
+        (cwd / ".codex" / "config.toml").unlink()
+
+        result = doctor(cwd=cwd)
+        self.assertTrue(any("Codex" in w for w in result.warnings))
+        self.assertTrue(result.control_plane_ok)  # warning is non-fatal
+
+        # After re-registering, the warning clears.
+        _merge_codex_mcp(cwd)
+        self.assertFalse(any("Codex" in w for w in doctor(cwd=cwd).warnings))
+
+    def test_doctor_warns_on_stale_manual_codex_mcp(self):
+        from memory_seed.core import doctor, _merge_codex_mcp, _codex_mcp_status
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)  # healthy control plane, so the non-fatal check is meaningful
+        config_path = cwd / ".codex" / "config.toml"
+        # Ours but stale, written as dotted keys -> no standard header to anchor a
+        # rewrite. Update must no-op, and doctor must NOT stay silent about it.
+        config_path.write_text(
+            'mcp_servers.memory-seed.command = "memory-seed-mcp"\n'
+            'mcp_servers.memory-seed.args = ["--old"]\n',
+            encoding="utf-8",
+        )
+
+        self.assertEqual(_codex_mcp_status(cwd), "stale-manual")
+        self.assertFalse(_merge_codex_mcp(cwd))  # safe no-op, not a corruption
+
+        result = doctor(cwd=cwd)
+        self.assertTrue(any("non-standard TOML form" in w for w in result.warnings))
+        self.assertTrue(result.control_plane_ok)  # non-fatal
+
+    def test_doctor_warns_on_stale_fixable_codex_mcp(self):
+        from memory_seed.core import doctor, _merge_codex_mcp, _codex_mcp_status
+
+        cwd = self.make_project()
+        config_path = cwd / ".codex" / "config.toml"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # Ours but stale, standard header form -> update can migrate it.
+        config_path.write_text(
+            "[mcp_servers.memory-seed]\n"
+            'command = "memory-seed-mcp"\n'
+            'args = ["--old"]\n',
+            encoding="utf-8",
+        )
+
+        self.assertEqual(_codex_mcp_status(cwd), "stale-fixable")
+        result = doctor(cwd=cwd)
+        self.assertTrue(any("outdated memory-seed MCP entry" in w for w in result.warnings))
+
+        # update migrates it; warning then clears and status is current.
+        self.assertTrue(_merge_codex_mcp(cwd))
+        self.assertEqual(_codex_mcp_status(cwd), "current")
+        self.assertFalse(any("Codex" in w for w in doctor(cwd=cwd).warnings))
+
+    def test_codex_mcp_status_current_and_foreign_are_quiet(self):
+        from memory_seed.core import doctor, _merge_codex_mcp, _codex_mcp_status
+
+        cwd = self.make_project()
+        # current
+        _merge_codex_mcp(cwd)
+        self.assertEqual(_codex_mcp_status(cwd), "current")
+        self.assertFalse(any("Codex" in w for w in doctor(cwd=cwd).warnings))
+
+        # foreign: a different server squatting our key
+        (cwd / ".codex" / "config.toml").write_text(
+            "[mcp_servers.memory-seed]\n"
+            'command = "some-other-server"\n'
+            "args = []\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(_codex_mcp_status(cwd), "foreign")
+        self.assertFalse(any("Codex" in w for w in doctor(cwd=cwd).warnings))
+
 
 class RetrievalCheckPathTests(unittest.TestCase):
     SCRIPT = Path("memory_seed/seed/.memory-seed/hooks/memory-retrieval-check.py").resolve()