@xqli02/mneme 0.1.0

package/src/commands/init.mjs

@@ -0,0 +1,344 @@
+/**
+ * mneme init — Initialize three-layer memory architecture in the current directory.
+ *
+ * Steps:
+ *   1. Install dependencies (git, dolt, bd)
+ *   2. git init (if needed)
+ *   3. Scaffold .openclaw/facts/, .opencode/prompt.md, AGENTS.md, .gitignore
+ *   4. Start dolt server + bd init
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { has, run, runLive, log, color, getPlatform } from "../utils.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, "..", "templates");
+
+// ── Template scaffolding ────────────────────────────────────────────────────
+
+/**
+ * Map of destination path (relative to project root) -> template filename.
+ */
+const SCAFFOLD = {
+  "AGENTS.md": "AGENTS.md",
+  ".opencode/prompt.md": "opencode-prompt.md",
+  ".openclaw/facts/architecture.md": "facts-architecture.md",
+  ".openclaw/facts/invariants.md": "facts-invariants.md",
+  ".openclaw/facts/performance_rules.md": "facts-performance_rules.md",
+  ".openclaw/facts/pitfalls.md": "facts-pitfalls.md",
+  ".gitignore": "gitignore",
+};
+
+function scaffoldFiles() {
+  let created = 0;
+  let skipped = 0;
+
+  for (const [dest, templateName] of Object.entries(SCAFFOLD)) {
+    if (existsSync(dest)) {
+      log.ok(`${dest} ${color.dim("(already exists)")}`);
+      skipped++;
+      continue;
+    }
+
+    // Ensure parent directory exists
+    const dir = dirname(dest);
+    if (dir !== "." && !existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const templatePath = join(TEMPLATES_DIR, templateName);
+    const content = readFileSync(templatePath, "utf-8");
+
+    // For .gitignore, we append rather than overwrite if it already exists
+    writeFileSync(dest, content, "utf-8");
+    log.ok(`${dest} ${color.dim("(created)")}`);
+    created++;
+  }
+
+  // If .gitignore already existed, ensure our entries are in it
+  if (existsSync(".gitignore") && skipped > 0) {
+    const existing = readFileSync(".gitignore", "utf-8");
+    const templateContent = readFileSync(
+      join(TEMPLATES_DIR, "gitignore"),
+      "utf-8",
+    );
+
+    // Check if our marker entries are present
+    if (!existing.includes(".beads/dolt/")) {
+      appendFileSync(".gitignore", `\n# Added by mneme init\n${templateContent}`);
+      log.ok(`.gitignore ${color.dim("(mneme entries appended)")}`);
+    }
+  }
+
+  return { created, skipped };
+}
+
+// ── Dependency installation ─────────────────────────────────────────────────
+
+function installGit() {
+  if (has("git")) {
+    const ver = run("git --version") ?? "";
+    log.ok(`git ${color.dim(ver)}`);
+    return true;
+  }
+
+  log.info("Installing git...");
+  const { os } = getPlatform();
+
+  if (os === "darwin") {
+    runLive("xcode-select --install 2>/dev/null || true");
+  } else if (os === "linux") {
+    if (has("apt-get")) runLive("sudo apt-get update -qq && sudo apt-get install -y -qq git");
+    else if (has("dnf")) runLive("sudo dnf install -y git");
+    else if (has("yum")) runLive("sudo yum install -y git");
+    else if (has("pacman")) runLive("sudo pacman -S --noconfirm git");
+    else {
+      log.fail("Cannot auto-install git. Please install manually.");
+      return false;
+    }
+  } else {
+    log.fail(`Unsupported platform for auto-install: ${os}. Please install git manually.`);
+    return false;
+  }
+
+  return has("git");
+}
+
+function checkOpencode() {
+  if (has("opencode")) {
+    const ver = run("opencode --version 2>/dev/null | head -1") ?? "";
+    log.ok(`opencode ${color.dim(ver)}`);
+    return true;
+  }
+
+  log.warn(
+    "opencode not installed — mneme wraps opencode for the AI agent experience",
+  );
+  log.info("  Install: https://opencode.ai");
+  log.info('  After installing, run `mneme` to start or `mneme doctor` to verify');
+  return false;
+}
+
+function installDolt() {
+  if (has("dolt")) {
+    const ver = run("dolt version") ?? "";
+    log.ok(`dolt ${color.dim(ver)}`);
+    return true;
+  }
+
+  log.info("Installing dolt...");
+  const code = runLive(
+    "curl -fsSL https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash",
+    { timeout: 120_000 },
+  );
+
+  if (code === 0 && has("dolt")) {
+    log.ok("dolt installed");
+    return true;
+  }
+
+  log.fail("Failed to install dolt. See https://github.com/dolthub/dolt");
+  return false;
+}
+
+function installBd() {
+  if (has("bd")) {
+    const ver = run("bd version 2>/dev/null | head -1") ?? "";
+    log.ok(`bd ${color.dim(ver)}`);
+    return true;
+  }
+
+  log.info("Installing bd (beads)...");
+
+  // Strategy: brew > npm > GitHub release binary
+  if (has("brew")) {
+    log.info("  via Homebrew...");
+    if (runLive("brew install beads") === 0 && has("bd")) {
+      log.ok("bd installed via brew");
+      return true;
+    }
+  }
+
+  if (has("npm")) {
+    log.info("  via npm...");
+    if (runLive("npm install -g @beads/bd") === 0 && has("bd")) {
+      log.ok("bd installed via npm");
+      return true;
+    }
+  }
+
+  // Fallback: download binary from GitHub releases
+  log.info("  via GitHub release binary...");
+  const { os, arch } = getPlatform();
+  const osMap = { linux: "linux", darwin: "darwin", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+  const osStr = osMap[os];
+  const archStr = archMap[arch];
+
+  if (!osStr || !archStr) {
+    log.fail(`Unsupported platform: ${os}/${arch}. Please install bd manually.`);
+    return false;
+  }
+
+  // Fetch latest version tag
+  const latestJson = run(
+    'curl -fsSL https://api.github.com/repos/steveyegge/beads/releases/latest',
+    { timeout: 30_000 },
+  );
+  if (!latestJson) {
+    log.fail("Failed to fetch beads release info.");
+    return false;
+  }
+
+  let version;
+  try {
+    const data = JSON.parse(latestJson);
+    version = data.tag_name?.replace(/^v/, "");
+  } catch {
+    log.fail("Failed to parse beads release info.");
+    return false;
+  }
+
+  const ext = os === "win32" ? "zip" : "tar.gz";
+  const url = `https://github.com/steveyegge/beads/releases/download/v${version}/beads_${version}_${osStr}_${archStr}.${ext}`;
+
+  const dlCmd =
+    ext === "tar.gz"
+      ? `curl -fsSL "${url}" -o /tmp/beads.tar.gz && tar xzf /tmp/beads.tar.gz -C /tmp/ && install /tmp/bd /usr/local/bin/bd`
+      : `curl -fsSL "${url}" -o /tmp/beads.zip && unzip -o /tmp/beads.zip -d /tmp/beads && install /tmp/beads/bd.exe /usr/local/bin/bd`;
+
+  if (runLive(dlCmd, { timeout: 60_000 }) === 0 && has("bd")) {
+    log.ok("bd installed via GitHub release");
+    return true;
+  }
+
+  log.fail("Failed to install bd. See https://github.com/steveyegge/beads");
+  return false;
+}
+
+// ── Dolt server + bd init ───────────────────────────────────────────────────
+
+function ensureDoltServer() {
+  // Check if bd can already talk to dolt
+  const test = run("bd list --status=open 2>&1");
+  if (test !== null && !test.includes("unreachable") && !test.includes("connection refused")) {
+    log.ok("dolt server already running");
+    return true;
+  }
+
+  log.info("Starting dolt server...");
+  const dataDir = existsSync(".beads/dolt") ? ".beads/dolt" : `${process.env.HOME}/.dolt/databases`;
+
+  if (!existsSync(dataDir)) {
+    mkdirSync(dataDir, { recursive: true });
+  }
+
+  // Start in background
+  run(
+    `nohup dolt sql-server --host 127.0.0.1 --port 3307 --data-dir "${dataDir}" > /tmp/dolt-server.log 2>&1 &`,
+  );
+
+  // Wait for server to be ready (up to 10s)
+  for (let i = 0; i < 10; i++) {
+    run("sleep 1");
+    const check = run("bd list --status=open 2>&1");
+    if (check !== null && !check.includes("unreachable") && !check.includes("connection refused")) {
+      log.ok("dolt server started");
+      return true;
+    }
+  }
+
+  log.fail("dolt server failed to start. Check /tmp/dolt-server.log");
+  return false;
+}
+
+function initBeads() {
+  if (existsSync(".beads/config.yaml")) {
+    log.ok(`.beads/ ${color.dim("(already initialized)")}`);
+    return true;
+  }
+
+  log.info("Initializing beads...");
+  const code = runLive("bd init");
+  if (code === 0) {
+    log.ok("beads initialized");
+    return true;
+  }
+
+  log.fail("bd init failed");
+  return false;
+}
+
+function initGit() {
+  if (existsSync(".git")) {
+    log.ok(`.git/ ${color.dim("(already initialized)")}`);
+    return true;
+  }
+
+  log.info("Initializing git...");
+  if (runLive("git init -q") === 0) {
+    log.ok("git initialized");
+    return true;
+  }
+
+  log.fail("git init failed");
+  return false;
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function init() {
+  console.log(`
+${color.bold("mneme init")} — Three-layer memory architecture for AI agents
+`);
+
+  const { os, arch } = getPlatform();
+  log.info(`Platform: ${os} ${arch}`);
+
+  // Step 1: Dependencies
+  log.step(1, 4, "Install dependencies");
+  const gitOk = installGit();
+  if (!gitOk) {
+    log.fail("git is required. Aborting.");
+    process.exit(1);
+  }
+  checkOpencode();
+  const doltOk = installDolt();
+  const bdOk = installBd();
+
+  // Step 2: Git init
+  log.step(2, 4, "Initialize git");
+  initGit();
+
+  // Step 3: Scaffold files
+  log.step(3, 4, "Scaffold project structure");
+  const { created, skipped } = scaffoldFiles();
+  log.info(`  ${created} file(s) created, ${skipped} already existed`);
+
+  // Step 4: Dolt + Beads
+  log.step(4, 4, "Initialize beads");
+  if (doltOk && bdOk) {
+    const serverOk = ensureDoltServer();
+    if (serverOk) {
+      initBeads();
+    }
+  } else {
+    log.warn("Skipping beads init (dolt or bd not installed)");
+    log.warn("Run `mneme doctor` after installing dependencies to check status");
+  }
+
+  // Done
+  console.log(`
+${color.bold("===============================")}
+  ${color.green("mneme init complete")}
+${color.bold("===============================")}
+
+${color.bold("Next steps:")}
+  mneme                      # Start coding with AI agent
+  bd ready                   # Check available tasks
+  mneme doctor               # Verify everything is healthy
+`);
+}

package/src/commands/propose.mjs

@@ -0,0 +1,150 @@
+/**
+ * mneme propose — Propose a new fact for OpenClaw.
+ *
+ * Creates a pending proposal in `.openclaw/proposals/` that requires
+ * human review via `mneme review` before being written to facts.
+ *
+ * Usage:
+ *   mneme propose --file=architecture --content="..." --reason="..."
+ *   mneme propose --file=pitfalls --content="..." --reason="..."
+ *
+ * Options:
+ *   --file      Target facts file name (without .md extension)
+ *   --content   The fact content to append
+ *   --reason    Why this qualifies as a long-term fact
+ *   --action    append (default) | create
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { log, color } from "../utils.mjs";
+
+const PROPOSALS_DIR = ".openclaw/proposals";
+const FACTS_DIR = ".openclaw/facts";
+
+/**
+ * Parse --key=value and --key "value" style args.
+ */
+function parseArgs(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) continue;
+
+    const eqIdx = arg.indexOf("=");
+    if (eqIdx !== -1) {
+      // --key=value
+      const key = arg.slice(2, eqIdx);
+      result[key] = arg.slice(eqIdx + 1);
+    } else {
+      // --key value
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Generate a short proposal ID from timestamp + content hash.
+ */
+function generateId(content) {
+  const ts = Date.now().toString(36);
+  const hash = createHash("sha256")
+    .update(content + ts)
+    .digest("hex")
+    .slice(0, 4);
+  return `p-${ts.slice(-4)}${hash}`;
+}
+
+export async function propose(args) {
+  const opts = parseArgs(args);
+
+  // Validate required fields
+  if (!opts.file) {
+    console.error(`
+Usage: mneme propose --file=<facts-file> --content="<fact>" --reason="<why>"
+
+Options:
+  --file      Target facts file (e.g. architecture, invariants, pitfalls)
+  --content   The fact content to append
+  --reason    Why this qualifies as a long-term fact
+  --action    append (default) | create
+
+Example:
+  mneme propose --file=pitfalls --content="bd export does not exist in v0.56.1" --reason="Verified by testing; agents will hit this repeatedly"
+`);
+    process.exit(1);
+  }
+
+  if (!opts.content) {
+    log.fail('--content is required. What fact do you want to propose?');
+    process.exit(1);
+  }
+
+  if (!opts.reason) {
+    log.fail('--reason is required. Why is this a long-term fact?');
+    process.exit(1);
+  }
+
+  const action = opts.action || "append";
+  if (action !== "append" && action !== "create") {
+    log.fail(`Invalid action: ${action}. Use "append" or "create".`);
+    process.exit(1);
+  }
+
+  // Validate target file exists (for append) or doesn't exist (for create)
+  const targetFile = opts.file.endsWith(".md") ? opts.file : `${opts.file}.md`;
+  const targetPath = join(FACTS_DIR, targetFile);
+
+  if (action === "append" && !existsSync(targetPath)) {
+    log.fail(`Facts file not found: ${targetPath}`);
+    const available = existsSync(FACTS_DIR)
+      ? readdirSync(FACTS_DIR)
+          .filter((f) => f.endsWith(".md"))
+          .map((f) => f.replace(/\.md$/, ""))
+      : [];
+    if (available.length > 0) {
+      console.log(`Available files: ${available.join(", ")}`);
+    }
+    console.log('Use --action=create to propose a new facts file.');
+    process.exit(1);
+  }
+
+  // Create proposals directory
+  if (!existsSync(PROPOSALS_DIR)) {
+    mkdirSync(PROPOSALS_DIR, { recursive: true });
+  }
+
+  // Build proposal
+  const id = generateId(opts.content);
+  const proposal = {
+    id,
+    file: targetFile,
+    action,
+    content: opts.content,
+    reason: opts.reason,
+    status: "pending",
+    created: new Date().toISOString(),
+  };
+
+  // Write proposal file
+  const proposalPath = join(PROPOSALS_DIR, `${id}.json`);
+  writeFileSync(proposalPath, JSON.stringify(proposal, null, 2) + "\n", "utf-8");
+
+  log.ok(`Proposal created: ${color.bold(id)}`);
+  console.log(`  File:    ${targetFile}`);
+  console.log(`  Action:  ${action}`);
+  console.log(`  Content: ${opts.content.slice(0, 80)}${opts.content.length > 80 ? "..." : ""}`);
+  console.log(`  Reason:  ${opts.reason}`);
+  console.log();
+  console.log(color.dim(`Review with: mneme review`));
+  console.log(color.dim(`Approve:     mneme review ${id} --approve`));
+}

package/src/commands/review.mjs

@@ -0,0 +1,210 @@
+/**
+ * mneme review — Review, approve, or reject OpenClaw fact proposals.
+ *
+ * Usage:
+ *   mneme review                   List all pending proposals
+ *   mneme review <id> --approve    Approve and write to facts
+ *   mneme review <id> --reject     Reject proposal
+ *   mneme review <id>              Show proposal details
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  mkdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { log, color } from "../utils.mjs";
+
+const PROPOSALS_DIR = ".openclaw/proposals";
+const FACTS_DIR = ".openclaw/facts";
+
+/**
+ * Load all proposals, optionally filtered by status.
+ */
+function loadProposals(status) {
+  if (!existsSync(PROPOSALS_DIR)) return [];
+
+  return readdirSync(PROPOSALS_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        return JSON.parse(readFileSync(join(PROPOSALS_DIR, f), "utf-8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .filter((p) => !status || p.status === status)
+    .sort((a, b) => new Date(a.created) - new Date(b.created));
+}
+
+/**
+ * Load a single proposal by ID.
+ */
+function loadProposal(id) {
+  const filePath = join(PROPOSALS_DIR, `${id}.json`);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a proposal back to disk.
+ */
+function saveProposal(proposal) {
+  const filePath = join(PROPOSALS_DIR, `${proposal.id}.json`);
+  writeFileSync(filePath, JSON.stringify(proposal, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * List pending proposals.
+ */
+function listPending() {
+  const pending = loadProposals("pending");
+
+  if (pending.length === 0) {
+    log.ok("No pending proposals");
+    return;
+  }
+
+  console.log(
+    `\n${color.bold("Pending proposals")} (${pending.length})\n`,
+  );
+
+  for (const p of pending) {
+    const date = p.created.split("T")[0];
+    console.log(
+      `  ${color.yellow("○")} ${color.bold(p.id)}  → ${p.file} (${p.action})  ${color.dim(date)}`,
+    );
+    console.log(`    ${p.content.slice(0, 100)}${p.content.length > 100 ? "..." : ""}`);
+    console.log(`    ${color.dim(`Reason: ${p.reason}`)}`);
+    console.log();
+  }
+
+  console.log(color.dim("  Approve: mneme review <id> --approve"));
+  console.log(color.dim("  Reject:  mneme review <id> --reject"));
+  console.log(color.dim("  Detail:  mneme review <id>"));
+}
+
+/**
+ * Show full detail of a proposal.
+ */
+function showProposal(proposal) {
+  const statusColor =
+    proposal.status === "pending"
+      ? color.yellow
+      : proposal.status === "approved"
+        ? color.green
+        : color.red;
+
+  console.log(`
+${color.bold("Proposal")} ${color.bold(proposal.id)}  [${statusColor(proposal.status.toUpperCase())}]
+
+  Target:  ${proposal.file} (${proposal.action})
+  Created: ${proposal.created}
+
+${color.bold("Content:")}
+${proposal.content}
+
+${color.bold("Reason:")}
+  ${proposal.reason}
+`);
+}
+
+/**
+ * Approve a proposal: append/create fact content.
+ */
+function approveProposal(proposal) {
+  const targetPath = join(FACTS_DIR, proposal.file);
+
+  if (proposal.action === "append") {
+    if (!existsSync(targetPath)) {
+      log.fail(`Target file not found: ${targetPath}`);
+      process.exit(1);
+    }
+    // Append with a blank line separator
+    appendFileSync(targetPath, `\n${proposal.content}\n`, "utf-8");
+    log.ok(`Appended to ${proposal.file}`);
+  } else if (proposal.action === "create") {
+    if (existsSync(targetPath)) {
+      log.warn(`File already exists: ${targetPath} — appending instead`);
+      appendFileSync(targetPath, `\n${proposal.content}\n`, "utf-8");
+    } else {
+      const dir = join(FACTS_DIR);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      writeFileSync(targetPath, proposal.content + "\n", "utf-8");
+      log.ok(`Created ${proposal.file}`);
+    }
+  }
+
+  // Update proposal status
+  proposal.status = "approved";
+  proposal.reviewed = new Date().toISOString();
+  saveProposal(proposal);
+
+  log.ok(`Proposal ${color.bold(proposal.id)} approved`);
+}
+
+/**
+ * Reject a proposal.
+ */
+function rejectProposal(proposal) {
+  proposal.status = "rejected";
+  proposal.reviewed = new Date().toISOString();
+  saveProposal(proposal);
+
+  log.ok(`Proposal ${color.bold(proposal.id)} rejected`);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function review(args) {
+  const doApprove = args.includes("--approve");
+  const doReject = args.includes("--reject");
+  const id = args.find((a) => !a.startsWith("-"));
+
+  // No ID → list pending
+  if (!id) {
+    listPending();
+    return;
+  }
+
+  // Load proposal
+  const proposal = loadProposal(id);
+  if (!proposal) {
+    log.fail(`Proposal not found: ${id}`);
+    const pending = loadProposals("pending");
+    if (pending.length > 0) {
+      console.log(
+        `\nPending: ${pending.map((p) => p.id).join(", ")}`,
+      );
+    }
+    process.exit(1);
+  }
+
+  // Action: approve or reject
+  if (doApprove) {
+    if (proposal.status !== "pending") {
+      log.warn(`Proposal already ${proposal.status}`);
+      process.exit(1);
+    }
+    showProposal(proposal);
+    approveProposal(proposal);
+  } else if (doReject) {
+    if (proposal.status !== "pending") {
+      log.warn(`Proposal already ${proposal.status}`);
+      process.exit(1);
+    }
+    rejectProposal(proposal);
+  } else {
+    // Just show detail
+    showProposal(proposal);
+  }
+}