Bidirectional sync between Claude Code's auto memory files and AgentDB. Auto memory is a persistent directory (~/.claude/projects/<project>/memory/) where Claude writes learnings as markdown. MEMORY.md (first 200 lines) is loaded into the system prompt; topic files are read on demand.
Quick Start
import{ AutoMemoryBridge }from'@claude-flow/memory';const bridge =newAutoMemoryBridge(memoryBackend,{
workingDir:'/workspaces/my-project',
syncMode:'on-session-end',// 'on-write' | 'on-session-end' | 'periodic'
pruneStrategy:'confidence-weighted',// 'confidence-weighted' | 'fifo' | 'lru'});// Record an insight (stores in AgentDB + optionally writes to files)await bridge.recordInsight({
category:'debugging',
summary:'HNSW index requires initialization before search',
source:'agent:tester',
confidence:0.95,});// Sync buffered insights to auto memory filesconst syncResult =await bridge.syncToAutoMemory();// Import existing auto memory files into AgentDB (on session start)const importResult =await bridge.importFromAutoMemory();// Curate MEMORY.md index (stays under 200-line limit)await bridge.curateIndex();// Check statusconst status = bridge.getStatus();
Sync Modes
Mode
Behavior
on-write
Writes to files immediately on recordInsight()
on-session-end
Buffers insights, flushes on syncToAutoMemory()
periodic
Auto-syncs on a configurable interval
Insight Categories
Category
Topic File
Description
project-patterns
patterns.md
Code patterns and conventions
debugging
debugging.md
Bug fixes and debugging insights
architecture
architecture.md
Design decisions and module relationships
performance
performance.md
Benchmarks and optimization results
security
security.md
Security findings and CVE notes
preferences
preferences.md
User and project preferences
swarm-results
swarm-results.md
Multi-agent swarm outcomes
Key Optimizations
Batch import - bulkInsert() instead of individual store() calls
Pre-fetched hashes - Single query for content-hash dedup during import
Async I/O - node:fs/promises for non-blocking writes
Exact dedup - hasSummaryLine() uses bullet-prefix matching, not substring
O(1) sync tracking - syncedInsightKeys Set prevents double-write race
Prune-before-build - Avoids O(n^2) index rebuild loop
Utility Functions
import{
resolveAutoMemoryDir,// Derive auto memory path from working dir
findGitRoot,// Walk up to find .git root
parseMarkdownEntries,// Parse ## headings into structured entries
extractSummaries,// Extract bullet summaries, strip metadata
formatInsightLine,// Format insight as markdown bullet
hashContent,// SHA-256 truncated to 16 hex chars
pruneTopicFile,// Keep topic files under line limit
hasSummaryLine,// Exact bullet-prefix dedup check}from'@claude-flow/memory';
import{ MemoryGraph }from'@claude-flow/memory';const graph =newMemoryGraph({
pageRankDamping:0.85,
pageRankIterations:50,
pageRankConvergence:1e-6,
maxNodes:5000,});// Build from backend entriesawait graph.buildFromBackend(backend,'my-namespace');// Or build manually
graph.addNode(entry);
graph.addEdge('entry-1','entry-2','reference',1.0);
graph.addEdge('entry-1','entry-3','similar',0.9);// Compute PageRank (power iteration)const ranks = graph.computePageRank();// Detect communities (label propagation)const communities = graph.detectCommunities();// Graph-aware ranking: blend vector score + PageRankconst ranked = graph.rankWithGraph(searchResults,0.7);// alpha=0.7 means 70% vector score + 30% PageRank// Get most influential insights for MEMORY.mdconst topNodes = graph.getTopNodes(20);// BFS traversal for related insightsconst neighbors = graph.getNeighbors('entry-1',2);// depth=2
Edge Types
Type
Source
Description
reference
MemoryEntry.references
Explicit cross-references between entries
similar
HNSW search
Auto-created when similarity > threshold
temporal
Timestamps
Entries created in same time window
co-accessed
Access patterns
Entries frequently accessed together
causal
Learning pipeline
Cause-effect relationships
Performance
Operation
Result
Target
Graph build (1k nodes)
2.78 ms
<200 ms
PageRank (1k nodes)
12.21 ms
<100 ms
Community detection (1k)
19.62 ms
—
rankWithGraph(10)
0.006 ms
—
getTopNodes(20)
0.308 ms
—
getNeighbors(d=2)
0.005 ms
—
Agent-Scoped Memory (ADR-049)
Maps Claude Code's 3-scope agent memory directories for per-agent knowledge isolation and cross-agent transfer.
Quick Start
import{ createAgentBridge, transferKnowledge }from'@claude-flow/memory';// Create a bridge for a specific agent scopeconst agentBridge =createAgentBridge(backend,{
agentName:'my-coder',
scope:'project',// 'project' | 'local' | 'user'
workingDir:'/workspaces/my-project',});// Record insights scoped to this agentawait agentBridge.recordInsight({
category:'debugging',
summary:'Use connection pooling for DB calls',
source:'agent:my-coder',
confidence:0.95,});// Transfer high-confidence insights between agentsconst result =awaittransferKnowledge(sourceBackend, targetBridge,{
sourceNamespace:'learnings',
minConfidence:0.8,// Only transfer confident insights
maxEntries:20,
categories:['debugging','architecture'],});// { transferred: 15, skipped: 5 }
Scope Paths
Scope
Directory
Use Case
project
<gitRoot>/.claude/agent-memory/<agent>/
Project-specific learnings
local
<gitRoot>/.claude/agent-memory-local/<agent>/
Machine-local data
user
~/.claude/agent-memory/<agent>/
Cross-project user knowledge
Utilities
import{
resolveAgentMemoryDir,// Get scope directory path
createAgentBridge,// Create scoped AutoMemoryBridge
transferKnowledge,// Cross-agent knowledge sharing
listAgentScopes,// Discover existing agent scopes}from'@claude-flow/memory';// Resolve path for an agent scopeconst dir =resolveAgentMemoryDir('my-agent','project');// → /workspaces/my-project/.claude/agent-memory/my-agent/// List all agent scopes in a directoryconst scopes =awaitlistAgentScopes('/workspaces/my-project');// [{ agentName: 'coder', scope: 'project', path: '...' }, ...]