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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.2.3
+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. |
@@ -200,7 +200,7 @@ GEMINI.md
 
 ## Current Version
 
-The current reusable control-plane version is `2.2`.
+The current reusable control-plane version is `2.3`.
 
 Legacy `.AGENTS/` projects remain supported as a fallback during migration.
 
@@ -304,7 +304,7 @@ When `--force` creates backups, Memory Seed adds `.memory-seed/backups/` to the
 
 The `update` command refreshes routing files, reusable runtime procedure files, and generic skill templates by version, sourcing them **from the installed package** rather than from PyPI — upgrade the package first to get newer templates (see [Updating](#updating)). Before replacing stale reusable control-plane files, it backs them up under `.memory-seed/backups/<timestamp>/` and archives their old version under `.memory-seed/archive/<old-version>/` or `.memory-seed/archive/unknown-<timestamp>/` when the old version is missing. Generated local memory files such as `index.md`, `policy.md`, and sessions are preserved.
 
-Use `update --dry-run` to list the reusable control-plane targets without writing files. Current behavior is conservative but broad: dry-run lists bundled seed paths rather than calculating which files are missing or version-mismatched. The real `update` command skips files that already have the current `memory-system-version` and preserves existing `.memory-seed/` runtime files.
+Use `update --dry-run` to list the reusable control-plane targets without writing files. Current behavior is conservative but broad: dry-run lists bundled seed paths rather than calculating which files are missing or version-mismatched. The real `update` command skips files already at the current `memory-system-version` or newer — so a stale installed tool never downgrades a project — and preserves existing `.memory-seed/` runtime files.
 
 The `compact` command summarises recent session activity from the nearest runtime so an agent can identify durable facts to promote into `index.md`, `policy.md`, or skills:
 
@@ -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.2.3 → 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. |
@@ -179,7 +179,7 @@ GEMINI.md
 
 ## Current Version
 
-The current reusable control-plane version is `2.2`.
+The current reusable control-plane version is `2.3`.
 
 Legacy `.AGENTS/` projects remain supported as a fallback during migration.
 
@@ -283,7 +283,7 @@ When `--force` creates backups, Memory Seed adds `.memory-seed/backups/` to the
 
 The `update` command refreshes routing files, reusable runtime procedure files, and generic skill templates by version, sourcing them **from the installed package** rather than from PyPI — upgrade the package first to get newer templates (see [Updating](#updating)). Before replacing stale reusable control-plane files, it backs them up under `.memory-seed/backups/<timestamp>/` and archives their old version under `.memory-seed/archive/<old-version>/` or `.memory-seed/archive/unknown-<timestamp>/` when the old version is missing. Generated local memory files such as `index.md`, `policy.md`, and sessions are preserved.
 
-Use `update --dry-run` to list the reusable control-plane targets without writing files. Current behavior is conservative but broad: dry-run lists bundled seed paths rather than calculating which files are missing or version-mismatched. The real `update` command skips files that already have the current `memory-system-version` and preserves existing `.memory-seed/` runtime files.
+Use `update --dry-run` to list the reusable control-plane targets without writing files. Current behavior is conservative but broad: dry-run lists bundled seed paths rather than calculating which files are missing or version-mismatched. The real `update` command skips files already at the current `memory-system-version` or newer — so a stale installed tool never downgrades a project — and preserves existing `.memory-seed/` runtime files.
 
 The `compact` command summarises recent session activity from the nearest runtime so an agent can identify durable facts to promote into `index.md`, `policy.md`, or skills:
 
@@ -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.2.3 → 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.2.3 → 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.2"
+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:
@@ -517,7 +677,9 @@ def update_project(cwd: str | Path = ".", dry_run: bool = False) -> InitResult:
         if _is_runtime_local_file(seed_file.destination) and destination.exists():
             continue
 
-        if destination.exists() and _read_memory_system_version(destination) == VERSION:
+        if destination.exists() and _version_at_least(
+            _read_memory_system_version(destination), VERSION
+        ):
             continue
 
         if destination.exists():
@@ -549,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:
@@ -598,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,
@@ -605,9 +791,47 @@ 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(
     cwd: str | Path = ".",
     days: int = 7,
@@ -677,6 +901,21 @@ def _read_memory_system_version(path: Path) -> str | None:
     return match.group(1)
 
 
+def _version_tuple(version: str | None) -> tuple[int, ...]:
+    """Dotted version -> int tuple. Missing/unparseable -> (-1,) so it always
+    compares older than any real version and is upgraded forward."""
+    if not version:
+        return (-1,)
+    try:
+        return tuple(int(part) for part in version.strip().split("."))
+    except ValueError:
+        return (-1,)
+
+
+def _version_at_least(actual: str | None, minimum: str) -> bool:
+    return _version_tuple(actual) >= _version_tuple(minimum)
+
+
 def _is_runtime_local_file(destination: str) -> bool:
     reusable_runtime_files = {
         f"{MEMORY_DIR_NAME}/agent-rules.md",

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

@@ -1,5 +1,5 @@
 ---
-memory-system-version: 2.2
+memory-system-version: 2.4
 tags:
   - memory-seed
   - agent-rules
@@ -292,12 +292,12 @@ Deferring or batching session log writes is a discipline failure, not an accepta
 The session file is strictly append-only and must stay in ascending time order. To guarantee this without ever reordering:
 
 - Append every new entry to the **end** of the day's file. Never insert an entry above an existing one.
-- **Use `>>` shell redirection or Python append mode (`open(f, 'a')`) to write entries — do not use an editor replace/insert operation.** Replace/insert requires selecting an anchor line; if a prior edit already added content after that anchor, the new entry lands mid-file instead of at the end. Append mode writes to the physical end of the file unconditionally, with no anchor needed.
+- **Append each entry at the physical end of the file; never insert above an existing entry.** That is the rule; the mechanism is up to your tools. The common failure is anchor-based edit tools — if you target a line you wrote earlier, a later edit may already sit below it, so the new entry lands mid-file. Avoid it by confirming the *actual* last line immediately before appending (for example, read the file's tail); never reuse an anchor from memory. With a POSIX shell or Python, append mode (`>> file`, `open(f, 'a')`) sidesteps anchors entirely — write UTF-8 (some shells, for example PowerShell `>>`, default to other encodings).
 - The entry heading timestamp is the **actual current clock time** at the moment you write it. Read it from the system clock; never reuse a time from your context, memory, or an earlier message, and never backdate it to when the work happened.
 - Because entries are always appended with the current time, file order, write order, and timestamp order are identical. No manual reordering is ever needed or allowed.
 - If you are recording work that completed earlier in the session (you forgot, or you are catching up), still stamp the heading with the current time. If the original work time matters, state it in the entry body — do not move the entry above newer ones and do not rewrite earlier headings.
 
-This is the invariant the "do not rewrite old session entries" rule protects: out-of-order or backdated entries force a human to manually re-sort the log, which is exactly what append-only is meant to prevent. The `>>` / append-mode discipline makes this invariant mechanical rather than reliant on careful anchor selection.
+This is the invariant the "do not rewrite old session entries" rule protects: out-of-order or backdated entries force a human to manually re-sort the log, which is exactly what append-only is meant to prevent. Confirming the real last line before each append — or using append mode where your environment supports it — makes this invariant mechanical rather than reliant on a remembered anchor.
 
 Detailed work logs belong in the nearest active runtime. Add a parent/root summary only when sub-project work changes parent-visible topology, shared design, release behavior, policy inheritance, cross-project dependencies, risks, or active priorities. Do not mirror sub-project logs into root memory.
 
@@ -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