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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.3.0
+Version: 2.5.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.5.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.5.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.5.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.5"
 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
@@ -63,6 +65,13 @@ SEED_FILES = [
     SeedFile(SEED_ROOT / "AGENTS.md", "AGENTS.md"),
     SeedFile(SEED_ROOT / "CLAUDE.md", "CLAUDE.md"),
     SeedFile(SEED_ROOT / "GEMINI.md", "GEMINI.md"),
+    SeedFile(SEED_ROOT / ".agents" / "README.md", ".agents/README.md"),
+    SeedFile(SEED_ROOT / ".agents" / "developer.md", ".agents/developer.md"),
+    SeedFile(SEED_ROOT / ".agents" / "content-creator.md", ".agents/content-creator.md"),
+    SeedFile(SEED_ROOT / ".agents" / "researcher.md", ".agents/researcher.md"),
+    SeedFile(SEED_ROOT / ".agents" / "sales-rep.md", ".agents/sales-rep.md"),
+    SeedFile(SEED_ROOT / ".agents" / "solo-founder.md", ".agents/solo-founder.md"),
+    SeedFile(SEED_ROOT / ".agents" / "copywriter.md", ".agents/copywriter.md"),
     SeedFile(
         SEED_ROOT / MEMORY_DIR_NAME / "agent-rules.md",
         ".memory-seed/agent-rules.md",
@@ -76,6 +85,10 @@ SEED_FILES = [
         SEED_ROOT / MEMORY_DIR_NAME / "skills" / "security_triage.md",
         ".memory-seed/skills/security_triage.md",
     ),
+    SeedFile(
+        SEED_ROOT / MEMORY_DIR_NAME / "skills" / "copywriter-conversion.md",
+        ".memory-seed/skills/copywriter-conversion.md",
+    ),
     SeedFile(
         SEED_ROOT / MEMORY_DIR_NAME / "skills" / "code_search.md",
         ".memory-seed/skills/code_search.md",
@@ -350,14 +363,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 +389,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 +494,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 +653,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 +722,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:
@@ -581,6 +754,8 @@ def doctor(cwd: str | Path = ".") -> DoctorResult:
 
         if not candidate.suffix == ".md":
             continue
+        if seed_file.destination.startswith(".agents/"):
+            continue  # agent personas are project-local; not version-tracked control plane
         actual = _read_memory_system_version(candidate)
         if actual != VERSION:
             version_mismatches.append(
@@ -600,6 +775,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,9 +804,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,
@@ -702,7 +937,7 @@ def _is_runtime_local_file(destination: str) -> bool:
     return (
         destination.startswith(f"{MEMORY_DIR_NAME}/")
         and destination not in reusable_runtime_files
-    )
+    ) or destination.startswith(".agents/")
 
 
 def _archive_replaced_control_plane_file(

{memory_seed-2.3.0 → memory_seed-2.5.0}/memory_seed/mcp_server.py

@@ -241,6 +241,7 @@ def _ranked_to_dict(result: RankedMemoryChunk) -> dict[str, Any]:
         "entry_id": chunk.entry_id,
         "user_initials": chunk.user_initials,
         "agent_type": chunk.agent_type,
+        "agent_name": chunk.agent_name,
         "project_path": chunk.project_path,
         "subproject_path": chunk.subproject_path,
         "entry_title": chunk.entry_title,
@@ -270,6 +271,7 @@ def _chunk_to_dict(chunk: MemoryChunk) -> dict[str, Any]:
         "entry_id": chunk.entry_id,
         "user_initials": chunk.user_initials,
         "agent_type": chunk.agent_type,
+        "agent_name": chunk.agent_name,
         "project_path": chunk.project_path,
         "subproject_path": chunk.subproject_path,
         "entry_title": chunk.entry_title,

memory_seed-2.5.0/memory_seed/seed/.agents/README.md

@@ -0,0 +1,118 @@
+# .agents/ — Agent Persona Library
+
+This folder ships with every `memory-seed init` and provides vendor-neutral persona templates that any LLM can inhabit. Each persona defines an identity, operating rules, memory protocol, and session discipline for a specific role.
+
+---
+
+## Available Personas
+
+| File | Agent Name | Role |
+|------|-----------|------|
+| `developer.md` | `developer` | Software Engineer / Staff IC |
+| `content-creator.md` | `content-creator` | Content Strategist / Writer |
+| `researcher.md` | `researcher` | Research Engine / Knowledge Architect |
+| `sales-rep.md` | `sales-rep` | Sales Operator / Pipeline Manager |
+| `solo-founder.md` | `solo-founder` | Co-founder / Generalist |
+
+---
+
+## Activation and Deactivation
+
+Personas are controlled by `.agents/_registry.yaml`. Set `status: active` to enable a persona; `status: inactive` to disable it.
+
+Bootstrap generates `_registry.yaml` when you first run `memory-seed init` in a project. Edit it at any time to switch personas.
+
+**Example registry:**
+```yaml
+agents:
+  developer:
+    file: developer.md
+    role: Software Engineer / Staff IC
+    status: active
+  solo-founder:
+    file: solo-founder.md
+    role: Co-founder / Generalist
+    status: inactive
+```
+
+When an agent starts a session, it reads `_registry.yaml`, loads all `status: active` persona files, and applies those rules alongside `agent-rules.md` and `policy.md`.
+
+**Multiple active personas:** Allowed. The persona most relevant to the current task governs. When ambiguous, the first active entry in `_registry.yaml` is the default.
+
+---
+
+## Adding a New Persona
+
+**Quick path (existing persona as starting point):**
+
+1. Copy any existing persona file: `cp developer.md data-scientist.md`
+2. Save it to `.agents/data-scientist.md`
+3. At the next session start, the agent detects the unregistered file and runs the onboarding flow automatically:
+   - Adds or corrects YAML frontmatter (`agent_name`, `memory_protocol`, `vendor_neutral`, `tags`)
+   - Rewrites the Memory Protocol section to use `.memory-seed/` paths (if it references a separate `memory/` folder)
+   - Adds `## Project Adaptations` and `## Skills` sections if missing
+   - Runs personalization: asks for entity name (or generates one), confirms user name, asks for business name
+   - Routes relevant skills from `.memory-seed/skills/` and offers to generate missing ones
+   - Adds the persona to `_registry.yaml` with `status: active`
+
+**Starting from scratch:**
+
+Write a plain Markdown file describing the role. The onboarding flow will handle all formatting. The minimum content needed:
+```markdown
+# [Role] Operating System
+
+## I. Identity
+
+You are [describe the role and its purpose].
+
+## III. Operating Rules
+
+[Domain-specific rules and standards for this role]
+```
+
+The agent fills in the Memory Protocol, Skills, Project Adaptations, and Persona Evolution sections during onboarding.
+
+The `.agents/` folder is project-local: `memory-seed update` never overwrites it once created, so custom personas and their evolved content survive upgrades.
+
+---
+
+## Persona Evolution (Lessons Learned)
+
+Personas grow smarter as the project progresses. At session end, the active agent may propose changes to the persona file based on patterns observed during the session. The flow:
+
+1. Agent drafts proposed change(s): what to add/change/remove and why (evidence from this session).
+2. Agent presents proposals to the user for approval. **No edits happen until the user approves.**
+3. On approval, the agent:
+   - Applies the edit to the relevant section of the persona file.
+   - Appends an entry to the `## Project Adaptations` section at the bottom of the persona file.
+   - Appends a session log entry (`agent_name: <slug>`, D/R/F + "Signed: user approved YYYY-MM-DD HH:MM").
+
+**Project Adaptations entry format:**
+```markdown
+### YYYY-MM-DD — Short description of what changed
+Session: ms-<entry_id> | Approved by: <user_initials>
+Section changed: [section name]
+Rationale: [one-line reason from session]
+```
+
+This creates three layers of traceability: the session log decision record, the in-file changelog, and the git diff.
+
+If no lessons emerged, skip the proposal — no empty prompts.
+
+---
+
+## Memory Protocol
+
+Each persona's Memory Protocol section points to the memory-seed runtime:
+- `.memory-seed/index.md` — active state and current focus
+- `.memory-seed/sessions/` (last 2 files) — recent decisions and open threads
+- `.memory-seed/policy.md` — behavioral constraints and preferences
+- `memory_search` MCP — historical context beyond the last 2 sessions
+
+Persona session entries use `agent_name: <slug>` in the entry YAML block (see `agent-rules.md` for the full format). This lets `memory_search` filter entries by persona.
+
+---
+
+## Vendor Neutrality
+
+Persona files use `.memory-seed/` paths and plain Markdown conventions — no LLM-specific APIs, directives, or syntax. Any file-reading AI coding agent (Claude, Gemini, Codex, GPT-4, or a future model) can read and apply these files.