Skip to content

eric-cielo/moflo / .claude/skills/memory-worktree

memory-worktree

Verified

Verify, customize, or opt out of moflo's AUTOMATIC durable-learning sharing across git worktrees / Conductor workspaces on one machine. As of the worktree-auto-sharing change this is on by default — learnings converge across a repo's worktrees with no setup. Use when the user asks "is memory shared across my worktrees?", "where are my worktree learnings stored?", "turn off worktree memory sharing", "share learnings across my separate clones", or "point my worktrees at a custom store". For a team or cross-machine (git-tracked) sharing, use /memory-team instead.

FileKindSize
SKILL.mdskill md5.7 KB
---
name: memory-worktree
description: |
  Verify, customize, or opt out of moflo's AUTOMATIC durable-learning sharing across git worktrees /
  Conductor workspaces on one machine. As of the worktree-auto-sharing change this is on by default —
  learnings converge across a repo's worktrees with no setup. Use when the user asks "is memory shared
  across my worktrees?", "where are my worktree learnings stored?", "turn off worktree memory sharing",
  "share learnings across my separate clones", or "point my worktrees at a custom store". For a team or
  cross-machine (git-tracked) sharing, use /memory-team instead.
arguments: "[--off | --path <store>]"
---

# /memory-worktree — Durable Sharing Across Worktrees (Automatic)

Working across git worktrees is a core moflo competency, so durable-learning sharing across the
worktrees of a repo is now **automatic and on by default**. When a checkout is part of a repo with
worktrees in play, moflo derives a shared durable store at **`<git-common-dir>/moflo/durable.db`** and
converges the `learnings` + `knowledge` namespaces across every worktree at session start — no config.
A plain single checkout writes nothing and behaves exactly as before.

This skill is for the three things you might still want: **verify** it's working, **customize** where it
stores (or extend it to non-worktree clones), or **opt out**.

> Only the durable slice travels. Structural + ephemeral data stays local per checkout and rebuilds
> itself — the same safety model the auto path is built on (a dedicated `durable.db`, never a full
> `moflo.db`). See [[memory-team]] for the git-tracked, cross-machine variant.

**Arguments:** `$ARGUMENTS` — `--off` to opt out, `--path <store>` to set a custom shared store.

## When to use

- "Is memory / are learnings shared across my worktrees?" → **verify** (Step 1).
- "Where are my worktree learnings stored?" → it's `<git-common-dir>/moflo/durable.db`; verify to confirm.
- "Turn off / disable worktree memory sharing" → **opt out** (Step 2).
- "Share learnings across my separate clones / a custom location" → **customize** (Step 3).

For a team, or your own laptop+desktop over git, that's `/memory-team`, not this.

## Procedure

### Step 0 — Memory first (gate requirement)

```
mcp__moflo__memory_search { query: "durable_path worktree sharing auto git common dir learnings", namespace: "guidance" }
```

### Step 1 — Verify (default action)

Run the safety/status check and surface it verbatim:

```bash
npx flo doctor -c shared-db 2>&1
```

- **"Automatic worktree learning sharing active (<path>)"** → it's working; the path is the shared store.
- **"No shared full moflo.db detected…"** → auto sharing is NOT active here. Most likely this checkout
  has no sibling worktrees yet (auto only turns on once worktrees exist). Confirm with the user; if they
  expected sharing across *separate clones* (not worktrees), go to Step 3 — auto can't converge those.
- **A `warn`** → a full-DB misconfig is present; follow the check's `fix` line.

To see that learnings actually converged, from a second worktree:

```bash
npx flo memory list --namespace learnings 2>&1 | head
```

### Step 2 — Opt out (`--off`)

If the user wants it off, set the toggle in the project-root `moflo.yaml` (preserve other `memory:` keys):

```yaml
memory:
  worktree_sharing: false
```

Explain: this stops the auto flush/seed at session start. Anything already converged into a worktree's
local DB stays; nothing new propagates. Takes effect next session.

### Step 3 — Customize the store (`--path`, or non-worktree clones)

Setting an explicit `memory.durable_path` **overrides** the auto derivation — use it to:
- put the shared store somewhere other than `.git/moflo/` (e.g. a synced/backed-up location), or
- converge checkouts that are **separate clones**, not git worktrees (auto only covers worktrees, since
  only worktrees share a git common dir).

```yaml
memory:
  durable_path: ~/.moflo-shared/<repo-name>-learnings.db
```

The path must live outside any single checkout and must **not** be named `moflo.db`. Create the parent
dir with a Node primitive (cross-platform — never `mkdir -p`):

```bash
node -e "const p=require('path'),fs=require('fs');fs.mkdirSync(p.dirname(process.argv[1]),{recursive:true})" "<chosen-store-path>"
```

Then re-run `npx flo doctor -c shared-db` to confirm it reports the durable-only store as safe.

## Output

End with a single-block summary of what state you left it in, e.g.:

```
Worktree Memory Sharing
────────────────────────
Mode:         automatic (default)  |  custom durable_path  |  disabled
Store:        <git-common-dir>/moflo/durable.db  (or the custom/none path)
Config:       memory.worktree_sharing / memory.durable_path
Verify:       npx flo doctor -c shared-db
Scope:        learnings + knowledge only (structural stays local)
```

## Rules

- **Don't** re-implement the sync or path derivation — it's `resolveDurablePath` / `syncDurableAtSessionStart`
  in `src/cli/services/durable-sync.ts`; this skill only reads config, sets the two keys, and verifies.
- **Never** set `durable_path` to a file named `moflo.db` or the local `.moflo/moflo.db` — that's the
  HNSW-index-divergence hazard `flo doctor -c shared-db` guards against.
- **Don't** use `mkdir -p` / `rm` / `cp` in shell steps — Windows lacks them on PATH. Use Node `fs`.
- **Cross-machine or team? Wrong skill.** Redirect to `/memory-team`.

## See Also

- `/memory-team` — git-tracked JSONL sharing for teams **and** one person across machines
- `flo doctor -c shared-db` — reports auto-sharing status and catches full-DB misconfig
- `docs/blog/memory-sharing.html` — the design rationale (durable vs structural vs ephemeral)
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall