@memfork/cli 0.1.19 → 0.1.21

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,137 @@
+---
+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
+
+---
+
+## Forking — exploring competing approaches
+
+When the user asks you to explore multiple competing approaches (e.g. "try both",
+"compare X vs Y", "explore both paths"), fork the memory tree so each hypothesis
+stays isolated. Never collapse competing ideas into a single branch.
+
+**Step 1 — announce and create branches:**
+
+```bash
+memfork branch dev/<hypothesis-a> --from $(git rev-parse --abbrev-ref HEAD)
+memfork branch dev/<hypothesis-b> --from $(git rev-parse --abbrev-ref HEAD)
+```
+
+Use short kebab-case names (`dev/redis-first`, `dev/bcrypt-cost`).
+
+**Step 2 — investigate each path and commit evidence:**
+
+```bash
+memfork commit \
+  --branch dev/<hypothesis-a> \
+  --message "<what you found>" \
+  --facts "<measured fact>" "<result>"
+```
+
+Commit at each meaningful step — hypothesis, measurement, result.
+
+**Step 3 — summarise, do not merge.**
+
+Report findings side by side and recommend which branch has stronger evidence.
+Never run `memfork merge` as part of a fork investigation — merging is a
+human governance act.
+
+---
+
+## 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 |