memento-mcp 0.3.5 → 0.3.6

package/README.md

@@ -10,7 +10,7 @@ AI agents have anterograde amnesia — every session starts blank. The Memento P
 npx memento-mcp init
 ```
 
-This creates `.memento.json`, detects your agent (Claude Code, Codex, Gemini CLI, OpenCode), writes the correct MCP config, and sets up hooks (Claude Code only) — all in one command.
+This creates `.memento.json`, detects your agent (Claude Code, Codex, Gemini CLI, OpenCode), writes the correct MCP config, and registers hooks — all in one command.
 
 ---
 
@@ -154,13 +154,29 @@ Full guide: **[The Protocol](https://hifathom.com/memento/docs/protocol)** on hi
 
 ## Hooks
 
-Hooks automate memory at session boundaries — recall on every message, distillation before context loss. Three production-ready scripts are included in `scripts/`:
+Hooks automate memory at session boundaries — recall on every message, distillation before context loss, identity injection at session start. Five production-ready scripts are included in `scripts/`:
 
-| Script | Event | What it does |
-|--------|-------|-------------|
-| `memento-userprompt-recall.sh` | UserPromptSubmit | Recalls memories relevant to the user's message |
-| `memento-stop-recall.sh` | Stop | Recalls memories from the assistant's own output (autonomous work) |
-| `memento-precompact-distill.sh` | PreCompact | Extracts memories from the conversation before context compression |
+| Script | What it does |
+|--------|-------------|
+| `memento-sessionstart-identity.sh` | Injects identity crystal + version check at session start |
+| `memento-userprompt-recall.sh` | Recalls memories relevant to the user's message |
+| `memento-stop-recall.sh` | Recalls memories from the assistant's own output (autonomous work) |
+| `memento-precompact-distill.sh` | Extracts memories from the conversation before context compression |
+| `memento-codex-notify.sh` | Stores post-turn summaries from Codex CLI as memory observations |
+
+### Agent hook support
+
+`npx memento-mcp init` auto-detects your agent and registers the appropriate hooks. Not all agents support the same hook events — here's what gets wired up:
+
+| Hook | Claude Code | Gemini CLI | Codex CLI |
+|------|:-----------:|:----------:|:---------:|
+| Session start / identity | `SessionStart` | `SessionStart` | — |
+| Recall on user message | `UserPromptSubmit` | `BeforeAgent` | — |
+| Recall on assistant output | `Stop` | `SessionEnd` | — |
+| Pre-compaction distillation | `PreCompact` | `PreCompress` | — |
+| Post-turn memory storage | — | — | `notify` |
+
+**OpenCode** uses a TypeScript plugin system — MCP tools work, but hooks require a different integration pattern.
 
 See **[scripts/README.md](scripts/README.md)** for setup, configuration, and how to write your own hooks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "mcpName": "io.github.myrakrusemark/memento-protocol",
   "description": "The Memento Protocol — persistent memory for AI agents",
   "type": "module",

package/scripts/README.md

@@ -1,18 +1,56 @@
 # Memento Protocol — Hook Scripts
 
-Automation hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that connect the Memento API to session lifecycle events. These scripts make memory automatic — recall on every message, distillation before context loss.
+Automation hooks that connect the Memento API to agent lifecycle events. These scripts make memory automatic — recall on every message, distillation before context loss, identity injection at session start.
 
-## Naming convention
+## Supported agents
 
-Hook scripts follow the pattern `[system]-[hook]-[verb].sh`:
+Memento hooks work with three CLI agents. Each has a different hook system, but the same scripts power all of them.
 
-| Script | Event | What it does |
-|--------|-------|-------------|
-| `memento-userprompt-recall.sh` | UserPromptSubmit | Recall memories relevant to the user's message |
-| `memento-stop-recall.sh` | Stop | Recall memories relevant to the assistant's own output |
-| `memento-precompact-distill.sh` | PreCompact | Extract memories from the conversation before context compression |
+| Hook | Claude Code | Gemini CLI | Codex CLI |
+|------|:-----------:|:----------:|:---------:|
+| Session start / identity | `SessionStart` | `SessionStart` | — |
+| Recall on user message | `UserPromptSubmit` | `BeforeAgent` | — |
+| Recall on assistant output | `Stop` | `SessionEnd` | — |
+| Pre-compaction distillation | `PreCompact` | `PreCompress` | — |
+| Post-turn memory storage | — | — | `notify` |
 
-## Set up hooks
+**OpenCode** uses a TypeScript plugin system — MCP tools work, but hooks require a different integration pattern.
+
+**Claude Code** and **Gemini CLI** have near-identical hook architectures — JSON on stdin, JSON on stdout. The same shell scripts work for both; only the event names differ.
+
+**Codex CLI** has a single `notify` mechanism — fire-and-forget, JSON as `argv[1]`, no context injection. Useful for post-turn memory storage only.
+
+## Scripts
+
+| Script | What it does |
+|--------|-------------|
+| `memento-sessionstart-identity.sh` | Injects identity crystal + version check at session start |
+| `memento-userprompt-recall.sh` | Recalls memories relevant to the user's message |
+| `memento-stop-recall.sh` | Recalls memories from the assistant's own output |
+| `memento-precompact-distill.sh` | Extracts memories from the conversation before context compression |
+| `memento-codex-notify.sh` | Stores post-turn summaries from Codex CLI as memory observations |
+
+## Automatic setup
+
+The recommended way to set up hooks:
+
+```bash
+npx memento-mcp init
+```
+
+This detects your agent, registers hooks in the correct config file, and copies scripts to `.memento/scripts/`. No manual configuration needed.
+
+To update hooks in an existing project:
+
+```bash
+npx memento-mcp update
+```
+
+---
+
+## Manual setup
+
+If you prefer to configure hooks yourself:
 
 ### 1. Create a `.env` file
 
@@ -36,18 +74,29 @@ The `.env` file is gitignored. All scripts source it automatically.
 chmod +x scripts/*.sh
 ```
 
