@memfork/cli 0.1.19 → 0.1.21

package/dist/cli.js

@@ -25,7 +25,7 @@ const { version } = createRequire(import.meta.url)("../package.json");
 import { cmdInit } from "./commands/init.js";
 import { cmdDoctor, cmdDoctorEnv } from "./commands/doctor.js";
 import { cmdInstall } from "./commands/install.js";
-import { cmdStatus, cmdLog, cmdRecall, cmdCommit, cmdMerge, cmdProposals, cmdUi, cmdShow, cmdDiff, cmdDelegates, cmdGrant, cmdGrantMemwal, cmdRevoke, cmdBranch, cmdCheckout, } from "./commands/ops.js";
+import { cmdStatus, cmdLog, cmdRecall, cmdCommit, cmdMerge, cmdProposals, cmdResolverCreate, cmdPrComment, cmdUi, cmdShow, cmdDiff, cmdDelegates, cmdGrant, cmdGrantMemwal, cmdRevoke, cmdBranch, cmdCheckout, } from "./commands/ops.js";
 import { cmdJoin } from "./commands/join.js";
 const program = new Command();
 program
@@ -90,13 +90,29 @@ program
 program
     .command("merge <from> <into>")
     .description("merge memory from one branch into another")
-    .option("-r, --resolver <id>", "ResolverRef object ID (default: LastWriteWins, or MEMFORK_RESOLVER_ID env var)")
+    .option("-r, --resolver <id>", "ResolverRef object ID — enables governed jury merge (or set MEMFORK_RESOLVER_ID)")
+    .option("--lww", "force LastWriteWins even when MEMFORK_RESOLVER_ID is set")
     .option("--ttl <ms>", "proposal TTL in milliseconds", parseInt, 86_400_000)
     .action(wrap((from, into, opts) => cmdMerge(from, into, opts)));
 program
     .command("proposals")
     .description("list open merge proposals")
     .action(wrap(cmdProposals));
+const resolverCmd = new Command("resolver").description("manage resolver objects");
+resolverCmd
+    .command("create")
+    .description("create a jury resolver (k-of-n)")
+    .requiredOption("--jury <addresses>", "comma-separated judge Sui addresses")
+    .option("-k, --k <n>", "approval threshold (default: majority)", parseInt)
+    .action(wrap((opts) => cmdResolverCreate({ jury: opts.jury, k: opts.k ?? 2 })));
+program.addCommand(resolverCmd);
+program
+    .command("pr-comment")
+    .description("post a MemForks decision summary to a GitHub PR")
+    .requiredOption("--pr <number>", "PR number", parseInt)
+    .option("--repo <owner/repo>", "GitHub repo (default: inferred from git remote)")
+    .option("--branch <name>", "branch to recall decided fact from (default: into_branch of last merge)")
+    .action(wrap((opts) => cmdPrComment(opts)));
 program
     .command("ui")
     .description("open the MemForks DAG visualizer")

package/dist/commands/install.js

@@ -21,8 +21,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readCredentials, readProjectConfig, MEMWAL_CONSTANTS } from "../config.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// dist/commands/install.js → packages/cli → packages → repo root → plugins/
-const PLUGIN_ROOT = path.resolve(__dirname, "..", "..", "..", "..", "plugins");
+// dist/commands/install.js → dist/ → package root → plugins/
+const PLUGIN_ROOT = path.resolve(__dirname, "..", "..", "plugins");
 function ok(s) { return chalk.green("✓") + " " + s; }
 function warn(s) { return chalk.yellow("⚠") + " " + s; }
 function tip(s) { return chalk.cyan("→") + " " + s; }

package/dist/commands/ops.d.ts

