@xqli02/mneme 0.1.0

package/src/commands/compact.mjs

@@ -0,0 +1,137 @@
+/**
+ * mneme compact — Pre-compaction persistence checklist.
+ *
+ * Checks that state is properly persisted before context compaction:
+ *   - In-progress beads have recent notes
+ *   - No uncommitted changes
+ *   - No unpushed commits
+ *   - Suggests actions if anything is out of sync
+ */
+
+import { existsSync } from "node:fs";
+import { run, log, color } from "../utils.mjs";
+
+export async function compact() {
+  console.log(
+    `\n${color.bold("mneme compact")} — pre-compaction persistence check\n`,
+  );
+
+  let warnings = 0;
+  let passes = 0;
+
+  // Check 1: Uncommitted changes
+  console.log(color.bold("Git state:"));
+  const status = run("git status --porcelain 2>&1");
+  if (status === null) {
+    log.warn("Not a git repository");
+    warnings++;
+  } else if (status === "") {
+    log.ok("Working tree clean");
+    passes++;
+  } else {
+    const lines = status.split("\n").filter(Boolean);
+    log.warn(
+      `${lines.length} uncommitted change(s) — commit before compaction`,
+    );
+    for (const line of lines.slice(0, 5)) {
+      console.log(`    ${line}`);
+    }
+    if (lines.length > 5) {
+      console.log(color.dim(`    ... and ${lines.length - 5} more`));
+    }
+    warnings++;
+  }
+
+  // Check 2: Unpushed commits
+  const unpushed = run("git log @{u}..HEAD --oneline 2>&1");
+  if (unpushed && !unpushed.includes("no upstream") && unpushed !== "") {
+    const count = unpushed.split("\n").filter(Boolean).length;
+    log.warn(`${count} unpushed commit(s) — push before compaction`);
+    warnings++;
+  } else if (unpushed === "") {
+    log.ok("All commits pushed");
+    passes++;
+  }
+
+  // Check 3: In-progress beads
+  console.log(`\n${color.bold("Beads state:")}`);
+  if (!existsSync(".beads/config.yaml")) {
+    log.warn("Beads not initialized");
+    warnings++;
+  } else {
+    const ipOut = run("bd list --status=in_progress 2>&1");
+    if (!ipOut || ipOut.includes("No issues")) {
+      log.ok("No in-progress beads (nothing to persist)");
+      passes++;
+    } else {
+      const beadLines = ipOut
+        .split("\n")
+        .filter((l) => /\b(mneme|bd)-[a-z0-9]+\b/.test(l) || /^[○◐●]/.test(l.trim()));
+
+      if (beadLines.length === 0) {
+        log.ok("No in-progress beads");
+        passes++;
+      } else {
+        log.warn(
+          `${beadLines.length} in-progress bead(s) — update notes with current progress:`,
+        );
+        for (const line of beadLines) {
+          console.log(`    ${line.trim()}`);
+        }
+        console.log(
+          color.dim(
+            '\n    Use: bd update <id> --notes="current progress..."',
+          ),
+        );
+        warnings++;
+      }
+    }
+
+    // Check for open beads that might need status update
+    const openOut = run("bd list --status=open 2>&1");
+    if (openOut && !openOut.includes("No issues")) {
+      const openLines = openOut
+        .split("\n")
+        .filter((l) => /\b(mneme|bd)-[a-z0-9]+\b/.test(l) || /^[○◐●]/.test(l.trim()));
+      if (openLines.length > 0) {
+        log.info(
+          `${openLines.length} open bead(s) — review if any should be closed or updated`,
+        );
+      }
+    }
+  }
+
+  // Check 4: OpenClaw facts
+  console.log(`\n${color.bold("OpenClaw state:")}`);
+  if (existsSync(".openclaw/facts/")) {
+    log.ok("Facts directory exists");
+    log.info(
+      "Review: any new long-term facts discovered this session? Propose with human confirmation.",
+    );
+    passes++;
+  } else {
+    log.warn("No .openclaw/facts/ directory");
+    warnings++;
+  }
+
+  // Summary
+  console.log();
+  if (warnings === 0) {
+    log.ok(
+      color.bold(
+        "All clear — safe to compact. State is fully persisted.",
+      ),
+    );
+  } else {
+    log.warn(
+      color.bold(
+        `${warnings} warning(s) — persist state before allowing compaction.`,
+      ),
+    );
+    console.log(
+      color.dim(
+        "\n  Remember: you can lose reasoning, but never lose state or facts.",
+      ),
+    );
+  }
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,91 @@
+/**
+ * mneme doctor — Check dependencies and project health.
+ */
+
+import { has, run, log, color } from "../utils.mjs";
+import { existsSync } from "node:fs";
+import { readdirSync } from "node:fs";
+
+/**
+ * Check a single dependency. Returns true if OK.
+ */
+function checkCmd(name, versionCmd) {
+  if (!has(name)) {
+    log.fail(`${name} not installed`);
+    return false;
+  }
+  const ver = run(versionCmd) ?? "unknown";
+  log.ok(`${name} ${color.dim(ver)}`);
+  return true;
+}
+
+/**
+ * Check if dolt server is reachable by bd.
+ */
+function checkDoltServer() {
+  if (!has("bd")) return false;
+  const result = run("bd list --status=open 2>&1");
+  if (result !== null && !result.includes("unreachable") && !result.includes("Error")) {
+    log.ok("dolt server reachable");
+    return true;
+  }
+  log.warn("dolt server not running or not reachable");
+  return false;
+}
+
+/**
+ * Check project structure.
+ */
+function checkStructure() {
+  const checks = [
+    [".git/", "git repository"],
+    [".openclaw/facts/", "OpenClaw facts directory"],
+    [".opencode/prompt.md", "OpenCode session prompt"],
+    ["AGENTS.md", "Agent behavior rules"],
+    [".beads/", "Beads data directory"],
+  ];
+
+  let allOk = true;
+  for (const [path, label] of checks) {
+    if (existsSync(path)) {
+      log.ok(label);
+    } else {
+      log.warn(`${label} ${color.dim(`(${path} not found)`)}`);
+      allOk = false;
+    }
+  }
+
+  // Check facts files
+  if (existsSync(".openclaw/facts/")) {
+    const files = readdirSync(".openclaw/facts/").filter((f) =>
+      f.endsWith(".md"),
+    );
+    log.info(`  ${files.length} facts file(s): ${files.join(", ")}`);
+  }
+
+  return allOk;
+}
+
+export async function doctor() {
+  console.log(`\n${color.bold("mneme doctor")} — checking health\n`);
+
+  console.log(color.bold("Dependencies:"));
+  const gitOk = checkCmd("git", "git --version");
+  const opencodeOk = checkCmd("opencode", "opencode --version 2>/dev/null | head -1");
+  const doltOk = checkCmd("dolt", "dolt version");
+  const bdOk = checkCmd("bd", "bd version 2>/dev/null | head -1");
+  const serverOk = checkDoltServer();
+
+  console.log(`\n${color.bold("Project structure:")}`);
+  const structOk = checkStructure();
+
+  console.log();
+  if (gitOk && opencodeOk && doltOk && bdOk && serverOk && structOk) {
+    log.ok(color.bold("All checks passed"));
+  } else {
+    log.warn(
+      color.bold("Some checks failed. Run `mneme init` to fix."),
+    );
+    process.exit(1);
+  }
+}

package/src/commands/facts.mjs

@@ -0,0 +1,148 @@
+/**
+ * mneme facts — View and manage OpenClaw facts.
+ *
+ * Usage:
+ *   mneme facts            List all facts files with summaries
+ *   mneme facts <name>     Show contents of a specific facts file
+ *   mneme facts --stats    Show statistics (line counts, budget usage)
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { log, color } from "../utils.mjs";
+
+const FACTS_DIR = ".openclaw/facts";
+const PROPOSALS_DIR = ".openclaw/proposals";
+const LINE_BUDGET_PER_FILE = 200;
+const LINE_BUDGET_TOTAL = 800;
+
+/**
+ * List all facts files with line counts.
+ */
+function listFacts(showStats) {
+  if (!existsSync(FACTS_DIR)) {
+    log.fail(
+      ".openclaw/facts/ not found — run `mneme init` to create it.",
+    );
+    process.exit(1);
+  }
+
+  const files = readdirSync(FACTS_DIR)
+    .filter((f) => f.endsWith(".md"))
+    .sort();
+
+  if (files.length === 0) {
+    log.warn("No facts files found. Create them with `mneme init`.");
+    return;
+  }
+
+  let totalLines = 0;
+
+  console.log(color.bold("\nOpenClaw Facts"));
+  console.log(color.dim("──────────────────────────────────────────"));
+
+  for (const file of files) {
+    const filePath = join(FACTS_DIR, file);
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n").length;
+    totalLines += lines;
+
+    const name = file.replace(/\.md$/, "");
+    const pct = Math.round((lines / LINE_BUDGET_PER_FILE) * 100);
+
+    // Extract first heading as description
+    const heading = content
+      .split("\n")
+      .find((l) => l.startsWith("# "));
+    const desc = heading ? heading.replace(/^#\s*/, "").trim() : "";
+
+    const budgetColor =
+      pct > 80 ? color.red : pct > 60 ? color.yellow : color.green;
+
+    console.log(
+      `  ${color.green("●")} ${color.bold(name)}  ${color.dim(desc)}`,
+    );
+    if (showStats) {
+      console.log(
+        `    ${lines} lines ${budgetColor(`(${pct}% of ${LINE_BUDGET_PER_FILE}-line budget)`)}`,
+      );
+    }
+  }
+
+  console.log(color.dim("──────────────────────────────────────────"));
+
+  const totalPct = Math.round((totalLines / LINE_BUDGET_TOTAL) * 100);
+  const totalColor =
+    totalPct > 80 ? color.red : totalPct > 60 ? color.yellow : color.green;
+
+  console.log(
+    `  ${files.length} file(s), ${totalColor(`${totalLines}/${LINE_BUDGET_TOTAL} lines (${totalPct}%)`)}`,
+  );
+  console.log();
+
+  if (totalPct > 80) {
+    log.warn(
+      "Facts approaching size budget — review and prune stale entries.",
+    );
+  }
+
+  // Show pending proposals count
+  if (existsSync(PROPOSALS_DIR)) {
+    const pending = readdirSync(PROPOSALS_DIR)
+      .filter((f) => f.endsWith(".json"))
+      .filter((f) => {
+        try {
+          const p = JSON.parse(readFileSync(join(PROPOSALS_DIR, f), "utf-8"));
+          return p.status === "pending";
+        } catch {
+          return false;
+        }
+      });
+    if (pending.length > 0) {
+      log.warn(
+        `${pending.length} pending proposal(s) — run ${color.bold("mneme review")} to review`,
+      );
+    }
+  }
+}
+
+/**
+ * Show contents of a specific facts file.
+ */
+function showFact(name) {
+  // Allow with or without .md extension
+  const fileName = name.endsWith(".md") ? name : `${name}.md`;
+  const filePath = join(FACTS_DIR, fileName);
+
+  if (!existsSync(filePath)) {
+    log.fail(`Facts file not found: ${filePath}`);
+
+    // Suggest available files
+    if (existsSync(FACTS_DIR)) {
+      const available = readdirSync(FACTS_DIR)
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => f.replace(/\.md$/, ""));
+      if (available.length > 0) {
+        console.log(`\nAvailable: ${available.join(", ")}`);
+      }
+    }
+    process.exit(1);
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  console.log();
+  console.log(content);
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function facts(args) {
+  const showStats = args.includes("--stats") || args.includes("-s");
+  const filtered = args.filter((a) => !a.startsWith("-") && a !== "facts");
+
+  if (filtered.length > 0) {
+    showFact(filtered[0]);
+  } else {
+    listFacts(showStats);
+  }
+}