omo-memory 0.1.1 → 0.1.2

package/README.md

@@ -32,6 +32,7 @@ After the package is published to npm, use the same package for CLI and MCP:
 
 ```sh
 npx -y omo-memory init
+npx -y omo-memory hooks install --host all
 npx -y omo-memory session bootstrap --host codex --adapter lazycodex --limit 5
 npx -y omo-memory recent --limit 5
 npx -y omo-memory mcp
@@ -64,6 +65,21 @@ grok mcp add omo-memory -- npx -y omo-memory mcp
 
 Both hosts use `~/.omo/memory/state.sqlite` by default. The `host` value is recorded when an adapter calls `memory_start_session`, not by installing separate servers.
 
+## Passive setup
+
+Install passive skills/rules/hooks with:
+
+```sh
+npx -y omo-memory hooks install --host all
+```
+
+This installs:
+
+- Codex: `~/.codex/skills/omo-memory/SKILL.md` plus a global `~/.codex/AGENTS.md` lifecycle rule.
+- Grok: `~/.grok/skills/omo-memory/SKILL.md`, a global `~/.grok/AGENTS.md` lifecycle rule, and a `~/.grok/hooks/` SessionStart hook.
+
+Codex currently exposes MCP and global instruction surfaces, but not a standalone user hook add command like Grok. The Codex passive behavior is therefore rule/skill-driven; Grok additionally gets an executable SessionStart hook.
+
 ## Session bootstrap
 
 Adapters should call the bootstrap tool at the beginning of each host session:

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { installHooks } from "./hooks.js";
 import { bootstrapSession, doctorReport, exportMemory, initMemory, purgeMemory, recentEvents, recordEvent, startSession, writeHandoff } from "./memory.js";
 import { runMcpServer } from "./mcp.js";
 async function main(argv) {
@@ -29,6 +30,9 @@ function runCommand(command, subcommand, rest) {
         const args = [subcommand, ...rest].filter((value) => value !== undefined);
         return { ok: true, ...purgeMemory({ yes: args.includes("--yes") }) };
     }
+    if (command === "hooks" && subcommand === "install") {
+        return { ok: true, ...installHooks({ host: parseHookInstallHost(readFlag(rest, "--host") ?? "all") }) };
+    }
     if (command === "session" && subcommand === "start") {
         const host = parseHost(readFlag(rest, "--host") ?? "unknown");
         const adapter = readFlag(rest, "--adapter") ?? "unknown";
@@ -73,6 +77,11 @@ function parseHost(value) {
         return value;
     fail("--host must be one of codex, opencode, grok, unknown");
 }
+function parseHookInstallHost(value) {
+    if (value === "codex" || value === "grok" || value === "all")
+        return value;
+    fail("--host must be one of codex, grok, all");
+}
 function readPositiveIntFlag(args, name, defaultValue) {
     return parsePositiveInt(readFlag(args, name) ?? String(defaultValue), name);
 }
@@ -86,7 +95,7 @@ function fail(message) {
     throw new Error(message);
 }
 function printHelp() {
-    process.stdout.write(`OMO Memory\n\nCommands:\n  omo-memory init\n  omo-memory doctor\n  omo-memory export\n  omo-memory purge --yes\n  omo-memory session start --host <codex|opencode|grok|unknown> --adapter <name>\n  omo-memory session bootstrap --host <codex|opencode|grok|unknown> --adapter <name> [--limit <n>]\n  omo-memory event record --type <type> --summary <text> [--session-id <id>]\n  omo-memory recent [--limit <n>]\n  omo-memory handoff write (--summary <text> | --summary-file <path>) [--session-id <id>]\n  omo-memory mcp\n`);
+    process.stdout.write(`OMO Memory\n\nCommands:\n  omo-memory init\n  omo-memory doctor\n  omo-memory export\n  omo-memory purge --yes\n  omo-memory hooks install --host <codex|grok|all>\n  omo-memory session start --host <codex|opencode|grok|unknown> --adapter <name>\n  omo-memory session bootstrap --host <codex|opencode|grok|unknown> --adapter <name> [--limit <n>]\n  omo-memory event record --type <type> --summary <text> [--session-id <id>]\n  omo-memory recent [--limit <n>]\n  omo-memory handoff write (--summary <text> | --summary-file <path>) [--session-id <id>]\n  omo-memory mcp\n`);
 }
 main(process.argv.slice(2)).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/hooks.js

@@ -0,0 +1,161 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CODEX_SKILL = `---
+name: omo-memory
+description: Use OMO Memory as the shared local memory ledger across Codex, Grok, and OpenCode. Trigger when starting non-trivial workspace work, needing prior session context, recording decisions, QA evidence, task state, handoffs, or using the omo-memory MCP tools.
+---
+
+# OMO Memory
+
+Use the \`omo-memory\` MCP server as the shared local memory ledger across Codex, Grok, and OpenCode.
+
+## Session Start
+
+At the beginning of non-trivial workspace work, call \`memory_bootstrap_session\` with:
+
+- \`host\`: \`codex\`
+- \`adapter\`: \`lazycodex\`
+- \`limit\`: \`5\`
+
+Read \`recentEvents\` before changing files. Keep the returned \`sessionId\` for the turn/session.
+
+## During Work
+
+Record durable, concise facts with \`memory_record_event\` and the active \`sessionId\`: decisions, QA evidence, task state, blockers, and handoff-worthy facts.
+
+Use \`memory_write_handoff\` for explicit handoff summaries.
+
+## Privacy
+
+Never store full transcripts, API keys, tokens, \`.env\` contents, auth files, cookies, bearer headers, or raw secret-bearing logs. Store summaries and evidence references only.
+`;
+const GROK_SKILL = CODEX_SKILL.replace("Codex, Grok", "Grok, Codex")
+    .replace("- `host`: `codex`", "- `host`: `grok`")
+    .replace("- `adapter`: `lazycodex`", "- `adapter`: `lfg`");
+const CODEX_AGENTS_BLOCK = `### OMO Memory lifecycle
+
+When the \`omo-memory\` MCP server is available, use it as the shared local memory ledger for Codex/Grok/OpenCode work.
+
+At the beginning of a non-trivial workspace session, call \`memory_bootstrap_session\` with:
+
+- \`host\`: \`codex\`
+- \`adapter\`: \`lazycodex\`
+- \`limit\`: \`5\`
+
+Read the returned \`recentEvents\` before making changes. Keep the returned \`sessionId\` for this session.
+
+During work, record concise durable state with \`memory_record_event\` using that \`sessionId\`: decisions, task state, QA evidence, important blockers, and handoff-worthy facts. Use \`memory_write_handoff\` only for explicit handoff summaries. Do not store full transcripts, API keys, tokens, \`.env\` contents, auth files, cookies, bearer headers, or raw secret-bearing logs.`;
+const GROK_AGENTS_BLOCK = CODEX_AGENTS_BLOCK.replace("- `host`: `codex`", "- `host`: `grok`").replace("- `adapter`: `lazycodex`", "- `adapter`: `lfg`");
+const GROK_HOOK_SCRIPT = `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const host = process.env["OMO_MEMORY_HOST"] ?? "grok";
+const adapter = process.env["OMO_MEMORY_ADAPTER"] ?? "lfg";
+const limit = process.env["OMO_MEMORY_LIMIT"] ?? "5";
+
+const result = spawnSync("npx", ["-y", "omo-memory", "session", "bootstrap", "--host", host, "--adapter", adapter, "--limit", limit], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+  timeout: 5000
+});
+
+if (result.status !== 0) {
+  process.stdout.write("OMO Memory: bootstrap unavailable; continue without blocking the session.\\n");
+  process.exit(0);
+}
+
+try {
+  const payload = JSON.parse(result.stdout);
+  const recentEvents = Array.isArray(payload.recentEvents) ? payload.recentEvents : [];
+  process.stdout.write(\`OMO Memory sessionId: \${payload.sessionId}\\n\`);
+  if (recentEvents.length === 0) {
+    process.stdout.write("OMO Memory recentEvents: none for this project.\\n");
+    process.exit(0);
+  }
+  process.stdout.write("OMO Memory recentEvents:\\n");
+  for (const event of recentEvents.slice(0, Number(limit))) {
+    process.stdout.write(\`- \${event.type}: \${event.summary}\\n\`);
+  }
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  process.stdout.write(\`OMO Memory: bootstrap returned unreadable output; \${detail}\\n\`);
+}
+`;
+const GROK_HOOKS_JSON = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"{{HOME}}/.grok/hooks/omo-memory-session.mjs\\"",
+            "timeout": 5,
+            "description": "omo-memory session bootstrap",
+            "statusMessage": "OMO Memory: loading recent session memory"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;
+const BLOCK_START = "<!-- omo-memory:start -->";
+const BLOCK_END = "<!-- omo-memory:end -->";
+export function installHooks(input) {
+    const home = process.env["OMO_MEMORY_INSTALL_HOME"] ?? homedir();
+    return { home, installed: targetsFor(input.host).map((target) => installTarget(target, home)) };
+}
+function targetsFor(host) {
+    if (host === "all")
+        return ["codex", "grok"];
+    return [host];
+}
+function installTarget(host, home) {
+    if (host === "codex")
+        return installCodex(home);
+    return installGrok(home);
+}
+function installCodex(home) {
+    const skillPath = join(home, ".codex", "skills", "omo-memory", "SKILL.md");
+    const agentsPath = join(home, ".codex", "AGENTS.md");
+    writeText(skillPath, CODEX_SKILL);
+    upsertAgentsBlock(agentsPath, CODEX_AGENTS_BLOCK);
+    return {
+        host: "codex",
+        files: [skillPath, agentsPath],
+        notes: ["Codex has no standalone user hook add command; this installs the passive lifecycle rule through global AGENTS.md."],
+    };
+}
+function installGrok(home) {
+    const skillPath = join(home, ".grok", "skills", "omo-memory", "SKILL.md");
+    const agentsPath = join(home, ".grok", "AGENTS.md");
+    const hookScriptPath = join(home, ".grok", "hooks", "omo-memory-session.mjs");
+    const hookJsonPath = join(home, ".grok", "hooks", "omo-memory-hooks.json");
+    writeText(skillPath, GROK_SKILL);
+    upsertAgentsBlock(agentsPath, GROK_AGENTS_BLOCK);
+    writeText(hookScriptPath, GROK_HOOK_SCRIPT);
+    chmodSync(hookScriptPath, 0o755);
+    writeText(hookJsonPath, GROK_HOOKS_JSON.replace("{{HOME}}", home));
+    return {
+        host: "grok",
+        files: [skillPath, agentsPath, hookScriptPath, hookJsonPath],
+        notes: ["Grok discovers ~/.grok/skills and ~/.grok/hooks; run grok inspect to verify discovery."],
+    };
+}
+function writeText(path, text) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+function upsertAgentsBlock(path, block) {
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const wrapped = `${BLOCK_START}\n${block}\n${BLOCK_END}`;
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start !== -1 && end > start) {
+        writeText(path, `${existing.slice(0, start)}${wrapped}${existing.slice(end + BLOCK_END.length)}`);
+        return;
+    }
+    const separator = existing.trim().length === 0 ? "" : "\n\n";
+    writeText(path, `${existing.trimEnd()}${separator}${wrapped}\n`);
+}

