| name | memory-patterns |
| description | Persistent memory patterns for moflo agents — session memory, long-term knowledge, pattern learning, and cross-session context via moflo's sql.js + HNSW vector store. Use when building stateful agents or assistants that need to remember across runs. |
MoFlo Memory Patterns
Persistent, semantically-searchable memory for moflo-enabled projects. Backed by .swarm/memory.db (sql.js + HNSW vector index) and exposed through MCP tools.
Core API
Three things to know:
-
MCP tools — call from Claude Code sessions:
mcp__moflo__memory_store { key, value, namespace?, tags?, ttl?, upsert? }
mcp__moflo__memory_search { query, namespace?, limit?, threshold? } — semantic, HNSW-backed
mcp__moflo__memory_retrieve { key, namespace? } — exact key lookup
mcp__moflo__memory_list { namespace?, limit? }
mcp__moflo__memory_delete { key, namespace? }
mcp__moflo__memory_stats {}
-
CLI — flo-search "<query>" --namespace <ns> for quick semantic lookup from the shell.
-
Namespaces — namespace + key is the unique identity. Default namespaces shipped by moflo: learnings, patterns, guidance, code-map. (knowledge is a deprecated alias — writes are transparently redirected to learnings.) Create your own for application memory (e.g. app:sessions, app:users).
Pattern 1: Session Memory
Rolling per-conversation memory with TTL so old sessions expire:
await mcp.memory_store({
namespace: 'app:sessions',
key: `${sessionId}:msg:${turnIndex}`,
value: { role, content, ts: Date.now() },
ttl: 60 * 60 * 24 * 7,
});
const all = await mcp.memory_list({ namespace: 'app:sessions' });
const current = all.filter(t => t.key.startsWith(`${sessionId}:`));
Why namespace-per-use: search scope stays small and delete-by-namespace becomes memory_list + memory_delete in a loop.
Pattern 2: Long-Term Knowledge
Facts that should survive any session and be findable by meaning, not exact key:
await mcp.memory_store({
namespace: 'learnings',
key: 'auth:session-token-rotation',
value: 'Session tokens are rotated every 15 minutes by the auth middleware. Refresh happens transparently on the client.',
tags: ['auth', 'security'],
upsert: true,
});
const hits = await mcp.memory_search({
namespace: 'learnings',
query: 'how do auth tokens refresh?',
limit: 5,
threshold: 0.4,
});
upsert: true is the norm — you're updating your own knowledge, not guarding against collisions.
Pattern 3: Pattern Learning (store + promote)
Capture what worked, then let the next run find it:
await mcp.memory_store({
namespace: 'patterns',
key: `${patternType}:${shortHash(signature)}`,
value: {
signature,
approach,
outcome: 'success',
occurrences: 1,
},
tags: [patternType],
upsert: true,
});
const similar = await mcp.memory_search({
namespace: 'patterns',
query: currentTaskDescription,
limit: 3,
threshold: 0.5,
});
On repeated hits, read the existing entry, increment occurrences, and upsert.
Pattern 4: Context Recall at Prompt Start
moflo's gate hooks enforce "search memory before exploring files." Mirror that in your own agents:
async function beforeTask(description: string) {
const [guidance, patterns, codeMap] = await Promise.all([
mcp.memory_search({ namespace: 'guidance', query: description, limit: 5 }),
mcp.memory_search({ namespace: 'patterns', query: description, limit: 5 }),
mcp.memory_search({ namespace: 'code-map', query: description, limit: 8 }),
]);
return { guidance, patterns, codeMap };
}
This is the same fan-out the /flo spell does — cheap (HNSW, parallel) and replaces a lot of exploratory Glob/Grep.
Anti-Patterns
- Don't put large blobs in
value. Store pointers/keys — the embedding is built from the value string, and huge values bloat the index.
- Don't search without a namespace. Cross-namespace search mixes
guidance (prose) with patterns (structured) — signal collapses.
- Don't use sequential numeric keys if you also want semantic search over them. Pick keys humans/agents would search for by meaning.
- Don't use
ttl on knowledge you want long-lived. TTL is for sessions, ephemeral cache, WIP notes.
Persistence & Indexing
- File:
.swarm/memory.db at project root (sql.js).
- Embeddings: built by cli's embeddings module; indexed with HNSW from
src/cli/memory/.
- Cold-start cost: ~5 seconds to initialize HNSW. Tests should share a single instance (
beforeAll, not beforeEach).
- Namespace isolation: each namespace is a logical partition, but the HNSW index spans the table. Query time scales with
limit and threshold, not total row count.
See Also
vector-search skill — RAG patterns over your own documents
memory-optimization skill — HNSW tuning, quantization, batch ops
.claude/guidance/moflo-core-guidance.md — CLI/MCP reference