@memfork/cli 0.1.18 → 0.1.20

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/ui-server.js

@@ -49,7 +49,7 @@ async function handleApiConfig(res) {
     const stored = treeId ? creds.trees[treeId] : undefined;
     json(res, {
         treeId,
-        packageId: project?.packageId ?? "0x7df9719d799386d34d657c49ae8cd6f5f03b39036f7c428b556095e42afd852f",
+        packageId: project?.packageId ?? "0xc13cc014fb8084b3468f6e5ffdc272e64ef35b7a912332eba7a0d44dd66b3121",
         network,
         rpcUrl: project?.rpcUrl ?? null,
         hasMemwal: !!(stored?.memwalKey && stored?.memwalAccountId),

package/dist/config.d.ts

@@ -25,22 +25,22 @@
 export declare const MEMWAL_CONSTANTS: {
     readonly testnet: {
         readonly packageId: "0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6";
-        readonly memforksPackageId: "0xc9f0a4964f810c794479bc5b66347998969d2c59d6797c313b8a96d2bdd6a914";
+        readonly memforksPackageId: "0x185e765a4979fb9d9089374f822485c88b9d0b2f91f9b1313a73043d5ef2357f";
         readonly registryId: "0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437";
-        readonly relayer: "https://relayer.staging.memwal.ai";
+        readonly relayer: "https://relayer-staging.memory.walrus.xyz";
     };
     readonly mainnet: {
         readonly packageId: "0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6";
-        readonly memforksPackageId: "0x7df9719d799386d34d657c49ae8cd6f5f03b39036f7c428b556095e42afd852f";
+        readonly memforksPackageId: "0xc13cc014fb8084b3468f6e5ffdc272e64ef35b7a912332eba7a0d44dd66b3121";
         readonly registryId: "0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd";
-        readonly relayer: "https://relayer.memwal.ai";
+        readonly relayer: "https://relayer.memory.walrus.xyz";
     };
 };
 export interface ProjectConfig {
     /** Sui MemoryTree object ID. */
     treeId?: string;
     /** Sui network. Default: "mainnet". */
-    network?: "testnet" | "mainnet" | "devnet" | "localnet";
+    network?: 'testnet' | 'mainnet' | 'devnet' | 'localnet';
     /** Default branch name. Default: "main". */
     defaultBranch?: string;
     /** Override Sui RPC URL. */
@@ -70,7 +70,7 @@ export interface ResolvedConfig {
     memwalAccountId: string;
     memwalKey: string;
     memwalRelayer: string;
-    network: "testnet" | "mainnet" | "devnet" | "localnet";
+    network: 'testnet' | 'mainnet' | 'devnet' | 'localnet';
     defaultBranch: string;
     rpcUrl?: string;
     packageId?: string;

package/dist/config.js

@@ -22,32 +22,32 @@
  *
  * Plugins and hooks call the CLI binary and never read credentials themselves.
  */
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 // ─── Public network constants ─────────────────────────────────────────────────
 // Sources: https://docs.memwal.ai/contract/overview
 export const MEMWAL_CONSTANTS = {
     testnet: {
-        packageId: "0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6",
-        memforksPackageId: "0xc9f0a4964f810c794479bc5b66347998969d2c59d6797c313b8a96d2bdd6a914",
-        registryId: "0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437",
-        relayer: "https://relayer.staging.memwal.ai",
+        packageId: '0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6',
+        memforksPackageId: '0x185e765a4979fb9d9089374f822485c88b9d0b2f91f9b1313a73043d5ef2357f',
+        registryId: '0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437',
+        relayer: 'https://relayer-staging.memory.walrus.xyz',
     },
     mainnet: {
-        packageId: "0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6",
-        memforksPackageId: "0x7df9719d799386d34d657c49ae8cd6f5f03b39036f7c428b556095e42afd852f",
-        registryId: "0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd",
-        relayer: "https://relayer.memwal.ai",
+        packageId: '0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6',
+        memforksPackageId: '0xc13cc014fb8084b3468f6e5ffdc272e64ef35b7a912332eba7a0d44dd66b3121',
+        registryId: '0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd',
+        relayer: 'https://relayer.memory.walrus.xyz',
     },
 };
 // ─── Paths ────────────────────────────────────────────────────────────────────
 function defaultRelayer(network) {
-    return MEMWAL_CONSTANTS[network]?.relayer
-        ?? MEMWAL_CONSTANTS.mainnet.relayer;
+    return (MEMWAL_CONSTANTS[network]?.relayer ??
+        MEMWAL_CONSTANTS.mainnet.relayer);
 }
 export function projectConfigPath(cwd = process.cwd()) {
-    return path.join(cwd, ".memfork", "config.json");
+    return path.join(cwd, '.memfork', 'config.json');
 }
 /**
  * Walk up the directory tree from `cwd` looking for a `.memfork/config.json`,
@@ -56,7 +56,7 @@ export function projectConfigPath(cwd = process.cwd()) {
 function findProjectConfigPath(cwd = process.cwd()) {
     let dir = cwd;
     while (true) {
-        const candidate = path.join(dir, ".memfork", "config.json");
+        const candidate = path.join(dir, '.memfork', 'config.json');
         if (fs.existsSync(candidate))
             return candidate;
         const parent = path.dirname(dir);
@@ -66,7 +66,7 @@ function findProjectConfigPath(cwd = process.cwd()) {
     }
 }
 export function credentialsPath() {
-    return path.join(os.homedir(), ".memfork", "credentials.json");
+    return path.join(os.homedir(), '.memfork', 'credentials.json');
 }
 // ─── Read helpers ─────────────────────────────────────────────────────────────
 export function readProjectConfig(cwd = process.cwd()) {
@@ -74,7 +74,7 @@ export function readProjectConfig(cwd = process.cwd()) {
     if (!p)
         return null;
     try {
-        return JSON.parse(fs.readFileSync(p, "utf8"));
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
     }
     catch {
         return null;
@@ -85,7 +85,7 @@ export function readCredentials() {
     if (!fs.existsSync(p))
         return { trees: {} };
     try {
-        return JSON.parse(fs.readFileSync(p, "utf8"));
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
     }
     catch {
         return { trees: {} };
@@ -94,14 +94,14 @@ export function readCredentials() {
 // ─── Write helpers ────────────────────────────────────────────────────────────
 export function writeProjectConfig(cfg, cwd = process.cwd()) {
     const root = findGitRoot(cwd) ?? cwd;
-    const dir = path.join(root, ".memfork");
+    const dir = path.join(root, '.memfork');
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(root, ".memfork", "config.json"), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    fs.writeFileSync(path.join(root, '.memfork', 'config.json'), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
 }
 function findGitRoot(cwd) {
     let dir = cwd;
     while (true) {
-        if (fs.existsSync(path.join(dir, ".git")))
+        if (fs.existsSync(path.join(dir, '.git')))
             return dir;
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -110,10 +110,10 @@ function findGitRoot(cwd) {
     }
 }
 export function writeCredentials(creds) {
-    const dir = path.join(os.homedir(), ".memfork");
+    const dir = path.join(os.homedir(), '.memfork');
     fs.mkdirSync(dir, { recursive: true });
     const p = credentialsPath();
-    fs.writeFileSync(p, JSON.stringify(creds, null, 2) + "\n", "utf8");
+    fs.writeFileSync(p, JSON.stringify(creds, null, 2) + '\n', 'utf8');
     // 600: owner read+write only — no other users can read private keys.
     fs.chmodSync(p, 0o600);
 }
@@ -133,7 +133,7 @@ export function setDefaultTree(treeId) {
 export class ConfigError extends Error {
     constructor(message) {
         super(message);
-        this.name = "ConfigError";
+        this.name = 'ConfigError';
     }
 }
 /**
@@ -145,21 +145,15 @@ export function resolveConfig(opts = {}) {
     const creds = readCredentials();
     const env = process.env;
     // ── Resolve treeId ──────────────────────────────────────────────────────────
-    const treeId = env["MEMFORK_TREE_ID"] ??
-        opts.treeId ??
-        project?.treeId ??
-        creds.default;
+    const treeId = env['MEMFORK_TREE_ID'] ?? opts.treeId ?? project?.treeId ?? creds.default;
     if (!treeId) {
-        throw new ConfigError("No MemoryTree found. Run `memfork init` to create or link one.");
+        throw new ConfigError('No MemoryTree found. Run `memfork init` to create or link one.');
     }
     // ── Resolve credentials ────────────────────────────────────────────────────
     const stored = creds.trees[treeId];
-    const privateKey = env["MEMFORK_PRIVATE_KEY"] ??
-        stored?.privateKey;
-    const memwalAccountId = env["MEMFORK_MEMWAL_ACCOUNT"] ??
-        stored?.memwalAccountId;
-    const memwalKey = env["MEMFORK_MEMWAL_KEY"] ??
-        stored?.memwalKey;
+    const privateKey = env['MEMFORK_PRIVATE_KEY'] ?? stored?.privateKey;
+    const memwalAccountId = env['MEMFORK_MEMWAL_ACCOUNT'] ?? stored?.memwalAccountId;
+    const memwalKey = env['MEMFORK_MEMWAL_KEY'] ?? stored?.memwalKey;
     if (!privateKey) {
         throw new ConfigError(`No private key for tree ${treeId}. Run \`memfork init\` or set MEMFORK_PRIVATE_KEY.`);
     }
@@ -170,22 +164,23 @@ export function resolveConfig(opts = {}) {
         throw new ConfigError(`No MemWal delegate key for tree ${treeId}. Run \`memfork init\` or set MEMFORK_MEMWAL_KEY.`);
     }
     // ── Merge non-secret config ────────────────────────────────────────────────
-    const network = (env["MEMFORK_NETWORK"] ??
+    const network = (env['MEMFORK_NETWORK'] ??
         project?.network ??
-        "mainnet");
+        'mainnet');
     return {
         treeId,
         privateKey,
         memwalAccountId,
         memwalKey,
-        memwalRelayer: env["MEMFORK_RELAYER_URL"] ??
+        memwalRelayer: env['MEMFORK_RELAYER_URL'] ??
             stored?.memwalRelayer ??
             defaultRelayer(network),
         network,
-        defaultBranch: project?.defaultBranch ?? "main",
-        rpcUrl: env["MEMFORK_RPC_URL"] ?? project?.rpcUrl,
-        packageId: env["MEMFORK_PACKAGE_ID"] ?? project?.packageId,
-        sponsorUrl: env["MEMFORK_SPONSOR_URL"] ?? project?.["sponsorUrl"],
+        defaultBranch: project?.defaultBranch ?? 'main',
+        rpcUrl: env['MEMFORK_RPC_URL'] ?? project?.rpcUrl,
+        packageId: env['MEMFORK_PACKAGE_ID'] ?? project?.packageId,
+        sponsorUrl: env['MEMFORK_SPONSOR_URL'] ??
+            project?.['sponsorUrl'],
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memfork/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "MemForks CLI — init, commit, recall, merge, install plugins",
   "repository": {
     "type": "git",
@@ -29,7 +29,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "plugins"
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",

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

@@ -0,0 +1,44 @@
+{
+  "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/memforks",
+  "repository": "https://github.com/memforks/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/memforks",
+    "privacyPolicyURL": "https://github.com/memforks/memforks",
+    "termsOfServiceURL": "https://github.com/memforks/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-recall/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: memory-recall
+description: >-
+  Recall relevant memory for the current task using the MemWal MCP tool.
+  Use when the user asks about prior decisions, past context, or what you remember.
+---
+
+# Memory Recall
+
+Memory is stored via the **MemWal MCP server** — use `memwal_recall` directly as a tool call.
+Do not run `memfork recall` from the shell; the MCP tool is faster and context-aware.
+
+## Usage
+
+```
+memwal_recall(
+  query="<natural language — what you want to find>",
+  namespace="branch/<current-git-branch>",
+  limit=5
+)
+```
+
+Examples:
+```
+memwal_recall(query="auth system design", namespace="branch/main")
+memwal_recall(query="database schema decisions", namespace="branch/feature/payments")
+memwal_recall(query="what do we know about the API rate limits?", limit=10)
+```
+
+## Rules
+
+- Always scope to the current Git branch namespace unless the user asks for cross-branch context.
+- High relevance scores = verified prior context.
+- If recall returns nothing, tell the user memory is empty for this branch and offer to start capturing.
+- Never fabricate facts — only use what `memwal_recall` returns.
+
+## After recalling
+
+If relevant facts were found, summarise them briefly before answering. Cite them as
+"from memory" so the user knows they come from a prior session.

package/plugins/cursor/README.md

@@ -0,0 +1,86 @@
+# MemForks — Cursor Plugin
+
+On-chain, branch-aware memory DAG for Cursor.
+
+**Memory storage** is handled by the MemWal MCP server — the agent calls
+`memwal_recall` and `memwal_remember` natively as tool calls, mid-conversation,
+at exactly the right moment.
+
+**On-chain versioning** is handled by the `memfork` CLI — architectural decisions
+get cryptographically anchored to Sui with branch context and a full commit history.
+
+## 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 cursor
+```
+
+This does two things:
+
+1. **Writes `~/.cursor/mcp.json`** — configures the MemWal MCP server using the
+   delegate key provisioned by `memfork init`. No browser login needed.
+
+2. **Copies `.cursor/rules/memforks.mdc`** — tells the agent when to use
+   `memwal_recall`, `memwal_remember`, and `memfork commit`.
+
+## Verify
+
+```bash
+memfork doctor
+```
+
+Restart Cursor — the agent now has MemWal MCP tools available immediately.
+
+## 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 — switching branches automatically scopes
+recall to the new branch context.
+
+## What gets installed
+
+```
+~/.cursor/mcp.json         ← MemWal MCP server (Streamable HTTP, auto-configured)
+.cursor/rules/memforks.mdc ← always-on agent guidance rule
+```
+
+No shell hooks. No subprocess wrappers. 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>
+```
+
+## Uninstall
+
+```bash
+# Remove the rule:
+rm .cursor/rules/memforks.mdc
+
+# Remove the MCP server entry from ~/.cursor/mcp.json:
+# Delete the "memwal" key from mcpServers
+```

package/plugins/cursor/rules/memforks.mdc

@@ -0,0 +1,103 @@
+---
+description: MemForks — on-chain, branch-aware memory. Use memwal MCP tools for recall/remember. Use memfork CLI only for on-chain commits and merges.
+alwaysApply: true
+---
+
+# MemForks Memory
+
+This project uses MemForks: a version-controlled, branch-aware memory DAG anchored on Sui.
+
+Memory storage is handled by the **MemWal MCP server** (already configured).
+On-chain versioning is handled by the **memfork CLI**.
+
+---
+
+## Recall — use the MCP tool
+
+When the user asks about prior decisions, architecture choices, or anything that might
+have been discussed before, call the MCP tool:
+
+```
+memwal_recall(query="<natural language query>", limit=5)
+```
+
+Use the namespace matching the current Git branch:
+
+```
+memwal_recall(query="auth system design decisions", namespace="branch/<current-branch>")
+```
+
+Results with high relevance scores are verified context from prior sessions.
+
+## Remember — use the MCP tool
+
+When you learn a durable fact (not ephemeral task state), save it:
+
+```
+memwal_remember(text="<the complete fact>", namespace="branch/<current-branch>")
+```
+
+Only save facts that will be useful in future sessions:
+- Architecture decisions
+- Project conventions and preferences
+- Resolved problems and their solutions
+- Key constraints or non-obvious requirements
+
+Do **not** save: current task state, in-progress work, temporary findings.
+
+---
+
+## On-chain commit — use the CLI
+
+After a significant turn where you've committed an architectural decision or resolved
+a non-trivial problem, also anchor it on-chain for immutable versioning:
+
+```bash
+memfork commit \
+  --branch $(git rev-parse --abbrev-ref HEAD) \
+  --message "decided: <one-line summary>" \
+  --facts "<fact 1>" "<fact 2>"
+```
+
+This creates a cryptographically verifiable commit on Sui — not just a blob.
+Use it for decisions that matter for audit trail, not routine facts.
+
+---
+
+## Branch awareness
+
+- Memory is scoped to the current Git branch via the `namespace` parameter
+- When the user switches branches, recall from the new branch namespace
+- Use `memfork status` to see the on-chain tree state and open merge proposals
+
+---
+
+## Suggesting a merge — proactive but not autonomous
+
+You may **suggest** a merge when you notice the current branch has accumulated
+durable facts that are not yet on `main`. Do this by saying something like:
+
+> "This branch has several facts that aren't on main yet — want me to merge them?
+> I'll run `memfork merge <branch> main` which will write a merge anchor on-chain."
+
+**Never run `memfork merge` without the user explicitly confirming.** Merging
+changes shared team memory — it is a governance act, not a routine commit.
+
+Situations where a suggestion is appropriate:
+- The user says "we're done with this branch" or "I'm about to open a PR"
+- You've committed 3+ significant facts in this session and the user hasn't merged yet
+- The user asks "what should I do next?" at the end of a long session
+
+Always phrase it as an offer, never as an action you are about to take automatically.
+
+---
+
+## Slash commands
+
+| Command | Action |
+|---------|--------|
+| `/memforks status` | Branch status, head commit, open proposals |
+| `/memforks log` | Recent on-chain commits on this branch |
+| `/memforks recall <query>` | Manual MCP recall with a specific query |
+| `/memforks merge <src> <dst>` | Merge branch memory on-chain (confirm with user first) |
+| `/memforks ui` | Open the DAG visualizer |