@@ -22,8 +22,18 @@ export declare function cmdCommit(opts: {
 export declare function cmdMerge(from: string, into: string, opts: {
     resolver?: string;
     ttl?: number;
+    lww?: boolean;
 }): Promise<void>;
 export declare function cmdProposals(): Promise<void>;
+export declare function cmdResolverCreate(opts: {
+    jury: string;
+    k: number;
+}): Promise<void>;
+export declare function cmdPrComment(opts: {
+    pr: number;
+    repo?: string;
+    branch?: string;
+}): Promise<void>;
 export declare function cmdUi(opts?: {
     share?: boolean;
     port?: number;

package/dist/commands/ops.js

@@ -129,11 +129,12 @@ export async function cmdMerge(from, into, opts) {
     const cfg = resolveConfig();
     const clientCfg = {
         ...toClientConfig(cfg),
-        // --resolver flag overrides MEMFORK_RESOLVER_ID env var for this call
-        ...(opts.resolver ? { defaultResolverId: opts.resolver } : {}),
+        // --resolver flag overrides MEMFORK_RESOLVER_ID env var for this call.
+        // --lww forces the LWW path even when MEMFORK_RESOLVER_ID is set.
+        ...(opts.lww ? { defaultResolverId: undefined } : opts.resolver ? { defaultResolverId: opts.resolver } : {}),
     };
     const client = await MemForksClient.connect(clientCfg);
-    const governed = !!(opts.resolver ?? process.env["MEMFORK_RESOLVER_ID"]);
+    const governed = !opts.lww && !!(opts.resolver ?? process.env["MEMFORK_RESOLVER_ID"]);
     process.stdout.write(chalk.dim(`Merging ${chalk.green(from)} → ${chalk.green(into)}`) +
         chalk.dim(governed ? "  (governed — awaiting resolver…)" : "  (LWW — self-finalizing…)") +
         "  ");
@@ -158,20 +159,192 @@ export async function cmdMerge(from, into, opts) {
 }
 // ─── proposals ────────────────────────────────────────────────────────────────
 export async function cmdProposals() {
-    const { client, cfg } = await getClient();
-    // Fetch open MergeProposed events from the indexer.
-    // For now this polls recent events (the indexer / app/ maintains the live view).
+    const { cfg } = await getClient();
+    const { SuiJsonRpcClient, JsonRpcHTTPTransport, getJsonRpcFullnodeUrl } = await import("@mysten/sui/jsonRpc");
+    const rpcUrl = cfg.rpcUrl ?? getJsonRpcFullnodeUrl(cfg.network ?? "testnet");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sui = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network: cfg.network ?? "testnet" });
     console.log("");
-    console.log(chalk.bold("Open merge proposals"));
-    console.log(chalk.dim("  (live status in the visualizer: memfork ui)"));
+    console.log(chalk.bold("Merge proposals") + chalk.dim("  tree: " + cfg.treeId.slice(0, 12) + "…"));
     console.log("");
-    console.log(chalk.dim("  Tree: " + cfg.treeId));
+    const PROPOSAL_STATUS = { PENDING: 0, FINALIZED: 1, ABORTED: 2 };
+    let events;
+    try {
+        const result = await sui.queryEvents({
+            query: { MoveEventType: `${cfg.packageId}::resolver::MergeProposed` },
+            limit: 20,
+            order: "descending",
+        });
+        events = result.data.filter((e) => e.parsedJson["tree_id"] === cfg.treeId);
+    }
+    catch {
+        console.log(chalk.dim("  Could not query Sui events."));
+        console.log(chalk.cyan("  →") + " Run " + chalk.bold("memfork ui") + " for the live view.");
+        console.log("");
+        return;
+    }
+    if (events.length === 0) {
+        console.log(chalk.dim("  No proposals found for this tree."));
+        console.log("");
+        return;
+    }
+    for (const ev of events.slice(0, 10)) {
+        const p = ev.parsedJson;
+        const id = String(p["proposal_id"] ?? "");
+        // Fetch live status from the proposal object.
+        let statusLabel = chalk.yellow("pending");
+        try {
+            const obj = await sui.getObject({ id, options: { showContent: true } });
+            if (obj.data?.content && obj.data.content.dataType === "moveObject") {
+                const status = Number(obj.data.content.fields["status"]);
+                if (status === PROPOSAL_STATUS.FINALIZED)
+                    statusLabel = chalk.green("finalized");
+                else if (status === PROPOSAL_STATUS.ABORTED)
+                    statusLabel = chalk.red("aborted");
+            }
+        }
+        catch { /* proposal may be consumed */ }
+        console.log(`  ${statusLabel}  ` +
+            chalk.green(String(p["from_branch"]) + " → " + String(p["into_branch"])) + "  " +
+            chalk.dim(id.slice(0, 12) + "…"));
+    }
     console.log("");
-    console.log(chalk.dim("  Polling Sui events…"));
-    // TODO: drive through MemForksIndexer once it's wired into the CLI.
-    // For the hackathon: redirect to the visualizer.
+    console.log(chalk.dim("  Full detail: memfork ui → Merges view"));
     console.log("");
-    console.log(chalk.cyan("  →") + " Run " + chalk.bold("memfork ui") + " for the full live proposal view.");
+}
+// ─── resolver create ──────────────────────────────────────────────────────────
+export async function cmdResolverCreate(opts) {
+    const { client } = await getClient();
+    const { resolvers } = await import("@memfork/core");
+    const juryAddrs = opts.jury.split(",").map((a) => a.trim()).filter(Boolean);
+    if (juryAddrs.length === 0) {
+        console.error(chalk.red("Pass at least one judge address via --jury <addr1,addr2,...>"));
+        process.exit(1);
+    }
+    const k = opts.k ?? Math.ceil(juryAddrs.length / 2 + 0.5);
+    process.stdout.write(chalk.dim(`Creating jury resolver  (${k}-of-${juryAddrs.length}) …  `));
+    const def = resolvers.jury(juryAddrs, k, juryAddrs.length);
+    const { digest, resolverId } = await client.createResolver(def);
+    console.log(chalk.green("done"));
+    console.log("");
+    console.log(chalk.dim("  ResolverRef: ") + chalk.cyan(resolverId));
+    console.log(chalk.dim("  tx:          ") + chalk.dim(digest));
+    console.log("");
+    console.log(chalk.bold("  Save this to your environment:"));
+    console.log("  " + chalk.cyan(`export MEMFORK_RESOLVER_ID=${resolverId}`));
+    console.log("");
+    console.log(chalk.dim("  Or add resolverId to .memfork/config.json for project-wide use."));
+    console.log("");
+}
+// ─── pr-comment ───────────────────────────────────────────────────────────────
+export async function cmdPrComment(opts) {
+    const { client, cfg } = await getClient();
+    const { SuiJsonRpcClient, JsonRpcHTTPTransport, getJsonRpcFullnodeUrl } = await import("@mysten/sui/jsonRpc");
+    const rpcUrl = cfg.rpcUrl ?? getJsonRpcFullnodeUrl(cfg.network ?? "testnet");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sui = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network: cfg.network ?? "testnet" });
+    console.log("");
+    console.log(chalk.dim("Fetching latest merge anchor…"));
+    // Find the most recent MergeFinalized event for this tree.
+    let anchorId = "";
+    let proposalId = "";
+    let suiTx = "";
+    let walrusBlob = "";
+    let fromBranch = "";
+    let intoBranch = "";
+    try {
+        const result = await sui.queryEvents({
+            query: { MoveEventType: `${cfg.packageId}::resolver::MergeFinalized` },
+            limit: 10,
+            order: "descending",
+        });
+        const ev = result.data
+            .find((e) => e.parsedJson["tree_id"] === cfg.treeId);
+        if (!ev) {
+            console.error(chalk.red("No finalized merges found for this tree. Run `memfork merge` first."));
+            process.exit(1);
+        }
+        anchorId = String(ev.parsedJson["merge_commit_id"] ?? "");
+        walrusBlob = String(ev.parsedJson["resolved_blob_id"] ?? "");
+        suiTx = ev.id.txDigest;
+        proposalId = String(ev.parsedJson["proposal_id"] ?? "");
+    }
+    catch (e) {
+        console.error(chalk.red("Failed to query Sui: " + String(e)));
+        process.exit(1);
+    }
+    // Fetch proposal for branch names and attestation count.
+    let voteCount = "?";
+    let threshold = "?";
+    try {
+        const obj = await sui.getObject({ id: proposalId, options: { showContent: true } });
+        if (obj.data?.content && obj.data.content.dataType === "moveObject") {
+            const fields = obj.data.content.fields;
+            fromBranch = String(fields["from_branch"] ?? "");
+            intoBranch = String(fields["into_branch"] ?? "");
+            const attests = fields["attestations"];
+            voteCount = String(attests?.length ?? "?");
+        }
+    }
+    catch { /* non-critical */ }
+    // Get the decided fact from the into_branch via recall.
+    const targetBranch = opts.branch ?? intoBranch ?? currentGitBranch();
+    let decision = `Use ${fromBranch || "winning branch"} approach.`;
+    try {
+        const results = await client.recall("decided", { branch: targetBranch, limit: 1 });
+        if (results.length > 0) {
+            decision = results[0].text.replace(/^decided:\s*/i, "").split(".")[0] + ".";
+        }
+    }
+    catch { /* fallback to default */ }
+    // Find rejected paths via recall on the into_branch.
+    let rejectedPath = "";
+    try {
+        const rejected = await client.recall("rejected-path", { branch: targetBranch, limit: 1 });
+        if (rejected.length > 0) {
+            const match = rejected[0].text.match(/(\S+)\s+was not merged/);
+            if (match)
+                rejectedPath = match[1];
+        }
+    }
+    catch { /* non-critical */ }
+    const shortAnchor = anchorId.replace(/^0x/, "").slice(0, 7);
+    const shortTx = suiTx.replace(/^0x/, "").slice(0, 8);
+    const shortBlob = walrusBlob.slice(0, 12);
+    const vizUrl = `memforks.dev/${cfg.treeId.replace(/^0x/, "").slice(0, 8)}#${shortAnchor}`;
+    const body = [
+        `🔗 **MemForks decision attached**`,
+        ``,
+        `**Decision:**`,
+        decision,
+        ``,
+        `**How it was decided:**`,
+        `Jury vote, ${voteCount} of ${threshold} — enforced on Sui`,
+        ``,
+        `**Merge:** \`${shortAnchor}\``,
+        ``,
+        `**Sui:** \`${shortTx}…\``,
+        ``,
+        `**Walrus:** \`${shortBlob}…\``,
+        rejectedPath
+            ? [``, `**Rejected path:**`, `\`${rejectedPath}@latest\` remains queryable`].join("\n")
+            : "",
+        ``,
+        `**Full audit trail:** ${vizUrl}`,
+    ].filter((l) => l !== undefined).join("\n");
+    // Post via gh CLI.
+    const repoFlag = opts.repo ? `--repo ${opts.repo}` : "";
+    try {
+        execSync(`gh pr comment ${opts.pr} ${repoFlag} --body ${JSON.stringify(body)}`, {
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        console.log(chalk.green("✓") + " Comment posted to PR #" + opts.pr);
+    }
+    catch {
+        console.log(chalk.yellow("gh CLI not available or auth required. Copy this comment:"));
+        console.log("");
+        console.log(body);
+    }
     console.log("");
 }
 // ─── ui ───────────────────────────────────────────────────────────────────────
@@ -441,15 +614,21 @@ function extractFacts(response) {
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function findAppDir() {
-    // dist/commands/ops.js → packages/cli → packages → repo root → apps/visualizer
+    // Resolution order:
+    //   1. packages/cli/ui/         — bundled at publish time (npm install path)
+    //   2. apps/visualizer/         — monorepo dev path (two depths to handle symlinks)
     const candidates = [
-        new URL("../../../../apps/visualizer", import.meta.url).pathname,
-        new URL("../../../../../apps/visualizer", import.meta.url).pathname,
+        new URL("../../ui", import.meta.url).pathname, // dist/commands/ → cli root → ui/
+        new URL("../../../../apps/visualizer", import.meta.url).pathname, // monorepo: packages/cli
+        new URL("../../../../../apps/visualizer", import.meta.url).pathname, // monorepo: alternate depth
     ];
     for (const c of candidates) {
         try {
-            if (fs.existsSync(c + "/package.json"))
+            // Bundled path: presence of index.html is the signal (no package.json shipped).
+            // Monorepo path: package.json marks the source root.
+            if (fs.existsSync(path.join(c, "index.html")) || fs.existsSync(path.join(c, "package.json"))) {
                 return c;
+            }
         }
         catch {
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memfork/cli",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "MemForks CLI — init, commit, recall, merge, install plugins",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "./config": "./dist/config.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/copy-plugins.mjs && tsc && node scripts/bundle-ui.mjs",
     "dev": "tsc --watch",
     "start": "node dist/index.js"
   },
@@ -29,11 +29,13 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "plugins",
+    "ui"
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@memfork/core": "^0.1.4",
+    "@memfork/core": "^0.1.9",
     "chalk": "^5.6.2",
     "commander": "^15.0.0"
   },

package/plugins/codex/.codex-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "memforks",
+  "version": "0.2.0",
+  "description": "On-chain, branch-aware memory DAG for Codex. MemForks anchors decisions to Sui and proposes cross-branch merges — memory storage is handled by the MemWal MCP server.",
+  "author": {
+    "name": "MemForks",
+    "email": "team@memforks.dev"
+  },
+  "homepage": "https://github.com/memforks-dev/memforks",
+  "repository": "https://github.com/memforks-dev/memforks",
+  "license": "Apache-2.0",
+  "keywords": [
+    "memory",
+    "sui",
+    "blockchain",
+    "provenance",
+    "branching",
+    "codex",
+    "agent-memory",
+    "memwal"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "MemForks",
+    "shortDescription": "On-chain, branch-aware memory DAG",
+    "longDescription": "MemForks gives Codex a tamper-proof, branch-synced memory DAG anchored on Sui. Memory recall and storage are handled natively by the MemWal MCP server. MemForks adds the version-control layer: immutable on-chain commits, Git branch-scoped history, and conflict-free cross-branch merges via an on-chain resolver.",
+    "developerName": "MemForks",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/memforks-dev/memforks",
+    "privacyPolicyURL": "https://github.com/memforks-dev/memforks",
+    "termsOfServiceURL": "https://github.com/memforks-dev/memforks/blob/main/LICENSE",
+    "defaultPrompt": [
+      "Recall any relevant context for this branch",
+      "Show my MemForks memory status",
+      "Commit the decisions we made today"
+    ],
+    "brandColor": "#1f9d72",
+    "screenshots": []
+  }
+}

package/plugins/codex/README.md

@@ -0,0 +1,81 @@
+# MemForks — Codex Plugin
+
+On-chain, branch-aware memory DAG for Codex.
+
+**Memory storage** is handled by the MemWal MCP server — the agent calls
+`memwal_recall` and `memwal_remember` natively as tool calls.
+
+**On-chain versioning** is handled by the `memfork` CLI — decisions get
+cryptographically anchored to Sui with branch context and a full commit DAG.
+
+## Setup (one time, per machine)
+
+```bash
+npm install -g @memfork/cli
+
+# Recommended — zero copy-paste, ~30 seconds on testnet:
+memfork init --quick
+
+# Or manual if you already have a Sui key + MemWal account:
+memfork init
+```
+
+## Install the plugin
+
+```bash
+memfork install codex
+```
+
+This does two things:
+
+1. **Writes `~/.codex/config.toml`** — adds a `[mcp_servers.memwal]` entry using
+   the delegate key provisioned by `memfork init`. No browser login needed.
+
+2. **Copies `.codex-plugin/`** — installs the plugin skills into the current project.
+
+Then register with Codex:
+
+```bash
+codex plugin add .codex-plugin
+```
+
+## Verify
+
+```bash
+memfork doctor
+```
+
+## What the agent can do
+
+| Tool / Command | What it does |
+|----------------|-------------|
+| `memwal_recall(query, namespace)` | Semantic search over branch memory (MCP tool) |
+| `memwal_remember(text, namespace)` | Save a fact to branch memory (MCP tool) |
+| `memwal_analyze(text)` | Extract and save multiple facts at once (MCP tool) |
+| `memfork commit --facts …` | Anchor a decision on-chain with full provenance |
+| `memfork merge <src> <dst>` | Propose a cross-branch memory merge |
+| `memfork status / log / proposals` | Inspect the on-chain DAG |
+
+Memory is namespaced by Git branch — `namespace="branch/<branch-name>"`.
+
+## What gets installed
+
+```
+~/.codex/config.toml       ← MemWal MCP server entry (auto-configured)
+.codex-plugin/
+  plugin.json              ← plugin metadata
+  skills/
+    memory-recall/         ← when/how to use memwal_recall
+    memforks-status/       ← when/how to use memfork commit/merge/status
+```
+
+No shell hooks. The MCP server is the transport.
+
+## Override for CI / headless use
+
+```bash
+MEMFORK_TREE_ID=0x…
+MEMFORK_PRIVATE_KEY=suiprivkey1…
+MEMFORK_MEMWAL_ACCOUNT=0x…
+MEMFORK_MEMWAL_KEY=<hex>
+```

package/plugins/codex/skills/memforks-status/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: memforks-status
+description: >-
+  Show MemForks on-chain status: branch DAG, open merge proposals, recent commits.
+  Use when the user asks about memory status, proposals, or the commit log.
+  Also use when committing decisions or proposing a merge.
+---
+
+# MemForks On-Chain Operations
+
+MemForks is the version-control layer on top of MemWal. Use the `memfork` CLI for
+DAG operations — not for routine recall/remember (that's the MCP server's job).
+
+## Check status
+
+```bash
+memfork status                    # current tree, branch, signer, head commit
+memfork log --branch <branch>     # recent on-chain commits
+memfork proposals                 # open merge proposals
+memfork ui                        # open the DAG visualizer
+```
+
+## Commit a decision on-chain
+
+Use this after significant architectural decisions — not for routine facts.
+(Routine facts go through `memwal_remember` via MCP.)
+
+```bash
+memfork commit \
+  --branch $(git rev-parse --abbrev-ref HEAD) \
+  --message "decided: <one-line summary>" \
+  --facts "<fact 1>" "<fact 2>"
+```
+
+## Merge branches
+
+When two branches need to reconcile their memory:
+
+```bash
+# Zero-config — LastWriteWins, self-finalizes immediately
+memfork merge <from-branch> <into-branch>
+
+# Governed — jury / LLM resolver (requires MEMFORK_RESOLVER_ID env var or --resolver flag)
+memfork merge <from-branch> <into-branch> --resolver <resolver-id>
+```
+
+With no `--resolver` flag and no `MEMFORK_RESOLVER_ID` set, the merge uses
+LastWriteWins and finalizes immediately — no resolver service required.
+
+When a resolver is configured, the command waits for the on-chain resolver service
+to collect attestations and finalize before returning.
+
+---
+
+## Suggesting a merge — proactive but not autonomous
+
+You may **suggest** a merge when you notice the current branch has accumulated
+durable facts not yet on `main`. Phrase it as an offer:
+
+> "This branch has several facts that aren't on main yet — want me to merge them?
+> I'll run `memfork merge <branch> main`."
+
+**Never run `memfork merge` without the user explicitly confirming.** Merging
+changes shared team memory and creates an on-chain anchor — it is a governance
+act, not a routine commit.
+
+Suggest a merge when:
+- The user says "we're done with this branch" or "I'm about to open a PR"
+- You've committed 3+ significant facts this session and the user hasn't merged
+- The user asks "what should I do next?" at the end of a long session
+
+Once the user confirms, run:
+
+```bash
+memfork merge <current-branch> main
+```
+
+---
+
+## When to use this skill
+
+- User asks "what's the status of my memory?"
+- User asks "are there any pending merges?"
+- User says "commit what we decided today"
+- User confirms they want to merge memory from one branch into another
+- User wants to open the DAG visualizer

package/plugins/codex/skills/memory-fork/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: memory-fork
+description: >-
+  Fork agent memory into parallel branches to explore competing hypotheses.
+  Use when the user asks to explore multiple approaches, compare options, or
+  says phrases like "explore both", "try two paths", "compare A vs B".
+---
+
+# Memory Fork
+
+When you detect a multi-hypothesis prompt — the user wants to explore two or
+more competing approaches — fork the MemForks memory tree so each path stays
+isolated.  Never collapse competing ideas into a single stream.
+
+## When to trigger
+
+Trigger this skill when the user prompt contains signals like:
+- "explore both paths" / "try both" / "compare X and Y"
+- "what if we did X instead of Y" (two real alternatives)
+- "should we do A or B?" (genuine decision fork, not a rhetorical question)
+- Any request to investigate multiple competing solutions side-by-side
+
+## Procedure
+
+### 1. Announce the fork
+
+Print exactly:
+
+```
+[memforks] Multi-hypothesis detected.
+[memforks] Forking agent memory from <current-branch>@HEAD
+```
+
+Then list the branches you will create, one per hypothesis:
+
+```
+           ├── dev/<short-hypothesis-a>
+           └── dev/<short-hypothesis-b>
+```
+
+Use kebab-case branch names derived from the hypothesis (e.g. `dev/redis-first`,
+`dev/bcrypt-cost`, `dev/approach-a`).
+
+### 2. Create the branches
+
+For each hypothesis, run:
+
+```bash
+memfork branch dev/<hypothesis> --from <current-branch>
+```
+
+### 3. Investigate hypothesis A
+
+Switch to the first branch and investigate:
+
+```bash
+memfork checkout dev/<hypothesis-a>
+```
+
+Work through the hypothesis.  As you discover facts, commit them:
+
+```bash
+memfork commit \
+  --branch dev/<hypothesis-a> \
+  --message "<what you found>" \
+  --facts "<concrete measurable fact>" "<another fact>"
+```
+
+Commit at each meaningful step — hypothesis statement, baseline measurement,
+result.  Three commits is normal; more is fine.
+
+### 4. Investigate hypothesis B
+
+```bash
+memfork checkout dev/<hypothesis-b>
+```
+
+Repeat the same commit cadence.
+
+### 5. Summarise
+
+After both branches have evidence, summarise findings side by side and tell
+the user which branch has stronger evidence.  Do NOT merge — merging is a
+human governance act (`memfork merge`).
+
+## Output format for each commit
+
+Use this fact structure for clarity and later recall:
+
+```
+hypothesis: <one-sentence statement of what this branch is testing>
+fact:        <measured or researched datum — numbers are better than adjectives>
+result:      <conclusion or outcome of the investigation>
+```
+
+## Rules
+
+- Never commit to `main` or the parent branch during a fork investigation.
+- Never type `memfork merge` — that is the operator's call.
+- If the user asks "which won?", answer from memory; do not merge.
+- Keep branch names short and descriptive (`dev/redis-first` not `dev/add-redis-caching-to-auth-flow`).
+- If `memfork branch` fails because the branch already exists, use `memfork checkout` and continue.