MoFlo learns about your project and remembers it across sessions — but the hard-won part of that memory used to be trapped in whatever checkout first learned it. A new git worktree, a fresh machine, a teammate’s clone would reindex your code and guidance on its own, yet start blank on everything you’d actually taught the project. That’s fixed now: across git worktrees, your MoFlo learnings follow you automatically, with no setup — and one guided command covers teams and extra machines. Here’s what changed, and why it’s safe.
- GitHub: github.com/eric-cielo/moflo
- npm: npmjs.com/package/moflo —
npm install --save-dev moflo
The premise: MoFlo remembers, until it doesn’t
The whole pitch for MoFlo is that an assistant which remembers beats one that starts cold every session. As you work, it accumulates durable knowledge about your project — the gotcha that cost you two hours, the decision you’ll regret re-litigating next month, the pattern that turned out to be the right one. That lives in a local SQLite database at .moflo/moflo.db, and it’s what makes each session smarter than the last.
There’s a catch: that database is gitignored — deliberately, since most of it is machine-local scratch. Step into a new checkout and you don’t land completely cold; MoFlo reindexes your code and guidance on its own. But that costs minutes on a large repo, and the durable, hard-won learnings don’t come back with it. A worktree to review a PR, a clone on your laptop, a teammate onboarding — the code gets reindexed, but the learnings are stranded. That’s the gap these changes close.
The one insight that makes it safe
The naive fix — point every checkout at one shared database — is a trap, and understanding why is the whole design. That database holds three very different kinds of data, and only one is worth sharing:
| Kind | Examples | Share it? |
|---|---|---|
| Durable | learnings, knowledge — things you or Claude decided are worth keeping | Yes — this is the good stuff |
| Structural | the code map, guidance chunks, test index — a searchable model of this branch’s code | No — it’s branch-specific and rebuilds cheaply |
| Ephemeral | task lists, swarm run-state, epic state | No — it’s per-run scratch, meaningless elsewhere |
Only the durable slice is user-authored, slow to recreate, and identical no matter which checkout you’re in. The structural data is actively harmful to share: a code map from one branch is wrong on another, so syncing it just means stale search results. So the rule the whole design rests on is simple:
Share only the durable slice. Let everything else stay local and rebuild itself.
There’s a second, subtler reason, and it’s the one that bites silently. MoFlo’s semantic search runs on an in-memory vector index (HNSW), and each running daemon builds its own copy. Point two daemons at one shared file and a learning written by the first never shows up in the second’s index until a full rebuild — a database that looks shared but a search that quietly lies. Sharing only the small, append-mostly durable slice sidesteps that entirely.
Worktrees just work— automatically
This is the change you’ll feel first, and it needs no setup at all. Spinning up git worktrees to juggle several branches or reviews at once is a core moflo workflow, so we made sharing across them the default: start moflo in a checkout whose repo has worktrees in play, and your durable learnings converge across every one of them on their own.
There’s nothing to configure because there’s nothing to coordinate. Every linked worktree shares one .git common directory, so moflo derives the store at a path they all compute the same way — <git-common-dir>/moflo/durable.db — and converges on it with no registry and no config key. (Conductor builds on git worktrees, so its workspaces are covered too.) At each session start, before the daemon comes up, a checkout flushes its new learnings up to that store and seeds its siblings’ back down; every durable write also writes through as it happens. Structural and ephemeral data stays local, where it belongs.
Two guardrails make this safe on by default:
- It only wakes for worktrees. A plain single checkout derives nothing and writes nothing — byte-for-byte as before — after a couple of filesystem stats.
- It can’t trip the index hazard. The derived store is a dedicated
durable.db, never a fullmoflo.db, so only the safe durable slice ever travels.
Want it elsewhere, or off? memory.durable_path overrides the location (and can converge separate clones, which don’t share a .git); memory.worktree_sharing: false turns it off. The /memory-worktree skill handles all three — but for the common case, you do nothing.
Beyond one machine — teams and your other laptops
Worktrees share a disk. Once learnings need to leave this machine, the destination is the same whether it’s a teammate or your own laptop — a file that travels with the repo — because “just me on two machines” is a team of one. So the learnings live in the repo, reviewed like any other change, in a text format instead of a binary one:
flo memory team-export # writes .moflo/shared/learnings.jsonl and makes it git-trackable
git add .moflo/shared/learnings.jsonl && git commit && git pushThe file is JSONL — one learning per line, sorted by namespace and key — so a committed file stays diff-reviewable and merge-friendly; you can see in a pull request exactly what a teammate is adding. Embeddings are omitted (384 floats a row would wreck the diff) and regenerated on import. After a git pull, the next session auto-imports the merged file, each entry stamped with its git author — no import command to remember.
One bit of git plumbing: you can’t re-include a file with ! under an ignored parent, so team-export rewrites .gitignore from a blanket .moflo/ to .moflo/* plus !/.moflo/shared/ — tracking just the shared artifact, ignoring the machine-local DB.
You still have to export before committing, and that’s easy to forget — so the /memory-team skill installs a pre-commit hook that re-exports and stages the artifact on every commit (only when it changed, so no empty-diff churn). Learnings ride along with the change that produced them; the artifact is never stale in a PR.
Prefer to keep your cross-machine learnings out of git? A portable binary artifact skips the repo entirely — carry it through a synced folder, USB stick, or scp:
flo memory sync --to ~/Dropbox/moflo-learnings.db # on machine A
flo memory sync --from ~/Dropbox/moflo-learnings.db # on machine BBeing a plain SQLite file, it carries the embeddings verbatim — no recompute on the far side — and the same INSERT OR IGNORE merge never duplicates or clobbers, run it twice or in both directions. The trade-off: not diffable, not reviewed. Just for you.
The fast-start bonus: whole-DB snapshots
Everything above shares the durable slice. One related problem it doesn’t solve: on a large repo, a brand-new workspace with an empty database faces a full cold reindex on its first session — parse all your code, re-embed everything through the ONNX model — minutes before search works. So there’s one more tool: a whole-database snapshot.
flo memory backup --to ~/moflo-snapshot.db # consistent snapshot of the entire DB
flo memory restore --from ~/moflo-snapshot.db # hydrate a fresh workspace instantlyOr set memory.hydrate_from and a fresh workspace seeds itself at session start. Because the snapshot already holds the structural namespaces and their embeddings, the first-pass reindex is skipped — search works on session one.
Isn’t that the whole-database sharing the last section warned against? No — the trap is two running daemons on one file, their indexes drifting apart. A snapshot restore is a one-time copy into an empty workspace that then owns its own copy: no second daemon, no divergence, and any branch drift self-heals on the next reindex.
How the pieces fit together
These aren’t competitors — they compose, running in a fixed order at session start, all before the daemon comes up:
1. hydrate → restore a whole-DB snapshot (only if the local DB is empty)
2. purge → drop ephemeral namespaces from the restored copy
3. durable → flush + seed the durable slice against the shared store
4. team → import the git-tracked team artifact
5. daemon → starts, builds its index over everything aboveA fresh workspace bootstraps from a snapshot, then durable-slice sync keeps its learnings converged from then on. Every step is purely additive — INSERT OR IGNORE on the same unique key — so they never fight.
Setup, and what’s on by default
The whole surface, from “do nothing” to “wire up a team”:
| Your situation | What you do | What travels |
|---|---|---|
| Worktrees / Conductor on one machine | Nothing — it’s automatic | A shared SQLite store in .git |
| A team on one repo — or just you across several machines | Run /memory-team once | A git-tracked JSONL file |
| A fresh workspace on a huge repo | Set memory.hydrate_from | A whole-DB snapshot (one-time) |
Two guided skills own the setup so you’re not hand-assembling paths and hooks: /memory-team configures the git-tracked artifact and its pre-commit hook (a team, or your own machines); /memory-worktree covers the automatic case’s edges — confirm it, move it, extend it to separate clones, or opt out. Under the hood it’s one memory: block, every line optional and off unless you set it:
memory:
# worktree_sharing: false # opt OUT of the automatic worktree default
# durable_path: ~/.moflo-shared/team-learnings.db # override the auto store / share across separate clones
# team_artifact: .moflo/shared/learnings.jsonl # git-tracked JSONL — team, or you across machines
# hydrate_from: /path/to/moflo-snapshot.db # seed a fresh workspace from a snapshotSo almost everything is off until you ask. The one exception is worktree sharing — on by default because worktrees are central to how moflo is used, and even then only when a repo actually has worktrees. Wire it up the risky way (a config pointed at a full database instead of a dedicated store) and flo doctor -c shared-db warns you first; it also reports when automatic sharing is active, so you can always see what’s on.
Why this matters
An assistant that learns is only as good as its reach. A lesson MoFlo picked up Monday, on your desktop, is worth little if it’s invisible Tuesday on your laptop — or to the teammate who hits the same gotcha next week.
These changes make that learning portable without making it dangerous, by refusing to treat “the database” as one thing: share the small, durable, human-meaningful slice freely; let the branch-specific, machine-generated part stay local and rebuild. That’s what lets your worktrees, your machines, and your whole team get smarter about a project together while search stays fast and correct on every one of them — and for worktrees, the workflow moflo leans on hardest, it happens without you lifting a finger.
Teach the project once. Have it remembered everywhere it runs.
- GitHub: github.com/eric-cielo/moflo
- npm: npmjs.com/package/moflo —
npm install --save-dev moflo
Leave a Reply