-### 3. Register hooks in Claude Code
+### 3. Register hooks
+
+#### Claude Code
 
-Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+Add to `.claude/settings.local.json` (project-level) or `~/.claude/settings.json` (global):
 
 ```json
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash .memento/scripts/memento-sessionstart-identity.sh",
+          "timeout": 10000
+        }]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [{
           "type": "command",
-          "command": "/path/to/memento-protocol/scripts/memento-userprompt-recall.sh",
+          "command": "bash .memento/scripts/memento-userprompt-recall.sh",
           "timeout": 5000
         }]
       }
@@ -56,7 +105,7 @@ Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (glo
       {
         "hooks": [{
           "type": "command",
-          "command": "/path/to/memento-protocol/scripts/memento-stop-recall.sh",
+          "command": "bash .memento/scripts/memento-stop-recall.sh",
           "timeout": 5000
         }]
       }
@@ -65,7 +114,54 @@ Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (glo
       {
         "hooks": [{
           "type": "command",
-          "command": "/path/to/memento-protocol/scripts/memento-precompact-distill.sh",
+          "command": "bash .memento/scripts/memento-precompact-distill.sh",
+          "timeout": 30000
+        }]
+      }
+    ]
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `.gemini/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash .memento/scripts/memento-sessionstart-identity.sh",
+          "timeout": 10000
+        }]
+      }
+    ],
+    "BeforeAgent": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash .memento/scripts/memento-userprompt-recall.sh",
+          "timeout": 5000
+        }]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash .memento/scripts/memento-stop-recall.sh",
+          "timeout": 5000
+        }]
+      }
+    ],
+    "PreCompress": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash .memento/scripts/memento-precompact-distill.sh",
           "timeout": 30000
         }]
       }
