omo-memory 0.1.1 → 0.1.3

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/hookTemplates.js

@@ -0,0 +1,151 @@
+export const CODEX_MARKETPLACE = "islee23520";
+export const CODEX_PLUGIN = "omo-memory";
+export 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.
+`;
+export const GROK_SKILL = CODEX_SKILL.replace("Codex, Grok", "Grok, Codex")
+    .replace("- `host`: `codex`", "- `host`: `grok`")
+    .replace("- `adapter`: `lazycodex`", "- `adapter`: `lfg`");
+export 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.`;
+export const GROK_AGENTS_BLOCK = CODEX_AGENTS_BLOCK.replace("- `host`: `codex`", "- `host`: `grok`").replace("- `adapter`: `lazycodex`", "- `adapter`: `lfg`");
+export const SESSION_BOOTSTRAP_SCRIPT = `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const host = process.env["OMO_MEMORY_HOST"] ?? "codex";
+const adapter = process.env["OMO_MEMORY_ADAPTER"] ?? "lazycodex";
+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\`);
+}
+`;
+export const GROK_HOOK_SCRIPT = SESSION_BOOTSTRAP_SCRIPT.replace('?? "codex"', '?? "grok"').replace('?? "lazycodex"', '?? "lfg"');
+export const CODEX_PLUGIN_JSON = `{
+  "name": "omo-memory",
+  "version": "0.1.3",
+  "description": "Session-start OMO Memory bootstrap hook for Codex.",
+  "author": "islee23520",
+  "homepage": "https://github.com/islee23520/omo-memory",
+  "repository": "https://github.com/islee23520/omo-memory",
+  "license": "MIT",
+  "keywords": ["codex", "hooks", "memory", "mcp"],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "OMO Memory",
+    "shortDescription": "Bootstraps local shared memory at Codex session start.",
+    "longDescription": "OMO Memory records concise local session state and loads recent project memory through the omo-memory CLI and MCP server.",
+    "developerName": "islee23520",
+    "category": "Developer Tools",
+    "capabilities": ["Hooks", "MCP Tools", "Workflow"],
+    "websiteURL": "https://github.com/islee23520/omo-memory",
+    "privacyPolicyURL": "https://github.com/islee23520/omo-memory#privacy",
+    "termsOfServiceURL": "https://github.com/islee23520/omo-memory#license",
+    "defaultPrompt": [
+      "Use OMO Memory to load recent project memory before non-trivial workspace work.",
+      "Record durable decisions, task state, QA evidence, blockers, and handoffs without storing secrets or full transcripts."
+    ],
+    "brandColor": "#0F766E",
+    "screenshots": []
+  },
+  "capabilities": []
+}
+`;
+export const CODEX_HOOKS_JSON = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"\${PLUGIN_ROOT}/scripts/omo-memory-session.mjs\\"",
+            "timeout": 5,
+            "description": "omo-memory session bootstrap",
+            "statusMessage": "OMO Memory: loading recent session memory"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;
+export 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"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;

package/dist/hooks.js

