omo-memory 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# OMO Memory
+
+OMO Memory is a host-neutral local session/work memory for OMO adapters.
+
+It gives lazycodex, omo-on-opencode, lfg, and future OMO adapters a shared local SQLite ledger that can be accessed through both:
+
+- `omo-memory` CLI for install, inspection, search, and handoff workflows.
+- `omo-memory mcp` stdio server for coding tools and agents.
+
+## Product shape
+
+- Global local DB: `~/.omo/memory/state.sqlite`
+- Project namespacing: by git remote + project root hash
+- Privacy default: local-only, no network sync, no secrets by design
+- Intended adapters: Codex/lazycodex, OpenCode/OMO, GrokBuild/lfg
+
+## MVP commands
+
+```sh
+npm install
+npm run build
+node dist/cli.js init
+node dist/cli.js session start --host grok --adapter lfg
+node dist/cli.js event record --type decision --summary "Chose SQLite + MCP + CLI for OMO shared memory"
+node dist/cli.js recent
+node dist/cli.js mcp
+```
+
+## Install
+
+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 recent --limit 5
+npx -y omo-memory mcp
+```
+
+For local development before publish:
+
+```sh
+npm install
+npm run build
+npm link
+omo-memory init
+```
+
+## MCP registration
+
+Register the same MCP server in every host that should read/write the shared local memory DB.
+
+Codex:
+
+```sh
+codex mcp add omo-memory -- npx -y omo-memory mcp
+```
+
+Grok:
+
+```sh
+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.
+
+## MCP tools
+
+Initial stdio MCP tools:
+
+- `memory_init`
+- `memory_project_context`
+- `memory_start_session`
+- `memory_record_event`
+- `memory_recent_events`
+- `memory_write_handoff`
+- `memory_export`
+- `memory_purge`
+
+## Non-goals for MVP
+
+- No cloud sync.
+- No full transcript capture by default.
+- No secret storage.
+- No adapter-specific host lock-in.

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { 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;
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    if (command === "mcp") {
+        await runMcpServer();
+        return;
+    }
+    const result = runCommand(command, subcommand, rest);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+function runCommand(command, subcommand, rest) {
+    if (command === "init") {
+        return { ok: true, ...initMemory() };
+    }
+    if (command === "doctor") {
+        return { ok: true, ...doctorReport() };
+    }
+    if (command === "export") {
+        return { ok: true, ...exportMemory() };
+    }
+    if (command === "purge") {
+        const args = [subcommand, ...rest].filter((value) => value !== undefined);
+        return { ok: true, ...purgeMemory({ yes: args.includes("--yes") }) };
+    }
+    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 === "event" && subcommand === "record") {
+        const type = readFlag(rest, "--type") ?? fail("event record requires --type");
+        const summary = readFlag(rest, "--summary") ?? fail("event record requires --summary");
+        const payloadJson = readFlag(rest, "--payload-json");
+        const sessionId = readFlag(rest, "--session-id");
+        return { ok: true, ...recordEvent({ type, summary, ...(payloadJson === undefined ? {} : { payloadJson }), ...(sessionId === undefined ? {} : { sessionId }) }) };
+    }
+    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) };
+    }
+    if (command === "handoff" && subcommand === "write") {
+        const summary = readFlag(rest, "--summary");
+        const summaryFile = readFlag(rest, "--summary-file");
+        const sessionId = readFlag(rest, "--session-id");
+        const summaryMd = summary ?? (summaryFile === undefined ? undefined : readFileSync(summaryFile, "utf8")) ?? fail("handoff write requires --summary or --summary-file");
+        return { ok: true, ...writeHandoff(summaryMd, sessionId) };
+    }
+    fail(`unknown command: ${[command, subcommand].filter(Boolean).join(" ")}`);
+}
+function readFlag(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--"))
+        fail(`${name} requires a value`);
+    return value;
+}
+function parseHost(value) {
+    if (value === "codex" || value === "opencode" || value === "grok" || value === "unknown")
+        return value;
+    fail("--host must be one of codex, opencode, grok, unknown");
+}
+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`);
+}
+main(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/mcp.js

@@ -0,0 +1,76 @@
+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";
+export async function runMcpServer() {
+    const server = new McpServer({ name: "omo-memory", version: "0.1.0" });
+    server.registerTool("memory_init", {
+        title: "Initialize OMO Memory",
+        description: "Create or migrate the local OMO memory SQLite database.",
+        inputSchema: {},
+    }, async () => jsonResult(initMemory()));
+    server.registerTool("memory_project_context", {
+        title: "Get OMO Project Context",
+        description: "Return the current project identity used by OMO Memory.",
+        inputSchema: {},
+    }, async () => jsonResult({ paths: memoryPaths(), project: resolveProjectContext() }));
+    server.registerTool("memory_export", {
+        title: "Export OMO Memory",
+        description: "Export the current project's OMO memory sessions, events, and handoffs.",
+        inputSchema: {},
+    }, async () => jsonResult(exportMemory()));
+    server.registerTool("memory_purge", {
+        title: "Purge OMO Memory",
+        description: "Delete the current project's OMO memory sessions, events, handoffs, and project row.",
+        inputSchema: {
+            confirm: z.boolean(),
+        },
+    }, async ({ confirm }) => {
+        try {
+            return jsonResult(purgeMemory({ yes: confirm }));
+        }
+        catch (error) {
+            if (error instanceof PurgeConfirmationError) {
+                return jsonResult({ ok: false, error: "memory_purge requires confirm: true" });
+            }
+            throw error;
+        }
+    });
+    server.registerTool("memory_start_session", {
+        title: "Start OMO Session",
+        description: "Record a new OMO adapter session for the current project.",
+        inputSchema: {
+            host: z.enum(["codex", "opencode", "grok", "unknown"]),
+            adapter: z.string().min(1),
+        },
+    }, async ({ host, adapter }) => jsonResult(startSession({ host, adapter })));
+    server.registerTool("memory_record_event", {
+        title: "Record OMO Memory Event",
+        description: "Append a summarized event to the current project's OMO memory ledger.",
+        inputSchema: {
+            type: z.string().min(1),
+            summary: z.string().min(1),
+            payloadJson: z.string().optional(),
+            sessionId: z.string().optional(),
+        },
+    }, async ({ type, summary, payloadJson, sessionId }) => jsonResult(recordEvent({ type, summary, ...(payloadJson === undefined ? {} : { payloadJson }), ...(sessionId === undefined ? {} : { sessionId }) })));
+    server.registerTool("memory_recent_events", {
+        title: "List Recent OMO Memory Events",
+        description: "List recent events for the current project.",
+        inputSchema: {
+            limit: z.number().int().positive().max(100).default(10),
+        },
+    }, async ({ limit }) => jsonResult({ events: recentEvents(limit) }));
+    server.registerTool("memory_write_handoff", {
+        title: "Write OMO Handoff",
+        description: "Store a handoff summary for the current project.",
+        inputSchema: {
+            summaryMd: z.string().min(1),
+            sessionId: z.string().optional(),
+        },
+    }, async ({ summaryMd, sessionId }) => jsonResult(writeHandoff(summaryMd, sessionId)));
+    await server.connect(new StdioServerTransport());
+}
+function jsonResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}

package/dist/memory.js

@@ -0,0 +1,257 @@
+import Database from "better-sqlite3";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { redactSecrets, sanitizeGitRemote } from "./privacy.js";
+export class PurgeConfirmationError extends Error {
+    constructor() {
+        super("purge requires --yes");
+        this.name = "PurgeConfirmationError";
+    }
+}
+const SCHEMA_VERSION = 1;
+export function defaultDbPath() {
+    return process.env["OMO_MEMORY_DB"] ?? join(homedir(), ".omo", "memory", "state.sqlite");
+}
+export function memoryPaths() {
+    return { dbPath: defaultDbPath() };
+}
+export function openMemoryDb(dbPath = defaultDbPath()) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    return db;
+}
+export function migrate(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      repo_root TEXT NOT NULL,
+      git_remote TEXT,
+      created_at TEXT NOT NULL,
+      last_seen_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      host TEXT NOT NULL,
+      adapter TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      git_branch TEXT,
+      git_head TEXT,
+      FOREIGN KEY(project_id) REFERENCES projects(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT,
+      project_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      payload_json TEXT,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id),
+      FOREIGN KEY(session_id) REFERENCES sessions(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS handoffs (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      session_id TEXT,
+      summary_md TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id),
+      FOREIGN KEY(session_id) REFERENCES sessions(id)
+    );
+  `);
+    db.prepare("INSERT OR REPLACE INTO schema_meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+}
+export function initMemory(dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        return { dbPath, schemaVersion: SCHEMA_VERSION };
+    }
+    finally {
+        db.close();
+    }
+}
+export function doctorReport(dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        const schemaVersion = Number(db.prepare("SELECT value FROM schema_meta WHERE key = 'schema_version'").pluck().get());
+        const count = (table) => Number(db.prepare(`SELECT COUNT(*) FROM ${table}`).pluck().get());
+        return {
+            paths: { dbPath },
+            schemaVersion,
+            project,
+            counts: {
+                projects: count("projects"),
+                sessions: count("sessions"),
+                events: count("events"),
+                handoffs: count("handoffs"),
+            },
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function resolveProjectContext(cwd = process.cwd()) {
+    const repoRoot = gitValue(["rev-parse", "--show-toplevel"], cwd) ?? resolve(cwd);
+    const rawGitRemote = gitValue(["config", "--get", "remote.origin.url"], repoRoot);
+    const gitRemote = sanitizeGitRemote(rawGitRemote);
+    const gitBranch = gitValue(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
+    const gitHead = gitValue(["rev-parse", "HEAD"], repoRoot);
+    const id = createHash("sha256").update(`${rawGitRemote ?? ""}\n${repoRoot}`).digest("hex").slice(0, 24);
+    return { id, repoRoot, gitRemote, gitBranch, gitHead };
+}
+export function upsertProject(db, project) {
+    const now = new Date().toISOString();
+    db.prepare(`
+    INSERT INTO projects (id, repo_root, git_remote, created_at, last_seen_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      repo_root = excluded.repo_root,
+      git_remote = excluded.git_remote,
+      last_seen_at = excluded.last_seen_at
+  `).run(project.id, project.repoRoot, project.gitRemote, now, now);
+}
+export function startSession(input, dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        upsertProject(db, project);
+        const sessionId = randomUUID();
+        db.prepare(`
+      INSERT INTO sessions (id, project_id, host, adapter, started_at, git_branch, git_head)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(sessionId, project.id, input.host, input.adapter, new Date().toISOString(), project.gitBranch, project.gitHead);
+        return { sessionId, project };
+    }
+    finally {
+        db.close();
+    }
+}
+export function recordEvent(input, dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        upsertProject(db, project);
+        const eventId = randomUUID();
+        db.prepare(`
+      INSERT INTO events (id, session_id, project_id, type, summary, payload_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(eventId, input.sessionId ?? null, project.id, input.type, redactSecrets(input.summary), input.payloadJson === undefined ? null : redactSecrets(input.payloadJson), new Date().toISOString());
+        return { eventId, project };
+    }
+    finally {
+        db.close();
+    }
+}
+export function recentEvents(limit, dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        return db.prepare(`
+      SELECT id, type, summary, created_at AS createdAt, session_id AS sessionId
+      FROM events
+      WHERE project_id = ?
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(project.id, limit);
+    }
+    finally {
+        db.close();
+    }
+}
+export function writeHandoff(summaryMd, sessionId, dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        upsertProject(db, project);
+        const handoffId = randomUUID();
+        db.prepare(`
+      INSERT INTO handoffs (id, project_id, session_id, summary_md, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(handoffId, project.id, sessionId ?? null, redactSecrets(summaryMd), new Date().toISOString());
+        return { handoffId, project };
+    }
+    finally {
+        db.close();
+    }
+}
+export function exportMemory(dbPath = defaultDbPath()) {
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        const sessions = db.prepare(`
+      SELECT id, host, adapter, started_at AS startedAt, ended_at AS endedAt, git_branch AS gitBranch, git_head AS gitHead FROM sessions
+      WHERE project_id = ? ORDER BY started_at ASC, id ASC
+    `).all(project.id);
+        const events = db.prepare(`
+      SELECT id, session_id AS sessionId, type, summary, payload_json AS payloadJson, created_at AS createdAt FROM events
+      WHERE project_id = ? ORDER BY created_at ASC, id ASC
+    `).all(project.id);
+        const handoffs = db.prepare(`
+      SELECT id, session_id AS sessionId, summary_md AS summaryMd, created_at AS createdAt FROM handoffs
+      WHERE project_id = ? ORDER BY created_at ASC, id ASC
+    `).all(project.id);
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            exportedAt: new Date().toISOString(),
+            paths: { dbPath },
+            project,
+            sessions,
+            events,
+            handoffs,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+export function purgeMemory(input, dbPath = defaultDbPath()) {
+    if (!input.yes)
+        throw new PurgeConfirmationError();
+    const db = openMemoryDb(dbPath);
+    try {
+        migrate(db);
+        const project = resolveProjectContext();
+        const deleteProject = db.transaction(() => {
+            const events = db.prepare("DELETE FROM events WHERE project_id IN (SELECT id FROM projects WHERE id = ? OR repo_root = ?)").run(project.id, project.repoRoot).changes;
+            const handoffs = db.prepare("DELETE FROM handoffs WHERE project_id IN (SELECT id FROM projects WHERE id = ? OR repo_root = ?)").run(project.id, project.repoRoot).changes;
+            const sessions = db.prepare("DELETE FROM sessions WHERE project_id IN (SELECT id FROM projects WHERE id = ? OR repo_root = ?)").run(project.id, project.repoRoot).changes;
+            const projects = db.prepare("DELETE FROM projects WHERE id = ? OR repo_root = ?").run(project.id, project.repoRoot).changes;
+            return { events, handoffs, sessions, projects };
+        });
+        return { project, deleted: deleteProject() };
+    }
+    finally {
+        db.close();
+    }
+}
+function gitValue(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/privacy.js

@@ -0,0 +1,21 @@
+const SECRET_PATTERNS = [
+    /\bBearer\s+[A-Za-z0-9._-]+/gi,
+    /\bgithub_pat_[A-Za-z0-9_]+/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bxox[baprs]-[A-Za-z0-9-]+/g,
+    /\b(?:sk-|pk-)[A-Za-z0-9_-]{12,}\b/g,
+    /\b(password|passwd|secret|token|api[_-]?key|auth)(["']?\s*[:=]\s*["']?)[A-Za-z0-9_\-./+=]{8,}/gi,
+];
+export function redactSecrets(input) {
+    return SECRET_PATTERNS.reduce((value, pattern) => {
+        if (pattern.source.startsWith("\\b(password")) {
+            return value.replace(pattern, "$1$2[REDACTED]");
+        }
+        return value.replace(pattern, "[REDACTED]");
+    }, input);
+}
+export function sanitizeGitRemote(remote) {
+    if (remote === null)
+        return null;
+    return redactSecrets(remote).replace(/(https?:\/\/)([^/@\s]+)@/gi, "$1[REDACTED]@");
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/adapter-integration.md

@@ -0,0 +1,125 @@
+# Adapter Integration
+
+OMO Memory is the shared local work ledger for OMO adapters. It is host-neutral: lazycodex, omo-on-opencode, lfg, and future adapters all write summaries, decisions, QA evidence, task state, and handoffs to the same local SQLite database at `~/.omo/memory/state.sqlite` by default.
+
+No full transcript capture by default. Do not store API keys, tokens, `.env` contents, auth files, raw tool logs, auth headers, cookies, or any other secret-bearing material.
+
+## Contract
+
+- Use the shared CLI or MCP surface; do not create adapter-specific tables, schemas, or side databases.
+- Keep `host` and `adapter` as session metadata. Use `host` for `codex`, `opencode`, `grok`, or `unknown`; use `adapter` for names such as `lazycodex`, `omo-on-opencode`, or `lfg`.
+- Record concise events with a stable `type`, a human-readable `summary`, and optional redacted JSON metadata in `payloadJson`.
+- Store handoffs as summary markdown that another host can read without needing the originating transcript.
+- Treat CLI and MCP as two entrypoints to the same core functions and schema.
+- Use `OMO_MEMORY_DB` only when the caller explicitly chooses a different database path, such as an isolated smoke test.
+
+## Adapter Metadata
+
+| Adapter | host | adapter | Typical use |
+| --- | --- | --- | --- |
+| lazycodex | `codex` | `lazycodex` | Codex session memory, decisions, QA evidence, and handoffs. |
+| omo-on-opencode | `opencode` | `omo-on-opencode` | OpenCode-hosted OMO session memory. |
+| lfg | `grok` | `lfg` | Grok/GrokBuild-oriented harness memory. |
+
+## CLI Examples
+
+After npm publish, adapters and users can invoke the packaged CLI directly:
+
+```sh
+npx -y omo-memory init
+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
+```
+
+For a source checkout:
+
+```sh
+node dist/cli.js init
+node dist/cli.js session start --host codex --adapter lazycodex
+node dist/cli.js session start --host opencode --adapter omo-on-opencode
+node dist/cli.js session start --host grok --adapter lfg
+node dist/cli.js event record --type decision --summary "Use OMO Memory as the shared local ledger."
+node dist/cli.js event record --type qa_evidence --summary "CLI smoke passed for init/session/event/recent."
+node dist/cli.js handoff write --summary "Continue from recent decision and qa_evidence events."
+node dist/cli.js recent --limit 10
+node dist/cli.js export
+node dist/cli.js purge --yes
+```
+
+For isolated adapter tests:
+
+```sh
+OMO_MEMORY_DB="$(mktemp -u /tmp/omo-memory.XXXXXX.sqlite)" node dist/cli.js init
+```
+
+## MCP Tools
+
+Adapters that run through MCP should register the packaged command after npm publish:
+
+```sh
+npx -y omo-memory mcp
+```
+
+For a source checkout:
+
+```sh
+node dist/cli.js mcp
+```
+
+Codex registration:
+
+```sh
+codex mcp add omo-memory -- npx -y omo-memory mcp
+```
+
+Grok registration:
+
+```sh
+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.
+
+Use these tools:
+
+- `memory_init`
+- `memory_project_context`
+- `memory_start_session`
+- `memory_record_event`
+- `memory_recent_events`
+- `memory_write_handoff`
+- `memory_export`
+- `memory_purge`
+
+Example session start:
+
+```json
+{
+  "tool": "memory_start_session",
+  "arguments": {
+    "host": "codex",
+    "adapter": "lazycodex"
+  }
+}
+```
+
+Example QA evidence:
+
+```json
+{
+  "tool": "memory_record_event",
+  "arguments": {
+    "type": "qa_evidence",
+    "summary": "MCP tools/list included memory_export and memory_purge."
+  }
+}
+```
+
+## Privacy Review
+
+- No full transcript capture by default.
+- Do not read or record `.env`, auth files, tokens, cookies, API keys, bearer headers, or raw secret-bearing logs.
+- Store sanitized summaries and evidence references instead of full logs.
+- Host-specific values may appear only in small redacted metadata payloads and must not require schema branches.
+- Export and purge are explicit lifecycle commands; purge requires explicit confirmation.

package/docs/epic-omo-memory.md

@@ -0,0 +1,98 @@
+# Epic: OMO Memory — shared local session DB for OMO adapters
+
+## Goal
+
+Build a host-neutral local memory layer for OMO so lazycodex, omo-on-opencode, lfg, and future adapters can share task context across coding-tool sessions.
+
+The product ships as both:
+
+- CLI: install, inspect, search, export, purge, and handoff operations.
+- MCP server: standard stdio tools for agents and coding tools to read/write OMO memory.
+
+## Problem
+
+OMO currently runs through multiple host adapters. Each host session can know what happened in its own conversation, but session decisions, QA results, failure reasons, next actions, and agent verdicts are not available to the next host/tool session in a reliable local-first format.
+
+Codegraph solves code intelligence, not work/session memory. OMO needs a separate shared memory ledger.
+
+## Product direction
+
+- Global local DB: `~/.omo/memory/state.sqlite`
+- Project namespace: derive from git remote + repo root hash, with branch/head metadata
+- Local-first privacy: no cloud sync and no secret storage by default
+- Adapter-neutral schema: `host` and `adapter` are metadata, not separate products
+- Shared API: CLI and MCP use the same core DB layer
+
+## In scope
+
+- SQLite schema and migrations
+- CLI commands:
+  - `init`
+  - `session start`
+  - `event record`
+  - `recent`
+  - `handoff write`
+  - `doctor`
+- MCP stdio server with tools:
+  - `memory_init`
+  - `memory_project_context`
+  - `memory_record_event`
+  - `memory_recent_events`
+  - `memory_write_handoff`
+- Privacy guardrails:
+  - local-only default
+  - no API key/token/env capture
+  - explicit purge/export commands
+- Adapter integration notes for lazycodex, omo-on-opencode, and lfg
+
+## Out of scope
+
+- Cloud sync
+- Team sharing by default
+- Full transcript capture by default
+- Vector/embedding search in MVP
+- Replacing codegraph
+- Host-specific private APIs as required dependencies
+
+## Acceptance criteria
+
+### CLI
+
+- `omo-memory init` creates or migrates `~/.omo/memory/state.sqlite`.
+- `omo-memory session start --host grok --adapter lfg` records a session for the current project.
+- `omo-memory event record --type decision --summary "..."` appends a project/session event.
+- `omo-memory recent` lists recent project events.
+- `omo-memory handoff write --summary-file path.md` stores a handoff summary.
+
+### MCP
+
+- `omo-memory mcp` starts a stdio MCP server.
+- MCP tools can initialize the DB, read project context, record events, list recent events, and write handoffs.
+- MCP tool responses are structured JSON text.
+
+### Privacy and safety
+
+- No secrets are read from `.env`, auth files, or host config by default.
+- DB path can be overridden only by explicit `OMO_MEMORY_DB`.
+- `doctor` reports DB path, schema version, and project identity without leaking sensitive values.
+
+### QA evidence
+
+- `npm run typecheck`
+- `npm run build`
+- CLI smoke:
+  - `node dist/cli.js init`
+  - `node dist/cli.js session start --host grok --adapter lfg`
+  - `node dist/cli.js event record --type decision --summary "smoke"`
+  - `node dist/cli.js recent`
+- MCP smoke: start `node dist/cli.js mcp` and verify `tools/list` includes memory tools.
+
+## Follow-up issue breakdown
+
+1. Schema and migration core
+2. CLI command surface
+3. MCP stdio server
+4. Project identity and git metadata
+5. Privacy/redaction/purge/export
+6. Adapter integration docs for lazycodex, omo-on-opencode, and lfg
+7. QA harness for CLI and MCP smoke tests

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "omo-memory",
+  "version": "0.1.0",
+  "description": "Host-neutral local SQLite memory and session ledger for OMO adapters, exposed through CLI and MCP.",
+  "type": "module",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "bin": {
+    "omo-memory": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/islee23520/omo-memory.git"
+  },
+  "bugs": {
+    "url": "https://github.com/islee23520/omo-memory/issues"
+  },
+  "homepage": "https://github.com/islee23520/omo-memory#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli.js",
+    "prepack": "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",
+    "mcp": "node dist/cli.js mcp",
+    "issue:epic": "node scripts/create-epic-issue.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.11.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.10.1",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}