# Core package (required)
npm install [email protected]

# Optional native dependencies for maximum performance
npm install hnswlib-node@^3.0.0 better-sqlite3@^11.0.0

import { AgentDBBackend } from '@claude-flow/memory';

const backend = new AgentDBBackend({
  dbPath: './data/memory.db',
  namespace: 'default',
  vectorDimension: 1536, // For OpenAI embeddings
  hnswM: 16,
  hnswEfConstruction: 200,
  hnswEfSearch: 100,
  embeddingGenerator: async (text) => {
    // Your embedding function
    return embeddings.embed(text);
  },
});

await backend.initialize();

import { HybridBackend } from '@claude-flow/memory';

const memory = new HybridBackend({
  // SQLite for structured queries
  sqlite: {
    dbPath: './data/memory-sqlite.db',
  },

  // AgentDB for vector search
  agentdb: {
    dbPath: './data/memory-agentdb.db',
    vectorDimension: 1536,
    hnswM: 16,
    hnswEfConstruction: 200,
  },

  embeddingGenerator: embedFn,
  dualWrite: true, // Write to both backends
});

await memory.initialize();

// Structured queries go to SQLite
const user = await memory.getByKey('users', '[email protected]');

// Semantic queries go to AgentDB (150x faster)
const similar = await memory.querySemantic({
  content: 'authentication patterns',
  k: 10,
  threshold: 0.7,
});

// Hybrid queries combine both
const results = await memory.queryHybrid({
  semantic: { content: 'security vulnerabilities', k: 20 },
  structured: { namespace: 'security', createdAfter: Date.now() - 86400000 },
  combineStrategy: 'intersection',
});

// Store entries with embeddings
await backend.store({
  id: 'entry-1',
  key: 'auth-patterns',
  content: 'OAuth 2.0 implementation patterns for secure authentication',
  embedding: await embedFn('OAuth 2.0 implementation patterns...'),
  // ... other fields
});

// Semantic search by content
const results = await backend.query({
  type: 'semantic',
  content: 'user authentication best practices',
  limit: 10,
  threshold: 0.8,
});

// Or search with pre-computed embedding
const results = await backend.search(
  queryEmbedding,
  { k: 10, threshold: 0.7 }
);

// Exact match → SQLite
await memory.query({ type: 'exact', namespace: 'users', key: '[email protected]' });

// Prefix search → SQLite (indexed)
await memory.query({ type: 'prefix', keyPrefix: 'auth-' });

// Semantic search → AgentDB (HNSW)
await memory.query({ type: 'semantic', content: 'security patterns', limit: 10 });

// Hybrid → Both backends with intelligent merging
await memory.query({ type: 'hybrid', content: 'patterns', namespace: 'security' });

interface AgentDBBackendConfig {
  /** Database path (default: ':memory:') */
  dbPath?: string;

  /** Namespace for memory organization */
  namespace?: string;

  /** Force WASM backend (skip native hnswlib) */
  forceWasm?: boolean;

  /** Vector backend: 'auto', 'ruvector', 'hnswlib' */
  vectorBackend?: 'auto' | 'ruvector' | 'hnswlib';

  /** Vector dimensions (default: 1536) */
  vectorDimension?: number;

  /** HNSW M parameter (connections per layer, default: 16) */
  hnswM?: number;

  /** HNSW efConstruction (build quality, default: 200) */
  hnswEfConstruction?: number;

  /** HNSW efSearch (search quality, default: 100) */
  hnswEfSearch?: number;

  /** Enable caching */
  cacheEnabled?: boolean;

  /** Embedding generator function */
  embeddingGenerator?: EmbeddingGenerator;

  /** Maximum entries */
  maxEntries?: number;
}

// 1. Try native hnswlib (fastest)
// 2. Fallback to ruvector (fast, pure JS)
// 3. Fallback to WASM (compatible)
// 4. Fallback to in-memory brute-force (always works)

const backend = new AgentDBBackend();
await backend.initialize();

// Check availability
if (backend.isAvailable()) {
  console.log('Using AgentDB with HNSW');
} else {
  console.log('Using fallback in-memory storage');
}

const backend = new AgentDBBackend({
  // Enable quantization for 50-75% memory reduction
  quantization: {
    type: 'scalar',
    bits: 8, // 4, 8, or 16
  },
});

const backend = new AgentDBBackend({
  vectorBackend: 'hnswlib',
  distanceMetric: 'cosine', // 'cosine', 'euclidean', 'dot'
});

const health = await backend.healthCheck();

console.log(health.status); // 'healthy' | 'degraded' | 'unhealthy'
console.log(health.components.index); // HNSW index health

if (health.status === 'degraded') {
  console.log('Issues:', health.issues);
  console.log('Recommendations:', health.recommendations);
}

const stats = await backend.getStats();

console.log('Total entries:', stats.totalEntries);
console.log('Avg query time:', stats.avgQueryTime, 'ms');
console.log('Avg search time:', stats.avgSearchTime, 'ms');

if (stats.hnswStats) {
  console.log('HNSW vectors:', stats.hnswStats.vectorCount);
  console.log('HNSW build time:', stats.hnswStats.buildTime, 'ms');
}

import { MemoryMigrator } from '@claude-flow/memory';

const migrator = new MemoryMigrator(
  backend,
  {
    source: 'memory-manager',
    sourcePath: './old-memory.json',
    batchSize: 1000,
  },
  embeddingGenerator
);

const result = await migrator.migrate();

console.log('Migrated:', result.totalMigrated);
console.log('Failed:', result.totalFailed);

AgentDB not available. Install [email protected] for vector search support.

npm install [email protected]

Failed to load hnswlib-node, falling back to WASM

# Ubuntu/Debian
sudo apt-get install build-essential python3

# macOS
xcode-select --install

# Then reinstall
npm install hnswlib-node@^3.0.0

const backend = new AgentDBBackend({
  forceWasm: true, // Skip native bindings
});

# Run AgentDB backend tests
npm test -- agentdb-backend.test.ts

# Run all memory tests
npm test

# Run benchmarks
npm run bench