@@ -0,0 +1,156 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CODEX_AGENTS_BLOCK, CODEX_HOOKS_JSON, CODEX_MARKETPLACE, CODEX_PLUGIN, CODEX_PLUGIN_JSON, CODEX_SKILL, GROK_AGENTS_BLOCK, GROK_HOOK_SCRIPT, GROK_HOOKS_JSON, GROK_SKILL, SESSION_BOOTSTRAP_SCRIPT, } from "./hookTemplates.js";
+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");
+    const marketplacePath = join(home, ".codex", "local-marketplaces", CODEX_MARKETPLACE);
+    const marketplaceJsonPath = join(marketplacePath, "marketplace.json");
+    const agentsMarketplaceJsonPath = join(marketplacePath, ".agents", "plugins", "marketplace.json");
+    const pluginRoot = join(marketplacePath, "plugins", CODEX_PLUGIN);
+    const pluginJsonPath = join(pluginRoot, ".codex-plugin", "plugin.json");
+    const pluginSkillPath = join(pluginRoot, "skills", "omo-memory", "SKILL.md");
+    const hookJsonPath = join(pluginRoot, "hooks", "hooks.json");
+    const hookScriptPath = join(pluginRoot, "scripts", "omo-memory-session.mjs");
+    const configPath = join(home, ".codex", "config.toml");
+    writeText(skillPath, CODEX_SKILL);
+    upsertAgentsBlock(agentsPath, CODEX_AGENTS_BLOCK);
+    writeText(pluginJsonPath, CODEX_PLUGIN_JSON);
+    writeText(pluginSkillPath, CODEX_SKILL);
+    writeText(hookJsonPath, CODEX_HOOKS_JSON);
+    writeText(hookScriptPath, SESSION_BOOTSTRAP_SCRIPT);
+    chmodSync(hookScriptPath, 0o755);
+    upsertMarketplace(marketplaceJsonPath, { withInterface: false });
+    upsertMarketplace(agentsMarketplaceJsonPath, { withInterface: true });
+    upsertCodexConfig(configPath, marketplacePath);
+    return {
+        host: "codex",
+        files: [skillPath, agentsPath, pluginJsonPath, pluginSkillPath, hookJsonPath, hookScriptPath, marketplaceJsonPath, agentsMarketplaceJsonPath, configPath],
+        notes: [
+            "Codex MCP still needs `codex mcp add omo-memory -- npx -y omo-memory mcp` if it is not already present.",
+            "Codex plugin hooks are installed through the local islee23520 marketplace and enabled in ~/.codex/config.toml.",
+            "Codex may ask to trust the new hook command on first execution unless hook trust has already been granted.",
+        ],
+    };
+}
+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(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+function upsertMarketplace(path, input) {
+    const marketplace = readMarketplace(path, input.withInterface);
+    const plugins = marketplace.plugins.filter((plugin) => plugin.name !== CODEX_PLUGIN);
+    const omoMemory = marketplacePlugin(input.withInterface);
+    const next = { ...marketplace, plugins: [...plugins, omoMemory] };
+    writeText(path, `${JSON.stringify(next, null, 2)}\n`);
+}
+function readMarketplace(path, withInterface) {
+    if (!existsSync(path))
+        return defaultMarketplace(withInterface);
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isMarketplace(parsed))
+        return defaultMarketplace(withInterface);
+    return parsed;
+}
+function defaultMarketplace(withInterface) {
+    return {
+        name: CODEX_MARKETPLACE,
+        ...(withInterface ? { interface: { displayName: CODEX_MARKETPLACE } } : {}),
+        plugins: [],
+    };
+}
+function marketplacePlugin(withPolicy) {
+    return {
+        name: CODEX_PLUGIN,
+        source: { source: "local", path: "./plugins/omo-memory" },
+        ...(withPolicy ? { policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: "Developer Tools" } : {}),
+    };
+}
+function isMarketplace(value) {
+    if (!isRecord(value) || value["name"] !== CODEX_MARKETPLACE || !Array.isArray(value["plugins"]))
+        return false;
+    return value["plugins"].every(isMarketplacePlugin);
+}
+function isMarketplacePlugin(value) {
+    if (!isRecord(value) || typeof value["name"] !== "string" || !isRecord(value["source"]))
+        return false;
+    const source = value["source"];
+    return source["source"] === "local" && typeof source["path"] === "string";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function upsertCodexConfig(path, marketplacePath) {
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const withHooks = ensureTomlKey(existing, "[features]", "plugin_hooks = true");
+    const withMarketplace = ensureTomlTable(withHooks, `[marketplaces.${CODEX_MARKETPLACE}]`, `source_type = "local"\nsource = "${escapeTomlString(marketplacePath)}"`);
+    writeText(path, ensureTomlTable(withMarketplace, `[plugins."${CODEX_PLUGIN}@${CODEX_MARKETPLACE}"]`, "enabled = true"));
+}
+function ensureTomlKey(text, table, keyValue) {
+    if (text.includes(keyValue))
+        return text;
+    if (!text.includes(table))
+        return appendTomlTable(text, table, keyValue);
+    const start = text.indexOf(table);
+    const nextTable = text.indexOf("\n[", start + table.length);
+    const insertAt = nextTable === -1 ? text.length : nextTable;
+    return `${text.slice(0, insertAt).trimEnd()}\n${keyValue}\n${text.slice(insertAt).trimStart()}`;
+}
+function ensureTomlTable(text, table, body) {
+    if (text.includes(table))
+        return text;
+    return appendTomlTable(text, table, body);
+}
+function appendTomlTable(text, table, body) {
+    const prefix = text.trimEnd();
+    const separator = prefix.length === 0 ? "" : "\n\n";
+    return `${prefix}${separator}${table}\n${body}\n`;
+}
+function escapeTomlString(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+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.3",
   "description": "Host-neutral local SQLite memory and session ledger for OMO adapters, exposed through CLI and MCP.",
   "type": "module",
   "files": [