@@ -74,13 +170,29 @@ Add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (glo
 }
 ```
 
-Replace `/path/to/memento-protocol` with the actual absolute path to your clone.
+#### Codex CLI
+
+Add to `.codex/config.toml`:
+
+```toml
+notify = ["bash", ".memento/scripts/memento-codex-notify.sh"]
+```
+
+Codex `notify` fires on `agent-turn-complete` — the script receives JSON as `argv[1]` (not stdin) and stores a memory observation from the assistant's response. Fire-and-forget only — no context injection.
 
 ---
 
 ## Script details
 
-### `memento-userprompt-recall.sh` — UserPromptSubmit
+### `memento-sessionstart-identity.sh` — SessionStart
+
+Fires when a session begins. Injects the identity crystal into model context and checks whether a newer version of memento-mcp is available.
+
+- **Timeout:** 10 seconds
+- **Model sees:** Identity crystal text + update notice (if newer version available)
+- **Version check:** Compares `.memento/version` against npm registry (2s timeout, silent on failure)
+
+### `memento-userprompt-recall.sh` — UserPromptSubmit / BeforeAgent
 
 Fires before every agent response. Sends the user's message to `/v1/context`, which returns relevant memories and skip list warnings.
 
@@ -91,7 +203,7 @@ Fires before every agent response. Sends the user's message to `/v1/context`, wh
 
 **Output format:** JSON with `systemMessage` (user display) + `hookSpecificOutput.additionalContext` (model context).
 
-### `memento-stop-recall.sh` — Stop
+### `memento-stop-recall.sh` — Stop / SessionEnd
 
 Fires after every assistant response. Uses the assistant's own output as the recall query — so memories surface during autonomous work, not just on user messages.
 
@@ -105,9 +217,9 @@ Fires after every assistant response. Uses the assistant's own output as the rec
 
 **Why this matters:** Without the Stop hook, memories only surface when a human sends a message. For autonomous agents that work independently — running ping routines, doing research, monitoring news — their own memories never get recalled. The Stop hook closes that gap.
 
-### `memento-precompact-distill.sh` — PreCompact
+### `memento-precompact-distill.sh` — PreCompact / PreCompress
 
-Fires before Claude Code compresses the conversation. Parses the full JSONL transcript and extracts novel facts, decisions, and observations as stored memories. Supports two extraction backends:
+Fires before the agent compresses the conversation. Parses the full JSONL transcript and extracts novel facts, decisions, and observations as stored memories. Supports two extraction backends:
 
 - **`"llama"` (default)** — sends transcript to `/v1/distill`, which runs Llama 3.1 8B via Cloudflare Workers AI. Free.
 - **`"claude-code"`** — runs `claude -p` locally for better extraction quality, then pushes to `/v1/memories/ingest`. Uses API credits.
@@ -135,19 +247,33 @@ Configure the model in `.memento.json`:
 
 **Why this matters:** Context compaction destroys information. Without distillation, anything discussed but not explicitly saved is lost. This hook captures what's novel — deduplicating against existing memories — so nothing important vanishes.
 
+### `memento-codex-notify.sh` — Codex notify
+
+Receives JSON as `argv[1]` on `agent-turn-complete` events. Extracts the assistant's response and stores it as a memory observation — best-effort, fire-and-forget.
+
+- **Event filter:** Only handles `agent-turn-complete` (other event types exit silently)
+- **Minimum threshold:** Messages under 50 characters are skipped
+- **Truncation:** Stores first 500 characters of the assistant's response
+- **Tags:** `codex`, `turn-summary`, `auto-capture`
+- **Config:** Reads `.memento.json` for API key, URL, and workspace
+
+**Why this matters:** Codex CLI can't inject context back into the model, so recall hooks don't apply. But post-turn storage still captures what the agent learned — available for recall in future sessions via any agent.
+
 ---
 
 ## Hook output formats
 
-Claude Code hooks can output data in several formats. These scripts use two:
+Claude Code and Gemini CLI hooks output data in the same JSON formats:
 
 | Format | Where it appears | Used by |
 |--------|-----------------|---------|
 | `systemMessage` | User's terminal | All scripts |
-| `hookSpecificOutput.additionalContext` | Model context (system-reminder) | UserPromptSubmit recall |
-| `decision: "block"` with `reason` | Model context (next instruction) | Stop recall |
+| `hookSpecificOutput.additionalContext` | Model context (system-reminder) | UserPromptSubmit / BeforeAgent recall |
+| `decision: "block"` with `reason` | Model context (next instruction) | Stop / SessionEnd recall |
 
-The `additionalContext` approach only works for UserPromptSubmit, PreToolUse, and PostToolUse events. For Stop hooks, the `decision: "block"` pattern is the only mechanism that injects content into model context.
+The `additionalContext` approach works for UserPromptSubmit/BeforeAgent, PreToolUse, and PostToolUse events. For Stop/SessionEnd hooks, the `decision: "block"` pattern is the only mechanism that injects content into model context.
+
+Codex `notify` has no output mechanism — it's fire-and-forget.
 
 ---
 
@@ -165,8 +291,13 @@ The `additionalContext` approach only works for UserPromptSubmit, PreToolUse, an
 
 Follow the naming convention: `[system]-[hook]-[verb].sh`. Your script receives JSON on stdin with event-specific fields:
 
-- **UserPromptSubmit:** `{ "prompt": "user's message" }`
-- **Stop:** `{ "last_assistant_message": "...", "stop_hook_active": false }`
-- **PreCompact:** `{ "transcript_path": "~/.claude/projects/.../conversation.jsonl" }`
+**Claude Code / Gemini CLI** (JSON on stdin):
+- **SessionStart:** `{ "session_id": "..." }`
+- **UserPromptSubmit / BeforeAgent:** `{ "prompt": "user's message" }`
+- **Stop / SessionEnd:** `{ "last_assistant_message": "...", "stop_hook_active": false }`
+- **PreCompact / PreCompress:** `{ "transcript_path": "~/.claude/projects/.../conversation.jsonl" }`
+
+**Codex CLI** (JSON as `argv[1]`):
+- **agent-turn-complete:** `{ "type": "agent-turn-complete", "last-assistant-message": "...", "input-messages": [...] }`
 
 Source `.env` for credentials, call the Memento API, and output JSON to stdout. Exit 0 for no-op (nothing to report).

package/src/cli.js

@@ -119,7 +119,7 @@ before compaction. Trust the hooks. Focus on writing good memories.`;
 // ---------------------------------------------------------------------------
 
 const HEADLESS_CMDS = {
-  "claude-code": (prompt) => ["claude", "-p", prompt],
+  "claude-code": (prompt) => ["claude", "-p", "--dangerously-skip-permissions", prompt],
   "codex":       (prompt) => ["codex", "exec", prompt],
   "gemini":      (prompt) => ["gemini", prompt],
   "opencode":    (prompt) => ["opencode", "run", prompt],
@@ -693,12 +693,13 @@ async function runInit(flags = {}) {
     // Interactive: ask with explicit command shown
     if (cmdParts) {
       const [cmd, ...args] = cmdParts;
-      const displayCmd = `${cmd} ${args[0]}${args.length > 1 ? " ..." : ""}`;
+      const flagArgs = args.slice(0, -1).join(" ");
+      const displayCmd = `${cmd} ${flagArgs} <prompt>`;
       const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
       console.log("─".repeat(60));
       const integrate = await askYesNo(
         rl2,
-        `\n  Auto-integrate instructions into your project?\n  This will run: ${displayCmd}\n\n  Proceed?`,
+        `\n  Auto-integrate instructions into your project?\n  This will run: ${displayCmd}\n\n  ⚠  This uses --dangerously-skip-permissions so the agent can\n  write to CLAUDE.md without prompting. If you prefer, decline\n  and we'll print the instructions for you to add manually.\n\n  Proceed?`,
         true,
       );
       rl2.close();