Unified memory persistence module for ruv-swarm, providing both generic SharedMemory and MCP-specific SwarmMemory implementations.
- SQLite Backend: Robust persistence with better-sqlite3
- High-Performance Caching: LRU cache with memory pressure handling
- Migration Support: Schema evolution with versioned migrations
- TTL Support: Automatic expiration of temporary data
- Tagging & Search: Flexible data organization and retrieval
- Compression: Automatic compression for large entries
- Metrics: Performance tracking and statistics
- Agent Management: Store and track swarm agents
- Task Coordination: Persistent task state and assignment
- Communication History: Inter-agent message logging
- Consensus Tracking: Decision-making history
- Neural Patterns: Store and retrieve learned patterns
- Performance Metrics: Swarm-specific analytics
The memory module is included with ruv-swarm. To use it in your project:
import { SharedMemory, SwarmMemory } from './memory/index.js';import { SharedMemory } from './memory/shared-memory.js';
// Initialize
const memory = new SharedMemory({
directory: '.hive-mind', // Storage directory
filename: 'memory.db', // Database filename
cacheSize: 1000, // Max cache entries
cacheMemoryMB: 50, // Max cache memory in MB
gcInterval: 300000, // Garbage collection interval (5 min)
});
await memory.initialize();
// Store data
await memory.store(
'user:123',
{
name
8000
: 'John Doe',
preferences: { theme: 'dark' },
},
{
namespace: 'users',
ttl: 3600, // Expires in 1 hour
tags: ['active', 'premium'],
metadata: { source: 'api' },
},
);
// Retrieve data
const user = await memory.retrieve('user:123', 'users');
// Search by pattern
const results = await memory.search({
pattern: 'user:*',
namespace: 'users',
tags: ['active'],
limit: 10,
});
// Get statistics
const stats = await memory.getStats();
// Close when done
await memory.close();import { SwarmMemory } from './memory/swarm-memory.js';
const swarm = new SwarmMemory({
swarmId: 'my-swarm',
directory: '.swarm',
});
await swarm.initialize();
// Manage agents
await swarm.storeAgent('agent-1', {
id: 'agent-1',
name: 'Code Analyzer',
type: 'analyzer',
status: 'active',
capabilities: ['code-review', 'pattern-detection'],
});
// Track tasks
await swarm.storeTask('task-1', {
id: 'task-1',
description: 'Analyze codebase',
priority: 'high',
status: 'pending',
assignedAgents: ['agent-1'],
});
// Update task progress
await swarm.updateTaskStatus('task-1', 'in_progress', {
progress: 25,
currentFile: 'src/index.js',
});
// Store learned patterns
await swarm.storePattern('pattern-1', {
id: 'pattern-1',
type: 'optimization',
confidence: 0.92,
data: {
name: 'parallel-processing',
conditions: ['large-dataset', 'cpu-intensive'],
strategy: 'worker-threads',
},
});
// Find best patterns for context
const patterns = await swarm.findBestPatterns(
{
tags: ['optimization', 'performance'],
},
5,
);
// Get comprehensive stats
const stats = await swarm.getSwarmStats();To migrate from the old CollectiveMemory or hive-mind database:
import { MemoryMigration } from './memory/migration.js';
const migration = new MemoryMigration({
dryRun: false, // Set to true to preview
verbose: true, // Show detailed progress
});
const result = await migration.migrate();
console.log('Migration result:', result);initialize()- Initialize the database and caching systemstore(key, value, options)- Store a value with optional namespace, TTL, tagsretrieve(key, namespace)- Get a value by key and namespacelist(namespace, options)- List entries in a namespacedelete(key, namespace)- Delete a specific entryclear(namespace)- Clear all entries in a namespacesearch(options)- Search entries by pattern, tags, or namespacegetStats()- Get memory statisticsbackup(filepath)- Backup the databaseclose()- Close database connection
initialized- Database initializedstored- Data stored successfullydeleted- Data deletederror- Error occurredgc- Garbage collection completed
storeAgent(agentId, data)- Store agent informationgetAgent(agentId)- Retrieve agent datalistAgents(filter)- List agents with optional filteringstoreTask(taskId, data)- Store task informationupdateTaskStatus(taskId, status, result)- Update task progressgetTask(taskId)- Retrieve task datastoreCommunication(from, to, message)- Log agent communicationstoreConsensus(id, decision)- Store consensus decisionstorePattern(id, pattern)- Store neural patternupdatePatternMetrics(id, success)- Update pattern performancefindBestPatterns(context, limit)- Find relevant patternsgetSwarmStats()- Get swarm-specific statisticsexportSwarmState()- Export complete swarm stateimportSwarmState(state)- Import swarm state
{
directory: '.hive-mind', // Storage directory
filename: 'memory.db', // Database file
cacheSize: 1000, // Max cached entries
cacheMemoryMB: 50, // Max cache memory
compressionThreshold: 10240, // Compress if larger (bytes)
gcInterval: 300000, // GC interval (ms)
enableWAL: true, // Use Write-Ahead Logging
enableVacuum: true // Auto-vacuum database
}Inherits all SharedMemory options plus:
{
swarmId: 'my-swarm', // Swarm identifier
mcpMode: true // Enable MCP features
}- Caching: Frequently accessed data is cached in memory
- Indexing: Key database fields are indexed for fast queries
- Compression: Large entries are automatically compressed
- Garbage Collection: Expired entries are cleaned periodically
- Connection Pooling: Prepared statements reduce overhead
- Memory Management: LRU eviction prevents unbounded growth
id- Auto-incrementing primary keykey- Unique key within namespacenamespace- Data namespacevalue- Stored value (JSON or string)type- Value type (json/string)metadata- Additional metadata (JSON)tags- Search tags (JSON array)created_at- Creation timestampupdated_at- Last update timestampaccessed_at- Last access timestampaccess_count- Number of accessesttl- Time to live in secondsexpires_at- Expiration timestampcompressed- Compression flagsize- Data size in bytes
- Use Namespaces: Organize data logically
- Set TTLs: Use expiration for temporary data
- Tag Data: Enable efficient searching
- Monitor Stats: Track performance metrics
- Regular Backups: Backup important da 4223 ta
- Close Properly: Always close connections
- Database Locked: Ensure only one process accesses the database
- Memory Growth: Check cache settings and TTLs
- Slow Queries: Review indexes and search patterns
- Migration Errors: Run with
dryRun: truefirst
Enable verbose logging:
memory.on('error', console.error);
memory.on('stored', console.log);
memory.on('gc', console.log);Part of the ruv-swarm project. See main LICENSE file.