An opinionated, local-first AI agent orchestration toolkit for Claude Code that provides semantic memory, learned routing, and automated task execution.
Also known as eric-cielo/moflo
- Stars
- 19
- Tools
- 121
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is MoFlo MCP?
MoFlo is an opinionated, local-first AI agent orchestration toolkit for Claude Code that provides semantic memory, learned routing, and automated task execution. It exposes 121 tools, such as agent_spawn, agent_terminate, agent_status.
Summary generated from the project's README
About MoFlo MCP server
Developers working with Claude Code can use moflo to transform their CLI environment into a self-improving agent orchestration system. It functions as a local-first toolkit that provides semantic memory, learned routing, and automated task execution without requiring external API keys or cloud services. By indexing your documentation and codebase locally using Node.js and built-in SQLite, the system ensures that Claude can search for context through meaning rather than just file paths.
The toolkit is specifically designed for Claude Code and uses hooks to enforce memory-first workflows, preventing the model from wasting tokens on unnecessary file exploration. It includes specialized tools like the /healer skill for diagnostics and the /eldar command to audit project setup and guidance. Through features like SONA and MicroLoRA, the system learns from task outcomes to improve its routing decisions over time, making it a specialized companion for local development workflows on macOS, Linux, and Windows.
What you can do with it
- 1Audit project setupAsk the AI to check if your project documentation and technology stack are correctly configured for Claude to use.
- 2Automate GitHub issuesHand a GitHub issue to the agent to research, implement, test, and create a pull request automatically.
- 3Diagnose installation errorsRun a diagnostic check to verify the orchestration toolkit is wired up correctly and fix any issues automatically.
- 4Implement spec-driven developmentTrigger a cycle that moves from a specification to a plan and then to implementation with enforced verification gates.
Written from the project's README. Every use case is checked against a quote from it.
How to install MoFlo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MoFlo MCP in Claude Code
$ claude mcp add moflo -- npx -y mofloInstall MoFlo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"moflo": {
"command": "npx",
"args": [
"-y",
"moflo"
]
}
}
}Install MoFlo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"moflo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"moflo"
]
}
}
}Install MoFlo MCP in VS Code CLI
$ code --add-mcp '{"name":"moflo","type":"stdio","command":"npx","args":["-y","moflo"]}'Install MoFlo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"moflo": {
"command": "npx",
"args": [
"-y",
"moflo"
]
}
}
}Install MoFlo MCP in Codex
$ codex mcp add moflo -- npx -y mofloInstall MoFlo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.moflo] command = "npx" args = ["-y", "moflo"]
Install MoFlo MCP in Gemini CLI
$ gemini mcp add -s user moflo npx -- -y mofloInstall MoFlo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"moflo": {
"command": "npx",
"args": [
"-y",
"moflo"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for moflo 4.13.7 in an isolated container with no network and no keys. It answered and listed 121 tools.
MoFlo MCP tools 121
Read from the server with tools/listagent_spawnSpawn a new agent with intelligent model selection
agent_terminateTerminate an agent on the coordinator (force / grace-period supported; reassigns active tasks)
agent_statusGet agent status from the coordinator (workload, health, last heartbeat, optional metrics)
agent_listList coordinator-tracked agents (with status / type / domain filters and pagination)
agent_poolManage agent pool
agent_healthCheck agent health
swarm_initInitialize the swarm coordinator (idempotent — returns the existing swarmId on re-init)
swarm_statusGet live swarm status from the coordinator (agent + task counts, topology, metrics)
swarm_healthCheck swarm health status
swarm_scaleScale swarm agents up or down with gradual / immediate / adaptive strategy
memory_storeStore a value in memory with vector embedding for semantic search (node:sqlite + HNSW backend). Upserts by default — pass upsert:false to fail on duplicate keys. Optional `metadata` lets chunk-row producers set the navigation fields (parentDoc, prevChunk, nextChunk, siblings, …) that `memory_get_neighbors` reads.
memory_retrieveRetrieve the full value for a SPECIFIC key. For chunk entries, prefer `memory_get_neighbors` for traversal — bulk-retrieving search hits is a protocol violation. The returned `navigation` object lets you keep traversing. Non-chunk entries instead return their parsed `metadata` object (null when absent), which is where structured records — e.g. a `/verify` per-criterion verdict — live; `value` stays human-readable. See `.claude/guidance/moflo-memory-protocol.md`.
Show all 121 toolsShow fewer tools
memory_searchSemantic vector search using HNSW approximate-nearest-neighbor (ANN) index. On chunk hits (non-null `navigation`) you MUST get adjacent context via chunk traversal, never a full-doc `Read`: prefer `expand: "neighbors"` in THIS call (cheapest — inlines prev/next), else `memory_get_neighbors`. Bulk `memory_retrieve` per hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.
memory_get_neighborsTraverse the chunk graph in one call: fetch the requested neighbors (prev/next/siblings/parent/children) of a chunk key. Returns success:false if the source is not a chunk.
memory_deleteDelete a memory entry by key
memory_listList memory entries with optional filtering
memory_statsGet memory storage statistics including HNSW index status
hooks_pre-editGet context and agent suggestions before editing a file
hooks_post-editRecord editing outcome for learning
hooks_pre-commandAssess risk before executing a command
hooks_post-commandRecord command execution outcome
hooks_routeRoute task to optimal agent using semantic similarity (native HNSW or pure JS)
hooks_metricsReturn a placeholder learning-metrics dashboard. SYNTHETIC: every value is a hardcoded literal. `period` is accepted and ignored, so 1h and 30d return identical numbers; nothing here is counted, routed or executed.
hooks_listList all registered hooks
hooks_pre-taskRecord task start and get agent suggestions with intelligent model routing (ADR-026)
hooks_post-taskRecord task completion for learning
hooks_explainExplain routing decision with full transparency
hooks_pretrainAnalyze repository to bootstrap intelligence (4-step pipeline)
hooks_build-agentsGenerate optimized agent configurations from pretrain data
hooks_transferTransfer learned patterns from another project
hooks_session-startInitialize a new session and auto-start daemon
hooks_session-endEnd current session, stop daemon, and persist state
hooks_session-restoreRestore a previous session
hooks_intelligenceMoVector intelligence system status. SYNTHETIC: the "real" counts read `.moflo/memory/store.json`, a JSON store this version no longer writes, so they resolve to zeros rather than reflecting the memory backend. `implementationStatus` is a hardcoded list asserting all twelve subsystems work, checked against nothing.
hooks_intelligence-resetReset intelligence learning state. SYNTHETIC: NOTHING IS RESET. This handler has no side effects — no trajectory, pattern or index entry is cleared, and the counts below are hardcoded literals, not a tally of what was removed. Do not treat a call to this tool as having cleared any state.
hooks_intelligence_pattern-storeStore pattern in ReasoningBank (HNSW-indexed)
hooks_intelligence_pattern-searchSearch patterns using REAL vector search (HNSW when available, brute-force fallback)
hooks_worker-listList all 12 background workers with status and capabilities
hooks_worker-dispatchDispatch a background worker for analysis/optimization tasks
hooks_worker-statusGet status of a specific worker or all active workers
hooks_worker-detectDetect worker triggers from user prompt (for UserPromptSubmit hook)
hooks_worker-cancelCancel a running worker
hooks_model-routeRoute task to optimal Claude model (haiku/sonnet/opus) based on complexity
hooks_model-outcomeRecord model routing outcome for learning
hooks_model-statsGet model routing statistics
task_createCreate a new task and submit it to the coordinator
task_statusGet task status from the coordinator
task_listList tasks with filters
task_completeMark a task as completed and record its result
task_assignAssign a task to a specific agent or to a domain pool
task_orchestrateSubmit multiple tasks in one call; load-balanced across available agents
task_cancelCancel a task
task_retryResubmit a finished task to the coordinator as a new task
task_summaryCounts of tasks by status, as used by the status dashboard
session_saveSave current session state
session_restoreRestore a saved session
session_listList saved sessions
session_deleteDelete a saved session
session_currentResolve the current session (the most recently saved one)
session_exportExport a saved session as a portable object
session_importImport a session object previously produced by session_export
hive-mind_spawnSpawn workers and automatically join them to the hive-mind (combines agent/spawn + hive-mind/join)
hive-mind_initInitialize the hive-mind collective
hive-mind_statusGet hive-mind status
hive-mind_joinJoin an agent to the hive-mind
hive-mind_leaveRemove an agent from the hive-mind
hive-mind_consensusPropose or vote on consensus
hive-mind_broadcastBroadcast message to all workers
hive-mind_shutdownShutdown the hive-mind and terminate all workers
hive-mind_memoryAccess hive shared memory (backed by Memory DB)
hive-mind_taskSubmit a task to the hive, optionally gated on worker consensus
spell_castCast a spell from a YAML/JSON scroll, grimoire name/abbreviation, or inline incantation
spell_createScribe a new spell definition from steps (returns YAML scroll)
spell_executeExecute a spell from a definition object directly
spell_statusScry the execution status of a cast spell
spell_listList available spells from the grimoire and recent castings
spell_suspendSuspend a running spell (converts to dispel — spells run to completion)
spell_resumeResume a spell (re-casts from beginning — mid-spell resume not yet supported)
spell_cancelDispel (cancel) a running spell
spell_templateBrowse spell templates from the grimoire
spell_acceptAccept a spell's permissions after reviewing the risk analysis. Required before first execution.
aidefence_scanScan input text for AI manipulation threats (prompt injection, jailbreaks, PII). Returns threat assessment with <10ms latency.
aidefence_analyzeDeep analysis of input for specific threat types with similar pattern search and mitigation recommendations.
aidefence_statsGet AIDefence detection and learning statistics.
aidefence_learnRecord detection feedback for pattern learning. Improves future detection accuracy.
aidefence_is_safeQuick boolean check if input is safe. Fastest option for simple validation.
aidefence_has_piiCheck if input contains PII (emails, SSNs, API keys, passwords, etc.).
system_healthProbe moflo components (memory, MCP server, daemon, swarm) and report the observed state of each
neural_predictCompute a real embedding for the input text via the embedding service
neural_patternsGet or manage neural patterns
neural_statusGet neural system status
performance_reportReport measured CPU, memory and heap usage for this process
performance_benchmarkRun performance benchmarks
moflodb_healthGet MofloDb v3 controller health status including cache stats and attestation count
moflodb_controllersList all MofloDb v3 controllers and their initialization status
moflodb_pattern-storeStore a pattern directly via ReasoningBank controller
moflodb_pattern-searchSearch patterns via ReasoningBank controller with BM25+semantic hybrid
moflodb_feedbackRecord task feedback for learning via LearningSystem + ReasoningBank controllers
moflodb_causal-edgeRecord a causal edge between two memory entries via CausalMemoryGraph
moflodb_routeRoute a task via MofloDb SemanticRouter or LearningSystem recommendAlgorithm
moflodb_session-startStart a session with ReflexionMemory episodic replay
moflodb_session-endEnd session, persist to ReflexionMemory, trigger NightlyLearner consolidation
moflodb_hierarchical-storeStore to hierarchical memory with tier (working, episodic, semantic)
moflodb_hierarchical-recallRecall from hierarchical memory with optional tier filter
moflodb_consolidateRun memory consolidation to promote entries across tiers and compress old data
moflodb_batchBatch-insert episodes into the MofloDb bridge store. Use memory_delete to remove entries and memory_store to overwrite them.
moflodb_context-synthesizeSynthesize context from stored memories for a given query
moflodb_semantic-routeRoute an input via MofloDb SemanticRouter for intent classification
progress_checkCalculate moflo implementation progress (CLI commands, MCP tools, hooks, packages, DDD coverage)
progress_summaryHuman-readable summary of moflo implementation progress
progress_syncRecalculate implementation progress and persist it to .moflo/metrics/v3-progress.json
hooks_coverage-gapsList every file below the coverage threshold, with a suggested test agent per file
hooks_coverage-routeRoute a task to an agent using the project coverage report to prioritise the weakest files
hooks_coverage-suggestSuggest coverage improvements for files under a path, ranked by priority
memory_exportExport memory entries to a JSON or CSV file on disk
memory_importImport memory entries from a file written by memory_export
memory_cleanupFind and optionally delete expired, stale, or unusable memory entries. Durable namespaces (learnings, knowledge) are exempt from the age-based buckets unless named via `namespace`; TTL-expired rows are collected everywhere.
memory_compressReclaim memory database space (SQLite VACUUM) and optionally rebuild the HNSW index
memory_detailed-statsMemory store statistics with per-namespace counts, on-disk size, and measured search latency
analyze_diffAnalyse a git diff for risk, change classification, and suggested reviewers
mcp_statusReport whether the moflo MCP server is running, and on which transport
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubMoFlo
A standalone, opinionated AI agent orchestration toolkit for Claude Code, optimized for local development.
TL;DR
MoFlo makes Claude Code remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run flo init, restart Claude Code, and everything just works: your docs and code are indexed on session start so Claude can search them instantly, gates prevent Claude from wasting tokens on blind exploration, task outcomes feed back into routing so it picks the right agent type next time, and context depletion warnings tell you when to start a fresh session. No configuration, no API keys, no cloud services — it all runs locally on your machine.
Quickstart
npm install --save-dev moflo
flo init
Restart Claude Code. That's it — memory, indexing, gates, and routing are all active.
Or — just ask Claude to install MoFlo into your project and initialize it!
To verify everything is running, run the /healer skill inside Claude Code (or flo healer from the CLI) after restarting — it runs full diagnostics. If anything fails, run /healer --fix to automatically fix issues.
Next Step: Consult the Eldar
After installing moflo, the single highest-leverage thing you can do for the best experience is run /eldar inside a Claude Code session.
Where /healer (or flo healer from the CLI) verifies that moflo itself is wired up correctly, /eldar audits how Claude is set up to actually use your project — guidance docs, CLAUDE.md, memory namespaces, hook/MCP wiring, model routing, and whether every technology in your stack (TypeScript, Python, Rust, Go, etc.) has matching guidance for Claude to lean on. The stack → guidance cross-reference alone is often the difference between "Claude feels lost in this codebase" and "Claude knows this codebase".
/eldar # Read-only audit; categorized findings, severity-ranked
/eldar --fix # Interactive triage — pick what to fix and the Eldar walk you through it
Run it on day one in any new project, any time Claude feels off, or as a periodic health check. Outside of the core install, this is the most impactful thing moflo offers — full details in the /eldar section further down.
Opinionated Defaults
MoFlo makes deliberate choices so you don't have to:
- Fully self-contained — No external services, no cloud dependencies, no API keys. Everything runs locally on your machine.
- Minimal dependencies — small runtime dep set, all WASM or prebuilt binaries. No native compilation, no
node-gyp, no platform-specific build steps. - Node.js runtime — Targets Node.js specifically. All scripts, hooks, and tooling are JavaScript/TypeScript. No Python, no Rust binaries, no native compilation.
- node:sqlite (built-in) — The memory database uses Node 22's built-in SQLite engine. No
better-sqlite3native bindings to compile, no WASM round-trip, no platform-specific build steps. Works identically on Windows, macOS, and Linux. - Neural embeddings by default — 384-dimensional embeddings using
all-MiniLM-L6-v2. No hash fallback, no peer-optional setup, no install prompts — real semantic search works out of the box. Apostinstallstep trims the embedding runtime to your platform and strips GPU-only libraries the runtime never loads, reclaiming roughly 340 MB on Linux and 150 MB on Windows from a fresh install. SetMOFLO_NO_PRUNE=1to skip the trim, orONNXRUNTIME_NODE_INSTALL_CUDA=trueto keep CUDA GPU support. - Full learning stack wired up OOTB — All configured and functional from
flo init, no manual setup:- SONA (Self-Optimizing Neural Architecture) — learns from task trajectories
- MicroLoRA — fast rank-2 weight adaptations from successful patterns
- EWC++ (Elastic Weight Consolidation) — prevents catastrophic forgetting across sessions
- HNSW Vector Search — fast nearest-neighbor search over your knowledge base
- Semantic Routing — maps tasks to the right agent via learned patterns (ReasoningBank)
- Trajectory Persistence — outcomes survive across sessions
- All local, no GPU, no API keys, no external services.
- Memory-first — Claude must search what it already knows before exploring files. Enforced by hooks, not just instructions.
- Task registration before agents — Sub-agents can't spawn until work is tracked. Prevents runaway agent proliferation.
- Learned routing — Task outcomes feed back into the routing system automatically. No manual configuration needed — it gets smarter with use.
- Incremental indexing — Guidance and code map indexes run on every session start but skip unchanged files. Fast after the first run.
- Claude Code is the only target — MoFlo is built and shipped for Anthropic's Claude Code (CLI, IDE extensions, web). It is not a Claude Desktop integration: nothing reads from or writes to
~/.claude/claude_desktop_config.jsonor%APPDATA%/Claude/, and adding paths there is always a bug. The MCP tools, memory system, and hooks could in principle work with any MCP-capable client, but Claude Code is the only surface we author for, test against, or accept bug reports on. - GitHub-oriented — The
/floskill, PR automation, and issue tracking are built around GitHub. With Claude's help, you can adapt them to your own issue tracker and source control system. - Cross-platform — Works identically on macOS, Linux, and Windows.
Features
| Feature | What It Does |
|---|---|
| Semantic Memory | 384-dim domain-aware embeddings. Store knowledge, search it instantly. |
| Reflection | Distills durable lessons from your sessions into searchable memory — automatically (auto-meditate), or on demand with /meditate. |
| Cross-Install Sharing | Durable learnings follow you across git worktrees automatically (no setup) — and across your own machines or a whole team via flo memory sync or a git-tracked artifact. Structural namespaces stay local. Full documentation → |
| Code Navigation | Indexes your codebase structure so Claude can answer "where does X live?" without Glob/Grep. |
| Guidance Indexing | Chunks your project docs (.claude/guidance/, docs/) and makes them searchable. |
| Gates | Enforces memory-first and task-creation patterns via Claude Code hooks. Prevents Claude from skipping steps. |
| Learned Routing | Routes tasks to the right agent type. Learns from outcomes — gets better over time. |
| Spell Engine | Define multi-step automations as YAML — shell commands, agent spawns, conditionals, loops, memory ops. Full documentation → |
/flo Skill |
Execute GitHub issues through a full process: research → enhance → implement → test → simplify → PR. (Also available as /fl.) |
| Spec-Driven Development | /flo -sd runs a spec → plan → implement → verify cycle with memory-indexed artifacts. Opt-in, but once armed both halves are enforced: an implement gate blocks source edits until the plan is reviewed, and verify-before-done gates the PR. Human review is optional (sdd.human_checkpoints, off by default); spec+plan auto-embed into the PR body (embed_in_pr), or point sdd.specs_dir at a tracked path. Details → |
| Context Tracking | Monitors context window usage (FRESH → MODERATE → DEPLETED → CRITICAL) and advises accordingly. |
| Cross-Platform | Works on macOS, Linux, and Windows. |
Getting Started
1. Install and init
npm install --save-dev moflo
flo init
flo init automatically scans your project to find where your guidance, code, and tests live, then writes the results into moflo.yaml. It looks for:
| What | Directories it checks | Default if none found |
|---|---|---|
| Guidance | .claude/guidance, docs/guides, docs, architecture, adr, .cursor/rules |
.claude/guidance |
| Source code | src, packages, lib, app, apps, services, server, client |
src |
| Tests | tests, test, __tests__, spec, e2e, plus __tests__ dirs inside src/ |
tests |
| Languages | Scans detected source dirs for file extensions | .ts, .tsx, .js, .jsx |
It also generates:
| Generated File | Purpose |
|---|---|
moflo.yaml |
Project config with detected guidance/code locations |
.claude/settings.json |
Gate hooks for Claude Code |
.claude/skills/flo/ |
The /flo issue execution skill (also /fl) |
CLAUDE.md section |
Teaches Claude how to use MoFlo |
.gitignore entries |
Excludes MoFlo state directories |
In interactive mode (flo init without --yes), it shows what it found and lets you confirm or adjust before writing.
Migrating from Claude Flow / Ruflo
If flo init detects an existing .claude/settings.json or .claude-flow/ directory (from a prior Claude Flow or Ruflo installation), it treats the project as already initialized and runs in update mode — merging MoFlo's hooks and configuration into your existing setup without overwriting your data. Specifically:
- Hooks — If your
.claude/settings.jsonalready has MoFlo-style gate hooks (flo gate), the hooks step is skipped. Otherwise, MoFlo's hooks are written into the file (existing non-MoFlo hooks are not removed). - MCP servers — MoFlo registers itself as the
mofloserver in.mcp.json. If you hadclaude-floworrufloMCP servers configured previously, those entries remain untouched — you can remove them manually once you've verified MoFlo is working. The/healerskill (orflo healerfrom the CLI) checks for themofloserver specifically. - Config files —
moflo.yaml,CLAUDE.md, and.claude/skills/flo/follow the same skip-if-exists logic. Use--forceto regenerate them.
To force a clean re-initialization over an existing setup:
flo init --force
First-run heads-up: brief CPU spike during initial indexing
The very first time MoFlo runs in your project — typically right after flo init and the next session start — it builds the initial guidance, code map, and test indexes from scratch and generates 384-dim embeddings for every chunk. On a medium-sized project this takes one to a few minutes and you may see elevated CPU during that window. It runs in the background, so you can start working immediately; you just might hear your fans for a bit.
After that first pass, indexing is incremental and lazy — every subsequent session start only re-processes files that actually changed since the last run, which typically finishes in under a second with no perceptible CPU activity. The big one-time cost is a deliberate trade: pay it once, then every future session opens with your project already searchable by meaning.
Tip: Let that initial indexing finish before running
/healer(orflo healer). Healer's embeddings and semantic-quality checks expect the indexes to exist — if you run it mid-build it may flag warnings that resolve themselves the moment indexing completes.
2. Review your guidance and code settings
Open moflo.yaml to see what init detected. The two key sections:
Guidance — documentation that helps Claude understand your project (conventions, architecture, domain context):
guidance:
directories:
- .claude/guidance # project rules, patterns, conventions
- docs # general documentation
Code map — source files to index for "where does X live?" navigation:
code_map:
directories:
- src # your source code
- packages # shared packages (monorepo)
extensions: [".ts", ".tsx"]
exclude: [node_modules, dist, .next, coverage]
Tests — test files to index for "what tests cover X?" reverse mapping:
tests:
directories:
- tests # your test files
- __tests__ # jest-style test dirs
patterns: ["*.test.*", "*.spec.*", "*.test-*"]
extensions: [".ts", ".tsx", ".js", ".jsx"]
exclude: [node_modules, coverage, dist]
namespace: tests
MoFlo chunks your guidance files into semantic embeddings, indexes your code structure, and maps test files back to their source targets — so Claude searches your knowledge base before touching any files. Adjust these directories to match your project:
# Monorepo with shared docs
guidance:
directories: [.claude/guidance, docs, packages/shared/docs]
code_map:
directories: [packages, apps, libs]
# Backend + frontend
code_map:
directories: [server/src, client/src]
3. Index and verify
flo memory index-guidance # Index your guidance docs
flo memory code-map # Index your code structure
flo healer # Verify everything works (alias: flo doctor)
Both indexes run automatically at session start after this, so you only need to run them manually on first setup or after major structural changes. The first index may take a minute or two on large codebases (1,000+ files) but runs in the background — you can start working immediately. Subsequent indexes are incremental and typically finish in under a second. To reindex everything at once:
flo memory refresh # Reindex all content, rebuild embeddings, cleanup, vacuum
Auto-Indexing
MoFlo automatically indexes three types of content on every session start, so your AI assistant always has up-to-date knowledge without manual intervention.
What gets indexed
| Index | Content | What it produces | Namespace |
|---|---|---|---|
| Guidance | Markdown files in your guidance directories (.claude/guidance/, docs/, etc.) |
Chunked text with 384-dim semantic embeddings — enables natural-language search across your project documentation | guidance |
| Code map | Source files in your code directories (src/, packages/, etc.) |
Structural index of exports, classes, functions, and types — enables "where does X live?" navigation without Glob/Grep | code-map |
| Tests | Test files matching configured patterns (*.test.*, *.spec.*) |
Reverse mapping from test files to their source targets — enables "what tests cover X?" lookups | tests |
How it works
- Session start hook — When Claude Code starts a new session, MoFlo's
SessionStarthook launches the indexers sequentially in a single background process. This runs silently — you can start working immediately. - Incremental — Each indexer tracks file modification times. Only files that changed since the last index run are re-processed. The first run on a large codebase may take a minute or two; subsequent runs typically finish in under a second.
- Embedding generation — Guidance chunks are embedded using MiniLM-L6-v2 (384 dimensions, WASM). These vectors are stored in the SQLite memory database and used for semantic search.
- No blocking — The indexers run in the background and don't block your session from starting. You can begin working immediately.
Configuration
Each indexer can be toggled independently in moflo.yaml:
auto_index:
guidance: true # Index docs on session start
code_map: true # Index code structure on session start
tests: true # Index test files on session start
Set any to false to disable that indexer. The underlying data remains in memory — you just stop refreshing it automatically. You can still run indexers manually:
flo memory index-guidance # Manual guidance reindex
flo memory code-map # Manual code map reindex
flo memory refresh # Reindex everything + rebuild embeddings + vacuum
Why this matters
Without auto-indexing, Claude Code starts every session with a blank slate — it doesn't know what documentation exists, where code lives, or what tests cover which files. It resorts to Glob/Grep exploration, which burns tokens and context window on rediscovery.
With auto-indexing, Claude can search semantically ("how does auth work?") and get relevant documentation chunks ranked by similarity, or ask "where is the user model defined?" and get a direct answer from the code map — all without touching the filesystem.
Learning From Your Sessions
MoFlo turns the work you do into durable knowledge. A lesson worth keeping — a reusable pattern, a gotcha that cost you an hour, a decision and the rationale behind it — lands in the learnings memory namespace, where it's embedded and semantically searchable in every future session. Two paths feed that namespace: one you trigger, one that runs on its own.
/meditate — deliberate retrospective
Run /meditate at the end of a meaningful chunk of work. It reviews the session, distills the handful of lessons that would help a future session on a different task, deduplicates them against what's already stored, and writes the survivors to learnings. It's the curated pass — you choose when to capture, and it keeps only high-signal items (an empty reflection is a valid result, not a failure to pad).
/meditate # Review the whole session and store durable lessons
/meditate --preview # Show the candidate lessons without writing anything
/meditate <focus> # Scope the retrospective to one thread, e.g. "the auth refactor"
Auto-meditate — the automatic counterpart
Auto-meditate does the same job without being asked. While you work, a lightweight hook notices when a durable lesson emerges — a correction, an error you fixed, a decision you made. At the next session start, a brief background pass distills those into learnings using the same durability bar and dedup-then-store protocol as /meditate. It reuses your existing Claude Code session (no extra API key), runs in the background, and ships on by default.
auto_meditate:
enabled: true # Set to false to opt out — /meditate still works manually
The two are complementary: auto-meditate is the always-on safety net, /meditate is the deliberate, curated pass. Both write to the same learnings namespace and both deduplicate, so neither pollutes the other — and anything they store is available to semantic search from then on.
Sharing learnings across installations
The learnings (and knowledge) namespaces are the durable slice of memory — user-authored and worth carrying across checkouts. The rest of the DB (code-map, guidance chunks, run state) is structural or ephemeral and rebuilds cheaply, so it stays local. For ongoing sync MoFlo shares only the durable slice — never live-shares the whole moflo.db between two daemons, which would make each daemon's in-memory search index diverge.
Pick the mechanism by topology:
| You want to share across… | Use | How |
|---|---|---|
| Git worktrees / Conductor workspaces (same machine) | Automatic — nothing to set | Learnings converge across worktrees at session-start (stored at <git-common-dir>/moflo/durable.db). Override with memory.durable_path; opt out with memory.worktree_sharing: false |
| Your own laptop + desktop + CI | flo memory sync --to/--from <file> |
Export to a synced folder (Dropbox/iCloud) or a copied file, import on the other machine |
| A whole team on one repo | flo memory team-export → commit .moflo/shared/learnings/ |
Teammates' session-start import-merges it after git pull (newest edit wins; one file per entry so concurrent PRs don't conflict; author provenance retained) |
| A fresh workspace that must be ready fast | flo memory backup/restore or memory.hydrate_from |
Seed a new workspace from a whole-DB snapshot so it's searchable on session one — no cold reindex. Safe because each workspace owns its own copy (a one-time restore, not live sharing) |
Verify your setup with flo doctor -c shared-db (it warns if you've accidentally pointed at a full moflo.db for live sharing). Full guide: moflo-cross-install-memory-sharing.md.
The Gate System
MoFlo installs Claude Code hooks that run on every tool call. Together, these gates create a feedback loop that prevents Claude from wasting tokens on blind exploration and ensures it builds on prior knowledge.
Gates explained
| Gate | What it enforces | When it triggers | Why it matters |
|---|---|---|---|
| Memory-first | Claude must search the memory database before using Glob, Grep, or Read on guidance files | Before every Glob/Grep call, and before Read calls targeting .claude/guidance/ |
Prevents the AI from re-exploring files it (or a previous session) already indexed. Forces it to check what it knows first, saving tokens and context window. |
| TaskCreate-first | Claude must call TaskCreate before spawning sub-agents via the Task tool | Before every Task (agent spawn) call | Ensures every piece of delegated work is tracked. Prevents runaway agent proliferation where Claude spawns agents without a clear plan. |
| Task-status (blocks by default) | The task list Claude opened must reflect reality before the PR — every task closed, deleted, or explicitly acknowledged as deferred | Before gh pr create, whenever the session opened tasks and left some open |
A stale task list is worse than none: it reports as not-started work that is about to merge. Every other step here is gated on an artifact; this is the one that gates what the user is shown. Deliberate deferrals stay legitimate — the block prints a one-command acknowledgement. Set task_status_gate: warn to report without blocking, or off; task_create_first: false disables both halves. |
| Context tracking | Tracks conversation length and warns about context depletion | On every user prompt (UserPromptSubmit hook) | As conversations grow, AI quality degrades. MoFlo tracks interaction count and assigns a bracket (FRESH → MODERATE → DEPLETED → CRITICAL), advising Claude to checkpoint progress or start a fresh session before quality drops. |
| Routing | Analyzes each prompt and recommends the optimal agent type and model tier | On every user prompt (UserPromptSubmit hook) | Saves cost by suggesting haiku for simple tasks, sonnet for moderate ones, opus for complex reasoning — without you having to think about model selection. |
| Verify-before-done (on by default) | Claude must verify the change end-to-end (the /verify skill) before gh pr create |
Before gh pr create (docs-only diffs exempt) |
Enforces "prove it works before done." On by default since #1294 (/flo delegates to /verify and reuses its test run — no double verify). Opt out with verify_before_done: false or --no-verify. Pairs with the Spec-Driven Development cycle, which gives verification its acceptance criteria. |
| Implement gate (SDD front half) | When a run is armed for SDD, Claude must author a spec and get its plan reviewed before editing source | Before every source Write/Edit, when -sd/sdd.default armed the run |
Makes the SDD front half enforced, not advisory (#1297): a spec-gated run can't skip to implementation. No-op for non-SDD work. Opt out per-project with sdd_gate: false, per-run with --no-sdd. Pairs with verify-before-done to gate both ends of the cycle. |
MoFlo MCP questions
How do I add MoFlo MCP to Claude Code?
Run claude mcp add moflo -- npx -y moflo in your terminal. Add --scope user to make it available in every project.
How do I add MoFlo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does MoFlo MCP provide?
It exposes 121 tools, including agent_spawn, agent_terminate, agent_status, agent_list, agent_pool.
Does MoFlo require any API keys or cloud services?
No, MoFlo is fully self-contained and runs entirely locally on your machine with no external services or API keys required.
How do I verify that MoFlo is installed and working correctly?
You can run the /healer skill inside Claude Code or use flo healer from the CLI to run full diagnostics.