memory-patterns

MoFlo Memory Patterns

Persistent, semantically-searchable memory for moflo-enabled projects. Backed by .moflo/moflo.db (node:sqlite + HNSW vector index) and exposed through MCP tools.

Core API

Three things to know:

1. 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 {}

2. CLI — flo-search "<query>" --namespace <ns> for quick semantic lookup from the shell.

3. 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:

// Store a turn
await mcp.memory_store({
  namespace: 'app:sessions',
  key: `${sessionId}:msg:${turnIndex}`,
  value: { role, content, ts: Date.now() },
  ttl: 60 * 60 * 24 * 7, // 7 days
});

// Recall the session — keys sort lexicographically, so prefixing with
// sessionId groups a conversation.
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,
});

// Retrieval: semantic, not keyword
const hits = await mcp.memory_search({
  namespace: 'learnings',
  query: 'how do auth tokens refresh?',
  limit: 5,
  threshold: 0.4,
});