memory-seed 2.1.2__tar.gz → 2.2.0__tar.gz

{memory_seed-2.1.2 → memory_seed-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.1.2
+Version: 2.2.0
 Summary: Portable local memory seed for file-reading AI coding agents
 Author: Jean Nathan Tshibuyi
 License: MIT
@@ -30,6 +30,12 @@ Memory Seed is a portable local memory system for AI coding agents. It plants a
 
 It is built first for solo developers who move between Codex, Claude Code, Gemini CLI, and other file-reading agents. Teams can also use it to standardize local agent memory across repositories without introducing a database or hosted memory service.
 
+## Demo
+
+https://github.com/user-attachments/assets/b1c64d9e-4a67-4bc2-a030-d8ba7f17ccfe
+
+[▶ Watch the 30-second demo](https://github.com/jnl-tshi/memory-seed/releases/download/v2.1.3/memory-seed-demo.mp4) if the player above does not load.
+
 ## Quickstart
 
 From the root of a project where you want local agent memory:
@@ -135,6 +141,24 @@ The result is a lightweight memory workflow you can understand, commit, review,
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
 | MCP-capable clients | Use `memory_search` and `memory_get_chunk` through `memory-seed-mcp --stdio`. |
 
+## Agent Hooks
+
+`memory-seed init` and `memory-seed update` install lifecycle hooks that keep memory current without relying on the agent to remember. Each hook is merged into the agent's own config file (existing settings are preserved), so it works regardless of which agent opens the project:
+
+| Agent | Config file | Session-log reminder | Memory-retrieval reminder |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `Stop` | `UserPromptSubmit` |
+| Codex CLI | `.codex/hooks.json` | `Stop` | `UserPromptSubmit` |
+| Gemini CLI | `.gemini/settings.json` | `Stop` | `UserPromptSubmit` |
+| Cursor | `.cursor/hooks.json` | `afterAgentResponse` | `sessionStart` |
+
+Both reminders are cross-platform Python scripts in `.memory-seed/hooks/`:
+
+- `session-log-check.py` — after a turn, reminds the agent to append a session-log entry if none was written in the last 15 minutes, and warns if the day's entries are out of ascending time order.
+- `memory-retrieval-check.py` — before substantive work, reminds the agent to retrieve prior context (`memory_search` or the most recent session files). Gated by an 8-hour marker file so it fires about once per working session.
+
+The hooks nudge; they never block. The scripts use Python 3.11+, which Memory Seed already requires.
+
 ## Reusable Seed Files
 
 ```text
@@ -144,6 +168,9 @@ GEMINI.md
 .memory-seed/
   agent-rules.md
   project-bootstrap.md
+  hooks/
+    session-log-check.py
+    memory-retrieval-check.py
   skills/
     index.md
     code_search.md
@@ -165,6 +192,7 @@ GEMINI.md
   project-bootstrap.md
   index.md
   policy.md
+  hooks/
   skills/
   sessions/
   archive/
@@ -337,7 +365,9 @@ 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.
 
-Run it over stdio:
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `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.
+
+If you are configuring the server manually, run it over stdio:
 
 ```powershell
 uvx --from memory-seed memory-seed-mcp --stdio

{memory_seed-2.1.2 → memory_seed-2.2.0}/README.md

@@ -9,6 +9,12 @@ Memory Seed is a portable local memory system for AI coding agents. It plants a
 
 It is built first for solo developers who move between Codex, Claude Code, Gemini CLI, and other file-reading agents. Teams can also use it to standardize local agent memory across repositories without introducing a database or hosted memory service.
 
+## Demo
+
+https://github.com/user-attachments/assets/b1c64d9e-4a67-4bc2-a030-d8ba7f17ccfe
+
+[▶ Watch the 30-second demo](https://github.com/jnl-tshi/memory-seed/releases/download/v2.1.3/memory-seed-demo.mp4) if the player above does not load.
+
 ## Quickstart
 
 From the root of a project where you want local agent memory:
@@ -114,6 +120,24 @@ The result is a lightweight memory workflow you can understand, commit, review,
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
 | MCP-capable clients | Use `memory_search` and `memory_get_chunk` through `memory-seed-mcp --stdio`. |
 
+## Agent Hooks
+
+`memory-seed init` and `memory-seed update` install lifecycle hooks that keep memory current without relying on the agent to remember. Each hook is merged into the agent's own config file (existing settings are preserved), so it works regardless of which agent opens the project:
+
+| Agent | Config file | Session-log reminder | Memory-retrieval reminder |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `Stop` | `UserPromptSubmit` |
+| Codex CLI | `.codex/hooks.json` | `Stop` | `UserPromptSubmit` |
+| Gemini CLI | `.gemini/settings.json` | `Stop` | `UserPromptSubmit` |
+| Cursor | `.cursor/hooks.json` | `afterAgentResponse` | `sessionStart` |
+
+Both reminders are cross-platform Python scripts in `.memory-seed/hooks/`:
+
+- `session-log-check.py` — after a turn, reminds the agent to append a session-log entry if none was written in the last 15 minutes, and warns if the day's entries are out of ascending time order.
+- `memory-retrieval-check.py` — before substantive work, reminds the agent to retrieve prior context (`memory_search` or the most recent session files). Gated by an 8-hour marker file so it fires about once per working session.
+
+The hooks nudge; they never block. The scripts use Python 3.11+, which Memory Seed already requires.
+
 ## Reusable Seed Files
 
 ```text
@@ -123,6 +147,9 @@ GEMINI.md
 .memory-seed/
   agent-rules.md
   project-bootstrap.md
+  hooks/
+    session-log-check.py
+    memory-retrieval-check.py
   skills/
     index.md
     code_search.md
@@ -144,6 +171,7 @@ GEMINI.md
   project-bootstrap.md
   index.md
   policy.md
+  hooks/
   skills/
   sessions/
   archive/
@@ -316,7 +344,9 @@ 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.
 
-Run it over stdio:
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `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.
+
+If you are configuring the server manually, run it over stdio:
 
 ```powershell
 uvx --from memory-seed memory-seed-mcp --stdio

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/core.py

@@ -128,6 +128,10 @@ _CODEX_RETRIEVAL_COMMAND = "python3 .memory-seed/hooks/memory-retrieval-check.py
 _CURSOR_RETRIEVAL_COMMAND = "python3 .memory-seed/hooks/memory-retrieval-check.py --cursor"
 _GEMINI_RETRIEVAL_COMMAND = "python3 .memory-seed/hooks/memory-retrieval-check.py --gemini"
 
+_MCP_SERVER_COMMAND = "memory-seed-mcp"
+_MCP_SERVER_ARGS = ["--stdio"]
+_MCP_SERVER_KEY = "memory-seed"
+
 BOOTSTRAP_GENERATED_FILES = [
     ".memory-seed/index.md",
     ".memory-seed/policy.md",
@@ -191,132 +195,54 @@ def resolve_runtime(cwd: str | Path = ".") -> Runtime:
 
 
 def _merge_cursor_hook(target_root: Path) -> bool:
-    """Add the session-log afterAgentResponse hook to .cursor/hooks.json."""
-    hooks_path = target_root / ".cursor" / "hooks.json"
-
-    data: dict = {}
-    if hooks_path.exists():
-        try:
-            with open(hooks_path) as f:
-                data = json.load(f)
-        except (json.JSONDecodeError, OSError):
-            data = {}
-
-    data.setdefault("version", 1)
-    for entry in data.get("hooks", {}).get("afterAgentResponse", []):
-        if entry.get("command") == _CURSOR_HOOK_COMMAND:
-            return False
-
-    data.setdefault("hooks", {}).setdefault("afterAgentResponse", []).append(
-        {"command": _CURSOR_HOOK_COMMAND}
+    """Upsert the session-log afterAgentResponse hook in .cursor/hooks.json."""
+    return _merge_cursor_event_hook(
+        target_root / ".cursor" / "hooks.json",
+        "afterAgentResponse",
+        _CURSOR_HOOK_COMMAND,
+        "session-log-check.py",
     )
 
-    hooks_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(hooks_path, "w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-
-    return True
-
 
 def _merge_gemini_hook(target_root: Path) -> bool:
-    """Add the session-log Stop hook to .gemini/settings.json."""
-    settings_path = target_root / ".gemini" / "settings.json"
-
-    data: dict = {}
-    if settings_path.exists():
-        try:
-            with open(settings_path) as f:
-                data = json.load(f)
-        except (json.JSONDecodeError, OSError):
-            data = {}
-
-    for group in data.get("hooks", {}).get("Stop", []):
-        for hook in group.get("hooks", []):
-            if hook.get("command") == _GEMINI_HOOK_COMMAND:
-                return False
-
-    data.setdefault("hooks", {}).setdefault("Stop", []).append(
-        {"hooks": [{"type": "command", "command": _GEMINI_HOOK_COMMAND}]}
+    """Upsert the session-log Stop hook in .gemini/settings.json."""
+    return _merge_grouped_hook(
+        target_root / ".gemini" / "settings.json",
+        "Stop",
+        _GEMINI_HOOK_COMMAND,
+        "session-log-check.py",
     )
 
-    settings_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(settings_path, "w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-
-    return True
-
 
 def _merge_codex_hook(target_root: Path) -> bool:
-    """Add the session-log Stop hook to .codex/hooks.json, merging with existing content.
-
-    Returns True if the file was created or modified, False if the hook was already present.
-    """
-    hooks_path = target_root / ".codex" / "hooks.json"
-
-    data: dict = {}
-    if hooks_path.exists():
-        try:
-            with open(hooks_path) as f:
-                data = json.load(f)
-        except (json.JSONDecodeError, OSError):
-            data = {}
-
-    for group in data.get("hooks", {}).get("Stop", []):
-        for hook in group.get("hooks", []):
-            if hook.get("command") == _CODEX_HOOK_COMMAND:
-                return False
-
-    data.setdefault("hooks", {}).setdefault("Stop", []).append(
-        {"hooks": [{"type": "command", "command": _CODEX_HOOK_COMMAND}]}
+    """Upsert the session-log Stop hook in .codex/hooks.json."""
+    return _merge_grouped_hook(
+        target_root / ".codex" / "hooks.json",
+        "Stop",
+        _CODEX_HOOK_COMMAND,
+        "session-log-check.py",
     )
 
-    hooks_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(hooks_path, "w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-
-    return True
-
 
 def _merge_claude_hook(target_root: Path) -> bool:
-    """Add the session-log Stop hook to .claude/settings.json, merging with existing content.
-
-    Returns True if the file was created or modified, False if the hook was already present.
-    """
-    settings_path = target_root / ".claude" / "settings.json"
-
-    data: dict = {}
-    if settings_path.exists():
-        try:
-            with open(settings_path) as f:
-                data = json.load(f)
-        except (json.JSONDecodeError, OSError):
-            data = {}
-
-    for group in data.get("hooks", {}).get("Stop", []):
-        for hook in group.get("hooks", []):
-            if hook.get("command") == _CLAUDE_HOOK_COMMAND:
-                return False
-
-    data.setdefault("hooks", {}).setdefault("Stop", []).append(
-        {"hooks": [{"type": "command", "command": _CLAUDE_HOOK_COMMAND}]}
+    """Upsert the session-log Stop hook in .claude/settings.json."""
+    return _merge_grouped_hook(
+        target_root / ".claude" / "settings.json",
+        "Stop",
+        _CLAUDE_HOOK_COMMAND,
+        "session-log-check.py",
     )
 
-    settings_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(settings_path, "w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-
-    return True
-
 
-def _merge_grouped_hook(config_path: Path, event: str, command: str) -> bool:
-    """Add a command hook under hooks.<event> in matcher-group form.
+def _merge_grouped_hook(config_path: Path, event: str, command: str, script_name: str) -> bool:
+    """Upsert a command hook under hooks.<event> in matcher-group form.
 
     Used for Claude Code, Codex, and Gemini, which share the
-    hooks.<event>[].hooks[].{type, command} shape. Idempotent.
+    hooks.<event>[].hooks[].{type, command} shape.
+
+    Identifies our entry by script_name (the stable filename). If an entry
+    with that script is found with a different command, updates it in place.
+    Returns True if the file was written, False if already current.
     """
     data: dict = {}
     if config_path.exists():
@@ -330,6 +256,13 @@ def _merge_grouped_hook(config_path: Path, event: str, command: str) -> bool:
         for hook in group.get("hooks", []):
             if hook.get("command") == command:
                 return False
+            if script_name in (hook.get("command") or ""):
+                hook["command"] = command
+                config_path.parent.mkdir(parents=True, exist_ok=True)
+                with open(config_path, "w") as f:
+                    json.dump(data, f, indent=2)
+                    f.write("\n")
+                return True
 
     data.setdefault("hooks", {}).setdefault(event, []).append(
         {"hooks": [{"type": "command", "command": command}]}
@@ -343,8 +276,12 @@ def _merge_grouped_hook(config_path: Path, event: str, command: str) -> bool:
     return True
 
 
-def _merge_cursor_event_hook(config_path: Path, event: str, command: str) -> bool:
-    """Add a command hook under hooks.<event> in Cursor's flat list form."""
+def _merge_cursor_event_hook(config_path: Path, event: str, command: str, script_name: str) -> bool:
+    """Upsert a command hook under hooks.<event> in Cursor's flat list form.
+
+    Identifies our entry by script_name. Updates in place if command changed.
+    Returns True if the file was written, False if already current.
+    """
     data: dict = {}
     if config_path.exists():
         try:
@@ -357,6 +294,13 @@ def _merge_cursor_event_hook(config_path: Path, event: str, command: str) -> boo
     for entry in data.get("hooks", {}).get(event, []):
         if entry.get("command") == command:
             return False
+        if script_name in (entry.get("command") or ""):
+            entry["command"] = command
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(config_path, "w") as f:
+                json.dump(data, f, indent=2)
+                f.write("\n")
+            return True
 
     data.setdefault("hooks", {}).setdefault(event, []).append({"command": command})
 
@@ -373,6 +317,7 @@ def _merge_claude_retrieval_hook(target_root: Path) -> bool:
         target_root / ".claude" / "settings.json",
         "UserPromptSubmit",
         _CLAUDE_RETRIEVAL_COMMAND,
+        "memory-retrieval-check.py",
     )
 
 
@@ -381,6 +326,7 @@ def _merge_codex_retrieval_hook(target_root: Path) -> bool:
         target_root / ".codex" / "hooks.json",
         "UserPromptSubmit",
         _CODEX_RETRIEVAL_COMMAND,
+        "memory-retrieval-check.py",
     )
 
 
@@ -389,6 +335,7 @@ def _merge_gemini_retrieval_hook(target_root: Path) -> bool:
         target_root / ".gemini" / "settings.json",
         "UserPromptSubmit",
         _GEMINI_RETRIEVAL_COMMAND,
+        "memory-retrieval-check.py",
     )
 
 
@@ -397,9 +344,97 @@ def _merge_cursor_retrieval_hook(target_root: Path) -> bool:
         target_root / ".cursor" / "hooks.json",
         "sessionStart",
         _CURSOR_RETRIEVAL_COMMAND,
+        "memory-retrieval-check.py",
     )
 
 
+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"}
+
+    data: dict = {}
+    if settings_path.exists():
+        try:
+            with open(settings_path) as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            data = {}
+
+    existing = data.get("mcpServers", {}).get(_MCP_SERVER_KEY, {})
+    if existing == expected:
+        return False
+    if existing and existing.get("command") != _MCP_SERVER_COMMAND:
+        return False  # a different server is using this key; don't overwrite
+
+    data.setdefault("mcpServers", {})[_MCP_SERVER_KEY] = expected
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(settings_path, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+    return True
+
+
+def _merge_cursor_mcp(target_root: Path) -> bool:
+    """Upsert the memory-seed-mcp stdio server entry in .cursor/mcp.json."""
+    mcp_path = target_root / ".cursor" / "mcp.json"
+    expected = {"command": _MCP_SERVER_COMMAND, "args": _MCP_SERVER_ARGS}
+
+    data: dict = {}
+    if mcp_path.exists():
+        try:
+            with open(mcp_path) as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            data = {}
+
+    existing = data.get("mcpServers", {}).get(_MCP_SERVER_KEY, {})
+    if existing == expected:
+        return False
+    if existing and existing.get("command") != _MCP_SERVER_COMMAND:
+        return False  # a different server is using this key; don't overwrite
+
+    data.setdefault("mcpServers", {})[_MCP_SERVER_KEY] = expected
+
+    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 _merge_gemini_mcp(target_root: Path) -> bool:
+    """Upsert the memory-seed-mcp stdio server entry in .gemini/settings.json."""
+    settings_path = target_root / ".gemini" / "settings.json"
+    expected = {"command": _MCP_SERVER_COMMAND, "args": _MCP_SERVER_ARGS}
+
+    data: dict = {}
+    if settings_path.exists():
+        try:
+            with open(settings_path) as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            data = {}
+
+    existing = data.get("mcpServers", {}).get(_MCP_SERVER_KEY, {})
+    if existing == expected:
+        return False
+    if existing and existing.get("command") != _MCP_SERVER_COMMAND:
+        return False  # a different server is using this key; don't overwrite
+
+    data.setdefault("mcpServers", {})[_MCP_SERVER_KEY] = expected
+
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(settings_path, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+    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]
@@ -445,6 +480,9 @@ 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_cursor_mcp, ".cursor/mcp.json"),
+        (_merge_gemini_mcp, ".gemini/settings.json"),
     )
     for merge, destination in hook_merges:
         if merge(target_root) and destination not in created:
@@ -507,6 +545,9 @@ 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_cursor_mcp, ".cursor/mcp.json"),
+        (_merge_gemini_mcp, ".gemini/settings.json"),
     )
     for merge, destination in hook_merges:
         if merge(target_root) and destination not in created:

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/seed/.memory-seed/agent-rules.md

@@ -89,7 +89,7 @@ Do not read or apply `.memory-seed/project-bootstrap.md` during normal operating
 
 ## History Retrieval And Conflict Resolution
 
-Use MCP history retrieval when prior decisions, rationale, unresolved risks, architecture, policy, bootstrap behavior, release history, or "why was this done" matters. This is a quick-start for agents that can call MCP tools.
+Use MCP history retrieval when prior decisions, reason, unresolved risks, architecture, policy, bootstrap behavior, release history, or "why was this done" matters. This is a quick-start for agents that can call MCP tools.
 
 ### When To Search
 
@@ -155,7 +155,7 @@ Use the fetched chunk text, not just the excerpt, when making or evaluating a co
 
 If MCP tools are unavailable, read recent and relevant `.memory-seed/sessions/YYYY-MM-DD.md` files directly. Start with the last two session files, then search older dated files by keyword if needed. Apply the same authority and conflict rules below.
 
-Current files are the active authority: `.memory-seed/index.md`, `.memory-seed/policy.md`, active `.memory-seed/skills/*.md`, and source/config files for implementation truth. Session history is evidence and rationale, not automatic authority.
+Current files are the active authority: `.memory-seed/index.md`, `.memory-seed/policy.md`, active `.memory-seed/skills/*.md`, and source/config files for implementation truth. Session history is evidence and reason, not automatic authority.
 
 When history conflicts with current authority files, resolve by timeline only when all clear supersession criteria are met:
 
@@ -300,7 +300,7 @@ This is the invariant the "do not rewrite old session entries" rule protects: ou
 
 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.
 
-Session entries must capture rationale when it matters, without forcing ceremony for small work. Use rationale for durable decisions, architecture changes, policy changes, bootstrap choices, release decisions, non-obvious tradeoffs, or changes likely to confuse a future agent.
+Session entries must capture reason when it matters, without forcing ceremony for small work. Use reason for durable decisions, architecture changes, policy changes, bootstrap choices, release decisions, non-obvious tradeoffs, or changes likely to confuse a future agent.
 
 ## Consolidation Review Triggers
 
@@ -390,6 +390,27 @@ subproject_path: null
 
 Keep session filenames date-only, such as `.memory-seed/sessions/2026-05-02.md`. Use minute-level timestamps in entry headings, taken from the current system clock at write time. Entries are appended in clock order and never backdated or reordered (see Append-Only Chronology). Generate `entry_id` as a deterministic short hash from metadata only: timestamp, title, user initials, agent type, project path, and subproject path. Use known user initials when available; otherwise ask during bootstrap or use a neutral placeholder until confirmed. Capture meaningful decisions, durable changes, follow-up risk, or handoff context. Do not log every command.
 
+### Reason Rules
+
+**DRAFT** is the compact decision-record format used inside session entries. Use it whenever a meaningful decision was made or implemented.
+
+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)
+- F = Files, artifacts, or behaviors changed (optional)
+- T = Tests or validation outcome (optional; may appear inline as `- T:` or as a separate `### Validation` section)
+
+`D` and `R` are required for every meaningful decision. `A`, `F`, and `T` are optional when not relevant.
+
+- Do not invent reason.
+- If reason is inferred, label it `Inferred reason`.
+- If reason is unknown, write `Reason not recorded`.
+- Alternatives are optional unless they affected the decision or tradeoff.
+- Use `D1`, `D2`, and similar labels only inside a multi-decision entry; `entry_id` is the global reference.
+- Do not rewrite old logs solely to match the newest schema unless the user explicitly asks.
+
 ### Entry Shapes
 
 Use the lightest entry shape that preserves future usefulness.
@@ -463,22 +484,6 @@ Use one entry when several decisions belong to one coherent task, plan, or user
 - Residual risks or next actions.
 ```
 
-### Rationale Rules
-
-- A DRAFT decision record uses compact labels:
-  - D = Decision
-  - R = Rationale
-  - A = Alternatives considered or rejected, with reason
-  - F = Files, artifacts, or behaviors changed
-  - T = Tests or validation
-- In a DRAFT decision record, `D` and `R` are required for meaningful decisions; `A`, `F`, and `T` are optional when not relevant.
-- Do not invent rationale.
-- If rationale is inferred, label it `Inferred rationale`.
-- If rationale is unknown, write `Rationale not recorded`.
-- Alternatives are optional unless they affected the decision or tradeoff.
-- Use `D1`, `D2`, and similar labels only inside a multi-decision entry; `entry_id` is the global reference.
-- Do not rewrite old logs solely to match the newest schema unless the user explicitly asks.
-
 ## Archive Policy
 
 Archive prior control-plane snapshots under `.memory-seed/archive/<version>/` before replacing reusable versioned artifacts. Archive snapshots are historical records and may preserve old path names.

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/seed/.memory-seed/hooks/memory-retrieval-check.py

@@ -1,4 +1,5 @@
 import json
+import shutil
 import sys
 from pathlib import Path
 from datetime import datetime, timedelta
@@ -27,14 +28,29 @@ try:
 except OSError:
     pass
 
-reminder = (
-    "MEMORY RETRIEVAL REMINDER: Before substantive work, retrieve relevant "
-    "prior context. Call the memory_search MCP tool, or if MCP is "
-    "unavailable read the two most recent .memory-seed/sessions/*.md files. "
-    "Do this before editing code or making decisions so you build on past "
-    "work instead of repeating it."
+_draft = (
+    "Record durable decisions using DRAFT labels: "
+    "D (Decision, required), R (Reason, required), "
+    "A (Alternatives, optional), F (Files, optional), T (Tests, optional)."
 )
 
+if shutil.which("memory-seed-mcp") is not None:
+    reminder = (
+        "MEMORY RETRIEVAL REMINDER: Before substantive work, retrieve relevant "
+        "prior context. Call the memory_search MCP tool, or if MCP is "
+        "unavailable read the two most recent .memory-seed/sessions/*.md files. "
+        "Do this before editing code or making decisions so you build on past "
+        f"work instead of repeating it. {_draft}"
+    )
+else:
+    reminder = (
+        "MEMORY RETRIEVAL REMINDER: memory-seed-mcp is not on PATH — the "
+        "memory_search tool is unavailable. To fix: run "
+        "`uv tool install memory-seed` (or `pip install memory-seed`), then "
+        "restart your editor. For now, read the two most recent "
+        f".memory-seed/sessions/*.md files before substantive work. {_draft}"
+    )
+
 if agent == "codex":
     # Codex CLI UserPromptSubmit: systemMessage shown in UI
     print(json.dumps({"systemMessage": reminder, "continue": True}))

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/seed/.memory-seed/hooks/session-log-check.py

@@ -27,7 +27,10 @@ if not recent:
         f"SESSION LOG REMINDER: No .memory-seed/sessions/ entry has been "
         f"updated in the last 15 minutes. If you completed meaningful work "
         f"this turn, append an entry to .memory-seed/sessions/{today}.md "
-        f"now — before this turn ends."
+        f"now — before this turn ends. "
+        f"For decisions, use DRAFT labels: "
+        f"D (Decision, required), R (Reason, required), "
+        f"A (Alternatives, optional), F (Files, optional), T (Tests, optional)."
     )
 
 # Chronology check: today's entry headings must be in non-decreasing time order.

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/seed/.memory-seed/project-bootstrap.md

@@ -284,7 +284,7 @@ Include:
 - inheritance choices
 - follow-up gaps
 
-Record rationale for bootstrap choices that shape future behavior:
+Record reason for bootstrap choices that shape future behavior:
 
 - project classification
 - policy and risk posture
@@ -292,7 +292,7 @@ Record rationale for bootstrap choices that shape future behavior:
 - active skill selection
 - major assumptions
 
-Do not require rationale for obvious file discoveries. Do not invent rationale; mark inferred rationale explicitly or write `Rationale not recorded` when unknown.
+Do not require reason for obvious file discoveries. Do not invent reason; mark inferred reason explicitly or write `Reason not recorded` when unknown.
 
 Keep sessions append-only.
 

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed/seed/.memory-seed/skills/memory_consolidation.md

@@ -20,14 +20,14 @@ Use this skill when compacting session history, reviewing recent work, or promot
 6. Promote reusable procedures into `.memory-seed/skills/*.md`.
 7. Leave one-off debugging traces, temporary hypotheses, superseded experiments, and raw command output in sessions only.
 
-## Rationale Boundary
+## Reason Boundary
 
-- sessions preserve rationale and tradeoffs.
+- sessions preserve reason and tradeoffs.
 - index.md receives only durable current conclusions.
 - policy.md receives only durable behavioral constraints.
 - Preserve DRAFT decision records in sessions.
-- Do not copy full rationale into index.md unless a short rationale note is needed to prevent likely misuse.
-- Preserve alternatives, rejected paths, inferred rationale, and unknown-rationale markers in session history.
+- Do not copy full reason into index.md unless a short reason note is needed to prevent likely misuse.
+- Preserve alternatives, rejected paths, inferred reason, and unknown-reason markers in session history.
 
 ## Commands
 

{memory_seed-2.1.2 → memory_seed-2.2.0}/memory_seed.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memory-seed
-Version: 2.1.2
+Version: 2.2.0
 Summary: Portable local memory seed for file-reading AI coding agents
 Author: Jean Nathan Tshibuyi
 License: MIT
@@ -30,6 +30,12 @@ Memory Seed is a portable local memory system for AI coding agents. It plants a
 
 It is built first for solo developers who move between Codex, Claude Code, Gemini CLI, and other file-reading agents. Teams can also use it to standardize local agent memory across repositories without introducing a database or hosted memory service.
 
+## Demo
+
+https://github.com/user-attachments/assets/b1c64d9e-4a67-4bc2-a030-d8ba7f17ccfe
+
+[▶ Watch the 30-second demo](https://github.com/jnl-tshi/memory-seed/releases/download/v2.1.3/memory-seed-demo.mp4) if the player above does not load.
+
 ## Quickstart
 
 From the root of a project where you want local agent memory:
@@ -135,6 +141,24 @@ The result is a lightweight memory workflow you can understand, commit, review,
 | Other file-reading agents | Start from `AGENTS.md` and follow nearest `.memory-seed/` runtime discovery. |
 | MCP-capable clients | Use `memory_search` and `memory_get_chunk` through `memory-seed-mcp --stdio`. |
 
+## Agent Hooks
+
+`memory-seed init` and `memory-seed update` install lifecycle hooks that keep memory current without relying on the agent to remember. Each hook is merged into the agent's own config file (existing settings are preserved), so it works regardless of which agent opens the project:
+
+| Agent | Config file | Session-log reminder | Memory-retrieval reminder |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `Stop` | `UserPromptSubmit` |
+| Codex CLI | `.codex/hooks.json` | `Stop` | `UserPromptSubmit` |
+| Gemini CLI | `.gemini/settings.json` | `Stop` | `UserPromptSubmit` |
+| Cursor | `.cursor/hooks.json` | `afterAgentResponse` | `sessionStart` |
+
+Both reminders are cross-platform Python scripts in `.memory-seed/hooks/`:
+
+- `session-log-check.py` — after a turn, reminds the agent to append a session-log entry if none was written in the last 15 minutes, and warns if the day's entries are out of ascending time order.
+- `memory-retrieval-check.py` — before substantive work, reminds the agent to retrieve prior context (`memory_search` or the most recent session files). Gated by an 8-hour marker file so it fires about once per working session.
+
+The hooks nudge; they never block. The scripts use Python 3.11+, which Memory Seed already requires.
+
 ## Reusable Seed Files
 
 ```text
@@ -144,6 +168,9 @@ GEMINI.md
 .memory-seed/
   agent-rules.md
   project-bootstrap.md
+  hooks/
+    session-log-check.py
+    memory-retrieval-check.py
   skills/
     index.md
     code_search.md
@@ -165,6 +192,7 @@ GEMINI.md
   project-bootstrap.md
   index.md
   policy.md
+  hooks/
   skills/
   sessions/
   archive/
@@ -337,7 +365,9 @@ 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.
 
-Run it over stdio:
+**Auto-registration:** `memory-seed init` and `memory-seed update` automatically register `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.
+
+If you are configuring the server manually, run it over stdio:
 
 ```powershell
 uvx --from memory-seed memory-seed-mcp --stdio

{memory_seed-2.1.2 → memory_seed-2.2.0}/pyproject.toml

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

{memory_seed-2.1.2 → memory_seed-2.2.0}/tests/test_memory_seed.py

@@ -493,6 +493,63 @@ class HookMergeTests(unittest.TestCase):
         self.assertTrue(_merge_cursor_retrieval_hook(cwd))
         self.assertFalse(_merge_cursor_retrieval_hook(cwd))
 
+    def test_grouped_hook_updates_stale_command(self):
+        import json
+        from memory_seed.core import _merge_grouped_hook
+
+        cwd = self.make_project()
+        config = cwd / ".claude" / "settings.json"
+        config.parent.mkdir(parents=True, exist_ok=True)
+        config.write_text(
+            json.dumps({
+                "hooks": {
+                    "UserPromptSubmit": [
+                        {"hooks": [{"type": "command", "command": "python3 .memory-seed/hooks/memory-retrieval-check.py --old-flag"}]}
+                    ]
+                }
+            }),
+            encoding="utf-8",
+        )
+
+        new_command = "python3 .memory-seed/hooks/memory-retrieval-check.py"
+        result = _merge_grouped_hook(config, "UserPromptSubmit", new_command, "memory-retrieval-check.py")
+        self.assertTrue(result)
+
+        data = json.loads(config.read_text())
+        commands = [
+            h["command"]
+            for g in data["hooks"]["UserPromptSubmit"]
+            for h in g.get("hooks", [])
+        ]
+        self.assertEqual(commands, [new_command])  # updated in place, no duplicate
+
+    def test_cursor_event_hook_updates_stale_command(self):
+        import json
+        from memory_seed.core import _merge_cursor_event_hook
+
+        cwd = self.make_project()
+        config = cwd / ".cursor" / "hooks.json"
+        config.parent.mkdir(parents=True, exist_ok=True)
+        config.write_text(
+            json.dumps({
+                "version": 1,
+                "hooks": {
+                    "sessionStart": [
+                        {"command": "python3 .memory-seed/hooks/memory-retrieval-check.py --cursor --old-flag"}
+                    ]
+                }
+            }),
+            encoding="utf-8",
+        )
+
+        new_command = "python3 .memory-seed/hooks/memory-retrieval-check.py --cursor"
+        result = _merge_cursor_event_hook(config, "sessionStart", new_command, "memory-retrieval-check.py")
+        self.assertTrue(result)
+
+        data = json.loads(config.read_text())
+        commands = [e["command"] for e in data["hooks"]["sessionStart"]]
+        self.assertEqual(commands, [new_command])  # updated in place, no duplicate
+
 
 class SessionLogOrderingHookTests(unittest.TestCase):
     SCRIPT = Path("memory_seed/seed/.memory-seed/hooks/session-log-check.py").resolve()
@@ -537,6 +594,169 @@ class SessionLogOrderingHookTests(unittest.TestCase):
         self.assertNotIn("ORDER WARNING", self._run(cwd))
 
 
+class McpMergeTests(unittest.TestCase):
+    def make_project(self):
+        path = Path(tempfile.mkdtemp(prefix="memory-seed-mcp-"))
+        self.addCleanup(lambda: shutil.rmtree(path, ignore_errors=True))
+        return path
+
+    def test_init_installs_mcp_for_claude(self):
+        import json
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)
+
+        data = json.loads((cwd / ".claude" / "settings.json").read_text())
+        self.assertIn("memory-seed", data["mcpServers"])
+        entry = data["mcpServers"]["memory-seed"]
+        self.assertEqual(entry["command"], "memory-seed-mcp")
+        self.assertEqual(entry["args"], ["--stdio"])
+        self.assertEqual(entry["type"], "stdio")
+
+    def test_init_installs_mcp_for_cursor(self):
+        import json
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)
+
+        data = json.loads((cwd / ".cursor" / "mcp.json").read_text())
+        self.assertIn("memory-seed", data["mcpServers"])
+        entry = data["mcpServers"]["memory-seed"]
+        self.assertEqual(entry["command"], "memory-seed-mcp")
+        self.assertEqual(entry["args"], ["--stdio"])
+        self.assertNotIn("type", entry)
+
+    def test_init_installs_mcp_for_gemini(self):
+        import json
+
+        cwd = self.make_project()
+        init_project(cwd=cwd)
+
+        data = json.loads((cwd / ".gemini" / "settings.json").read_text())
+        self.assertIn("memory-seed", data["mcpServers"])
+        entry = data["mcpServers"]["memory-seed"]
+        self.assertEqual(entry["command"], "memory-seed-mcp")
+        self.assertEqual(entry["args"], ["--stdio"])
+
+    def test_mcp_merges_are_idempotent(self):
+        from memory_seed.core import (
+            _merge_claude_mcp,
+            _merge_cursor_mcp,
+            _merge_gemini_mcp,
+        )
+
+        cwd = self.make_project()
+        self.assertTrue(_merge_claude_mcp(cwd))
+        self.assertFalse(_merge_claude_mcp(cwd))
+        self.assertTrue(_merge_cursor_mcp(cwd))
+        self.assertFalse(_merge_cursor_mcp(cwd))
+        self.assertTrue(_merge_gemini_mcp(cwd))
+        self.assertFalse(_merge_gemini_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"}}}),
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_claude_mcp
+        result = _merge_claude_mcp(cwd)
+        self.assertTrue(result)
+
+        data = json.loads(settings.read_text())
+        self.assertEqual(data["mcpServers"]["memory-seed"]["args"], ["--stdio"])
+
+    def test_mcp_merge_preserves_unrelated_mcp_server(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": {"other-server": {"command": "other-cmd", "args": []}}}),
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_claude_mcp
+        _merge_claude_mcp(cwd)
+
+        data = json.loads(settings.read_text())
+        self.assertIn("other-server", data["mcpServers"])
+        self.assertEqual(data["mcpServers"]["other-server"]["command"], "other-cmd")
+
+    def test_gemini_mcp_merge_preserves_existing_hooks(self):
+        import json
+
+        cwd = self.make_project()
+        gemini_path = cwd / ".gemini" / "settings.json"
+        gemini_path.parent.mkdir(parents=True, exist_ok=True)
+        gemini_path.write_text(
+            json.dumps({"hooks": {"Stop": [{"hooks": [{"type": "command", "command": "existing"}]}]}}),
+            encoding="utf-8",
+        )
+
+        from memory_seed.core import _merge_gemini_mcp
+        _merge_gemini_mcp(cwd)
+
+        data = json.loads(gemini_path.read_text())
+        self.assertIn("memory-seed", data["mcpServers"])
+        self.assertIn("Stop", data["hooks"])
+        self.assertEqual(data["hooks"]["Stop"][0]["hooks"][0]["command"], "existing")
+
+
+class RetrievalCheckPathTests(unittest.TestCase):
+    SCRIPT = Path("memory_seed/seed/.memory-seed/hooks/memory-retrieval-check.py").resolve()
+
+    def make_project(self):
+        path = Path(tempfile.mkdtemp(prefix="memory-seed-retrieval-"))
+        self.addCleanup(lambda: shutil.rmtree(path, ignore_errors=True))
+        (path / ".memory-seed").mkdir()
+        return path
+
+    def _run(self, cwd, extra_env=None):
+        import subprocess
+        import sys
+        import os
+
+        env = os.environ.copy()
+        if extra_env:
+            env.update(extra_env)
+        return subprocess.run(
+            [sys.executable, str(self.SCRIPT)],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            env=env,
+        ).stdout
+
+    def test_mcp_found_message_mentions_memory_search(self):
+        import os
+        import stat
+
+        cwd = self.make_project()
+        # Create a dummy memory-seed-mcp binary on PATH
+        bin_dir = cwd / "bin"
+        bin_dir.mkdir()
+        fake_bin = bin_dir / "memory-seed-mcp"
+        fake_bin.write_text("#!/usr/bin/env python3\n")
+        fake_bin.chmod(fake_bin.stat().st_mode | stat.S_IEXEC)
+
+        out = self._run(cwd, extra_env={"PATH": str(bin_dir) + os.pathsep + os.environ.get("PATH", "")})
+        self.assertIn("memory_search", out)
+        self.assertNotIn("uv tool install", out)
+
+    def test_mcp_missing_message_mentions_install(self):
+        cwd = self.make_project()
+        out = self._run(cwd, extra_env={"PATH": ""})
+        self.assertIn("uv tool install", out)
+        self.assertNotIn("memory_search MCP tool", out)
+
+
 class CliHelpTests(unittest.TestCase):
     def _run(self, argv):
         import contextlib

{memory_seed-2.1.2 → memory_seed-2.2.0}/tests/test_session_schema.py

@@ -13,13 +13,13 @@ class SessionSchemaTests(unittest.TestCase):
             "Multi-decision session entry",
             "DRAFT decision record",
             "D = Decision",
-            "R = Rationale",
+            "R = Reason",
             "A = Alternatives considered or rejected",
             "F = Files, artifacts, or behaviors changed",
             "T = Tests or validation",
-            "Do not invent rationale",
-            "Inferred rationale",
-            "Rationale not recorded",
+            "Do not invent reason",
+            "Inferred reason",
+            "Reason not recorded",
             "Alternatives are optional",
         ):
             self.assertIn(phrase, content)
@@ -49,7 +49,7 @@ class SessionSchemaTests(unittest.TestCase):
             "clear supersession criteria",
             "newer dated session entry or current authority file",
             "no later reversal or unresolved disagreement is found",
-            "Session history is evidence and rationale",
+            "Session history is evidence and reason",
             "ask the user before changing durable design",
         ):
             self.assertIn(phrase, content)
@@ -187,7 +187,7 @@ class SessionSchemaTests(unittest.TestCase):
             "active skill selection",
             "major assumptions",
             "DRAFT decision records",
-            "Do not require rationale for obvious file discoveries",
+            "Do not require reason for obvious file discoveries",
         ):
             self.assertIn(phrase, content)
 
@@ -208,11 +208,11 @@ class SessionSchemaTests(unittest.TestCase):
         content = Path(".memory-seed/skills/memory_consolidation.md").read_text(encoding="utf-8")
 
         for phrase in (
-            "sessions preserve rationale and tradeoffs",
+            "sessions preserve reason and tradeoffs",
             "index.md receives only durable current conclusions",
             "policy.md receives only durable behavioral constraints",
             "Preserve DRAFT decision records",
-            "Do not copy full rationale into index.md",
+            "Do not copy full reason into index.md",
         ):
             self.assertIn(phrase, content)