omo-memory 0.1.0 → 0.1.2

package/README.md

@@ -32,6 +32,8 @@ 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
 ```
@@ -63,6 +65,51 @@ 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:
+
+```json
+{
+  "tool": "memory_bootstrap_session",
+  "arguments": {
+    "host": "codex",
+    "adapter": "lazycodex",
+    "limit": 5
+  }
+}
+```
+
+The response contains a new `sessionId` plus `recentEvents` for the current project. Reuse that `sessionId` when recording follow-up events:
+
+```json
+{
+  "tool": "memory_record_event",
+  "arguments": {
+    "type": "decision",
+    "summary": "Chose the npm MCP package as the shared local memory surface.",
+    "sessionId": "<sessionId>"
+  }
+}
+```
+
+This is local routing, not transcript scraping. OMO Memory does not automatically read full Codex or Grok transcripts; the host or adapter must call these MCP tools.
+
 ## MCP tools
 
 Initial stdio MCP tools:
@@ -70,6 +117,7 @@ Initial stdio MCP tools:
 - `memory_init`
 - `memory_project_context`
 - `memory_start_session`
+- `memory_bootstrap_session`
 - `memory_record_event`
 - `memory_recent_events`
 - `memory_write_handoff`

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { doctorReport, exportMemory, initMemory, purgeMemory, recentEvents, recordEvent, startSession, writeHandoff } from "./memory.js";
+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) {
     const [command, subcommand, ...rest] = argv;
@@ -29,11 +30,19 @@ 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";
         return { ok: true, ...startSession({ host, adapter }) };
     }
+    if (command === "session" && subcommand === "bootstrap") {
+        const host = parseHost(readFlag(rest, "--host") ?? "unknown");
+        const adapter = readFlag(rest, "--adapter") ?? "unknown";
+        return { ok: true, ...bootstrapSession({ host, adapter, limit: readPositiveIntFlag(rest, "--limit", 5) }) };
+    }
     if (command === "event" && subcommand === "record") {
         const type = readFlag(rest, "--type") ?? fail("event record requires --type");
         const summary = readFlag(rest, "--summary") ?? fail("event record requires --summary");
@@ -43,10 +52,7 @@ function runCommand(command, subcommand, rest) {
     }
     if (command === "recent") {
         const limitRaw = readFlag([subcommand, ...rest].filter((value) => value !== undefined), "--limit");
-        const limit = limitRaw === undefined ? 10 : Number(limitRaw);
-        if (!Number.isInteger(limit) || limit <= 0)
-            fail("recent --limit must be a positive integer");
-        return { ok: true, events: recentEvents(limit) };
+        return { ok: true, events: recentEvents(parsePositiveInt(limitRaw, "recent --limit")) };
     }
     if (command === "handoff" && subcommand === "write") {
         const summary = readFlag(rest, "--summary");
@@ -71,11 +77,25 @@ 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);
+}
+function parsePositiveInt(value, label) {
+    const limit = value === undefined ? 10 : Number(value);
+    if (!Number.isInteger(limit) || limit <= 0)
+        fail(`${label} must be a positive integer`);
+    return limit;
+}
 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 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

@@ -1,9 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { exportMemory, initMemory, memoryPaths, purgeMemory, PurgeConfirmationError, recentEvents, recordEvent, resolveProjectContext, startSession, writeHandoff } from "./memory.js";
+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.0" });
+    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.",
@@ -44,6 +44,15 @@ export async function runMcpServer() {
             adapter: z.string().min(1),
         },
     }, async ({ host, adapter }) => jsonResult(startSession({ host, adapter })));
+    server.registerTool("memory_bootstrap_session", {
+        title: "Bootstrap OMO Session",
+        description: "Start a host adapter session and return recent project memory in one call. Call this at the beginning of each Codex, OpenCode, or Grok session.",
+        inputSchema: {
+            host: z.enum(["codex", "opencode", "grok", "unknown"]),
+            adapter: z.string().min(1),
+            limit: z.number().int().positive().max(100).default(5),
+        },
+    }, async ({ host, adapter, limit }) => jsonResult(bootstrapSession({ host, adapter, limit })));
     server.registerTool("memory_record_event", {
         title: "Record OMO Memory Event",
         description: "Append a summarized event to the current project's OMO memory ledger.",

package/dist/memory.js

@@ -145,6 +145,10 @@ export function startSession(input, dbPath = defaultDbPath()) {
         db.close();
     }
 }
+export function bootstrapSession(input, dbPath = defaultDbPath()) {
+    const session = startSession({ host: input.host, adapter: input.adapter }, dbPath);
+    return { ...session, recentEvents: recentEvents(input.limit, dbPath) };
+}
 export function recordEvent(input, dbPath = defaultDbPath()) {
     const db = openMemoryDb(dbPath);
     try {

package/docs/adapter-integration.md

@@ -27,6 +27,8 @@ 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
 npx -y omo-memory recent --limit 10
@@ -81,10 +83,63 @@ 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`.
+
+```json
+{
+  "tool": "memory_bootstrap_session",
+  "arguments": {
+    "host": "grok",
+    "adapter": "lfg",
+    "limit": 5
+  }
+}
+```
+
+The tool returns:
+
+- `sessionId`: the new session row for subsequent event/handoff writes.
+- `project`: the current git/project namespace.
+- `recentEvents`: recent events from the same project namespace.
+
+During the session, write concise task state and evidence with the returned `sessionId`:
+
+```json
+{
+  "tool": "memory_record_event",
+  "arguments": {
+    "type": "qa_evidence",
+    "summary": "npm-published MCP exposed memory_bootstrap_session and memory_recent_events.",
+    "sessionId": "<sessionId>"
+  }
+}
+```
+
+This package is the local MCP-to-SQLite router. It does not scrape host transcripts or centralize cloud state. Hosts and adapters must call the MCP tools at their own lifecycle points.
+
 Use these tools:
 
 - `memory_init`
 - `memory_project_context`
+- `memory_bootstrap_session`
 - `memory_start_session`
 - `memory_record_event`
 - `memory_recent_events`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omo-memory",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Host-neutral local SQLite memory and session ledger for OMO adapters, exposed through CLI and MCP.",
   "type": "module",
   "files": [
@@ -27,6 +27,7 @@
     "typecheck": "tsc --noEmit",
     "start": "node dist/cli.js",
     "prepack": "npm run build",
+    "presmoke": "npm run build",
     "smoke": "npm run smoke:cli && npm run smoke:mcp",
     "smoke:cli": "node scripts/smoke-cli.mjs",
     "smoke:mcp": "node scripts/smoke-mcp.mjs",