@memfork/cli 0.1.19 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memfork/cli",
-  "version": "0.1.19",
+  "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 |