package/dist/mcp.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { bootstrapSession, exportMemory, initMemory, memoryPaths, purgeMemory, PurgeConfirmationError, recentEvents, recordEvent, resolveProjectContext, startSession, writeHandoff } from "./memory.js";
 export async function runMcpServer() {
-    const server = new McpServer({ name: "omo-memory", version: "0.1.1" });
+    const server = new McpServer({ name: "omo-memory", version: "0.1.2" });
     server.registerTool("memory_init", {
         title: "Initialize OMO Memory",
         description: "Create or migrate the local OMO memory SQLite database.",

package/docs/adapter-integration.md

@@ -27,6 +27,7 @@ After npm publish, adapters and users can invoke the packaged CLI directly:
 
 ```sh
 npx -y omo-memory init
+npx -y omo-memory hooks install --host all
 npx -y omo-memory session bootstrap --host codex --adapter lazycodex --limit 5
 npx -y omo-memory session start --host codex --adapter lazycodex
 npx -y omo-memory session start --host grok --adapter lfg
@@ -82,6 +83,22 @@ grok mcp add omo-memory -- npx -y omo-memory mcp
 
 Register the same MCP server in every host that needs memory access. Do not create separate Codex/Grok schemas or databases; host identity belongs in `memory_start_session` metadata.
 
+## Passive Hook Install
+
+Install host-side passive behavior with:
+
+```sh
+npx -y omo-memory hooks install --host all
+```
+
+Supported `--host` values:
+
+- `codex`: installs `~/.codex/skills/omo-memory/SKILL.md` and an idempotent OMO Memory block in `~/.codex/AGENTS.md`.
+- `grok`: installs `~/.grok/skills/omo-memory/SKILL.md`, an idempotent OMO Memory block in `~/.grok/AGENTS.md`, and `~/.grok/hooks/omo-memory-hooks.json` plus its SessionStart script.
+- `all`: installs both.
+
+The installer is idempotent and replaces only the marked `omo-memory` block in AGENTS files.
+
 ## Session Bootstrap Flow
 
 At the beginning of a Codex, OpenCode, or Grok adapter session, call `memory_bootstrap_session` instead of separately calling `memory_start_session` and `memory_recent_events`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omo-memory",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Host-neutral local SQLite memory and session ledger for OMO adapters, exposed through CLI and MCP.",
   "type": "module",
   "files": [