@monoes/memory 1.0.5 → 1.0.6

package/README.md

@@ -1,891 +1,123 @@
-# @monomind/memory
-
-[![npm version](https://img.shields.io/npm/v/@monomind/memory.svg)](https://www.npmjs.com/package/@monomind/memory)
-[![npm downloads](https://img.shields.io/npm/dm/@monomind/memory.svg)](https://www.npmjs.com/package/@monomind/memory)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-
-> High-performance memory module for Monomind V1 - LanceDB unification, HNSW indexing, vector search, self-learning knowledge graph, and hybrid SQLite+LanceDB backend (ADR-009).
-
-## Features
-
-- **Indexed Vector Search** - HNSW (Hierarchical Navigable Small World) vector index for fast similarity search
-- **Hybrid Backend** - SQLite for structured data + LanceDB for vectors (ADR-009)
-- **Auto Memory Bridge** - Bidirectional sync between Claude Code auto memory and LanceDB (ADR-048)
-- **Self-Learning** - LearningBridge connects insights to the ReasoningBank pattern store (ADR-049)
-- **Knowledge Graph** - PageRank + label propagation community detection + HippoRAG PPR re-ranking (ADR-049)
-- **Agent-Scoped Memory** - 3-scope agent memory (project/local/user) with cross-agent knowledge transfer (ADR-049)
-- **Vector Quantization** - Binary, scalar, and product quantization for 4-32x memory reduction
-- **Multiple Distance Metrics** - Cosine, Euclidean, dot product, and Manhattan distance
-- **Query Builder** - Fluent API for building complex memory queries
-- **Cache Manager** - LRU caching with configurable size and TTL
-- **Migration Tools** - Seamless migration from V2 memory systems
-- **DiskANN Backend** - SSD-resident Vamana ANN graph for million-scale entry search (arXiv:2305.04359)
-- **A-MEM Auto-Linking** - Bidirectional reference edges auto-created on store (arXiv:2409.11987)
-- **GraphRAG Community Retrieval** - Community-level summaries annotate semantic search results (arXiv:2404.16130)
-- **HippoRAG PPR Re-ranking** - Personalised PageRank re-ranks semantic results via knowledge graph (arXiv:2405.14831)
-- **Collaborative Memory Promotion** - Entries auto-promoted to team scope after 3+ agent reads/24 h (arXiv:2505.18279)
-- **Temporal Knowledge Graph** - Causal/temporal edge typing inspired by Zep/Graphiti (arXiv:2501.13956)
-- **Injection Filter** - Structural prompt-injection detection on semantic search results (arXiv:2302.12173, arXiv:2310.12815)
-
-## Installation
+# @monoes/memory
 
-```bash
-npm install @monomind/memory
-```
+[![license](https://img.shields.io/npm/l/@monoes/memory.svg?style=flat-square)](https://github.com/monoes/monomind/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-blue?style=flat-square)](https://nodejs.org)
 
-## Quick Start
-
-```typescript
-import { HNSWIndex, LanceDBAdapter, CacheManager } from '@monomind/memory';
-
-// Create HNSW index for vector search
-const index = new HNSWIndex({
-  dimensions: 1536,  // OpenAI embedding size
-  M: 16,             // Max connections per node
-  efConstruction: 200,
-  metric: 'cosine'
-});
+**Persistent memory backends for Monomind agents** — SQLite (native or WASM) key-value storage, an optional LanceDB vector backend, a pure-JS HNSW index, JSONL episodic memory, and a chunked knowledge store.
 
-// Add vectors
-await index.addPoint('memory-1', new Float32Array(embedding));
-await index.addPoint('memory-2', new Float32Array(embedding2));
+> Part of the [Monomind](https://github.com/monoes/monomind) ecosystem. The only hard dependency is `sql.js` (WASM); `better-sqlite3` and `@lancedb/lancedb` are optional and loaded dynamically when installed.
 
-// Search for similar vectors
-const results = await index.search(queryVector, 10);
-// [{ id: 'memory-1', distance: 0.05 }, { id: 'memory-2', distance: 0.12 }]
-```
+## Install
 
-## API Reference
+```bash
+npm install @monoes/memory
 
-### HNSW Index
+# optional: native SQLite and vector search
+npm install better-sqlite3 @lancedb/lancedb apache-arrow
+```
 
-```typescript
-import { HNSWIndex } from '@monomind/memory';
+## What's in the box
 
-const index = new HNSWIndex({
-  dimensions: 1536,
-  M: 16,                    // Max connections per layer
-  efConstruction: 200,      // Construction-time search depth
-  maxElements: 1000000,     // Max vectors
-  metric: 'cosine',         // 'cosine' | 'euclidean' | 'dot' | 'manhattan'
-  quantization: {           // Optional quantization
-    type: 'scalar',         // 'binary' | 'scalar' | 'product'
-    bits: 8
-  }
-});
+| Export | What it does |
+|---|---|
+| `UnifiedMemoryService` | High-level store/get/search facade backed by `LanceDBBackend` |
+| `SQLiteBackend` / `SqlJsBackend` | Structured key-value memory (native SQLite or zero-compile WASM) |
+| `LanceDBBackend` | Vector memory via `@lancedb/lancedb` (optional dependency, loaded lazily) |
+| `HNSWIndex` | Pure-JS approximate nearest-neighbor index with quantization support |
+| `EpisodicStore` | JSON-lines episodic memory — accumulates agent runs into summarized episodes |
+| `chunkDocument`, `KnowledgeStore`, `KnowledgeRetriever` | Document chunking + retrieval for knowledge bases |
+| `QueryBuilder` / `query()` | Fluent query construction (namespace, tags, threshold, sort) |
+| `CacheManager`, `TieredCacheManager` | LRU caching with size/TTL limits |
+| `createDatabase`, `getPlatformInfo` | Platform-aware provider selection (better-sqlite3 → sql.js → JSON fallback) |
+| `SwarmCheckpointer` | Persist/restore swarm agent state snapshots |
+| `MemoryMigrator` | Import from SQLite, JSON, or Markdown sources |
+| `PromptVersionStore`, `ControllerRegistry` | Prompt version history; init-level controller registry |
 
-// Add vectors
-await index.addPoint(id: string, vector: Float32Array);
-
-// Search
-const results = await index.search(
-  query: Float32Array,
-  k: number,
-  ef?: number  // Search-time depth (higher = more accurate)
-);
-
-// Search with filters
-const filtered = await index.searchWithFilters(
-  query,
-  k,
-  (id) => id.startsWith('session-')
-);
-
-// Remove vectors
-await index.removePoint(id);
-
-// Get statistics
-const stats = index.getStats();
-// { vectorCount, memoryUsage, avgSearchTime, compressionRatio }
-```
+Note: Monomind's live hook/routing hot path uses plain JSON pattern files and
+keyword-based episodic recall — the vector backends here are opt-in, used when
+an embedding generator and the optional native dependencies are provided.
 
-### LanceDB Adapter
+## Quick start — key-value memory
 
 ```typescript
-import { LanceDBAdapter } from '@monomind/memory';
-
-const adapter = new LanceDBAdapter({
-  dimensions: 1536,           // vector dimensions
-  hnswM: 16,                  // max connections per HNSW layer
-  hnswEfConstruction: 200,    // construction-time search depth
-  cacheEnabled: true,         // LRU result cache
-  cacheSize: 10000,           // max cached entries
-  cacheTtl: 300000,           // 5 minutes
-  defaultNamespace: 'default',
-  embeddingGenerator: async (text) => myEmbedder.embed(text),
-});
+import { SQLiteBackend } from '@monoes/memory';
 
-await adapter.initialize();
+const backend = new SQLiteBackend({ databasePath: './data/memory.db' });
+await backend.initialize();
 
-// Store memory — namespace is normalised to defaultNamespace when empty
-await adapter.store({
-  id: 'mem-123',
+await backend.store({
+  id: 'mem-1',
   key: 'user-preference',
   content: 'User prefers dark mode',
   type: 'semantic',
   namespace: 'preferences',
   tags: ['ui'],
-  metadata: {},
-  accessLevel: 'private',
-  createdAt: Date.now(),
-  updatedAt: Date.now(),
-  version: 1,
-  references: [],
-  accessCount: 0,
-  lastAccessedAt: Date.now(),
 });
 
-// Semantic search
-const results = await adapter.semanticSearch('dark mode preference', 10, 0.7);
-// [{ entry: MemoryEntry, score: number, distance: number }, ...]
-
-// Convenience: store from plain input (auto-generates id, timestamps)
-const entry = await adapter.storeEntry({
-  key: 'my-fact',
-  content: 'TypeScript 5+ required',
-  namespace: 'learnings',
-  type: 'semantic',
-  tags: ['setup'],
-  metadata: {},
-});
+const entry = await backend.getByKey('preferences', 'user-preference');
 ```
 
-### Cache Manager
+## Vector search (optional)
 
 ```typescript
-import { CacheManager } from '@monomind/memory';
-
-const cache = new CacheManager<MemoryEntry>({
-  maxSize: 1000,       // max entries before LRU eviction
-  ttl: 3_600_000,     // entry TTL in ms (1 hour)
-  maxMemory: 50 * 1024 * 1024, // optional memory cap (50 MB)
-  lruEnabled: true,   // enable LRU ordering (default: true)
-});
-
-// Cache operations
-cache.set('key', entry);
-const entry = cache.get('key');     // null if missing or expired
-const exists = cache.has('key');
-cache.delete('key');
-cache.clear();                      // emits 'cache:cleared' with correct previousSize
-
-// Batch prefetch
-await cache.prefetch(['k1', 'k2'], async (keys) => loadFromDB(keys));
-
-// Statistics
-const stats = cache.getStats();
-// { size, hits, misses, hitRate, evictions, memoryUsage }
+import { UnifiedMemoryService } from '@monoes/memory';
 
-// Cleanup — call on process exit to stop the internal cleanup timer
-cache.shutdown();
-```
-
-### Query Builder
-
-```typescript
-import { query, QueryTemplates } from '@monomind/memory';
-
-// Fluent query construction — produces a MemoryQuery object
-const q = query()
-  .semantic('authentication patterns')   // type = semantic, embeds content
-  .inNamespace('security')
-  .withTags(['auth', 'patterns'])
-  .ofType('semantic')
-  .threshold(0.7)
-  .limit(20)
-  .sortByNewest()                         // sortField: createdAt, sortDirection: desc
-  .build();
-
-// Exact-key lookup
-const exact = query().exact('my-key', 'my-namespace').build();
-
-// Prefix search
-const prefix = query().prefix('session-').inNamespace('sessions').build();
-
-// Sorting options
-query().semantic('...').sortBy('accessCount', 'desc').build();  // most-accessed first
-query().semantic('...').oldestFirst().build();                   // createdAt asc
-query().semantic('...').recentlyAccessed().build();              // lastAccessedAt desc
-
-// sortField and sortDirection are passed through to all backends that support them
-// (lancedb-adapter, sqlite-backend, sqljs-backend, JsonBackend)
-
-// Predefined templates
-const recent = QueryTemplates.recentInNamespace('learnings', 10);
-const stale = QueryTemplates.staleEntries('session-cache', 10);
-```
-
-### Migration
-
-```typescript
-import { MemoryMigrator, createMigrator } from '@monomind/memory';
-
-// Migrate from a legacy SQLite, JSON, or Markdown source
-const migrator = createMigrator(targetAdapter, {
-  source: 'sqlite',          // 'sqlite' | 'json' | 'markdown' | 'memory-manager' | 'swarm-memory'
-  sourcePath: './data/v2-memory.db',
-  batchSize: 100,
-  generateEmbeddings: true,  // generate vector embeddings for each entry
-  continueOnError: true,     // skip bad entries instead of aborting
-  validateData: true,
-});
-
-const result = await migrator.migrate();
-console.log(`Migrated ${result.progress.migrated} entries`);
-console.log(`Failed: ${result.progress.failed}`);
-
-```
-
-## Quantization Options
-
-```typescript
-// Binary quantization (32x compression)
-const binaryIndex = new HNSWIndex({
+// Requires @lancedb/lancedb + apache-arrow installed
+const memory = new UnifiedMemoryService({
+  persistencePath: './data/lancedb',
   dimensions: 1536,
-  quantization: { type: 'binary' }
-});
-
-// Scalar quantization (4x compression)
-const scalarIndex = new HNSWIndex({
-  dimensions: 1536,
-  quantization: { type: 'scalar', bits: 8 }
-});
-
-// Product quantization (8x compression)
-const productIndex = new HNSWIndex({
-  dimensions: 1536,
-  quantization: { type: 'product', subquantizers: 8 }
-});
-```
-
-## Auto Memory Bridge (ADR-048)
-
-Bidirectional sync between Claude Code's [auto memory](https://code.claude.com/docs/en/memory) files and LanceDB. 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
-
-```typescript
-import { AutoMemoryBridge } from '@monomind/memory';
-
-const bridge = new AutoMemoryBridge(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 LanceDB + 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 files
-const syncResult = await bridge.syncToAutoMemory();
-
-// Import existing auto memory files into LanceDB (on session start)
-const importResult = await bridge.importFromAutoMemory();
-
-// Curate MEMORY.md index (stays under 200-line limit)
-await bridge.curateIndex();
-
-// Check status
-const 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
-
-```typescript
-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 '@monomind/memory';
-```
-
-### Types
-
-```typescript
-import type {
-  AutoMemoryBridgeConfig,
-  MemoryInsight,
-  InsightCategory,
-  SyncDirection,
-  SyncMode,
-  PruneStrategy,
-  SyncResult,
-  ImportResult,
-} from '@monomind/memory';
-```
-
-## Self-Learning Bridge (ADR-049)
-
-Connects insights to the ReasoningBank pattern store. The optional neural learning system can be injected via `neuralLoader`; when none is provided, learning operations degrade to no-ops while pattern storage and retrieval continue to work.
-
-### Quick Start
-
-```typescript
-import { AutoMemoryBridge, LearningBridge } from '@monomind/memory';
-
-const bridge = new AutoMemoryBridge(backend, {
-  workingDir: '/workspaces/my-project',
-  learning: {
-    sonaMode: 'balanced',
-    confidenceDecayRate: 0.005,   // Per-hour decay
-    accessBoostAmount: 0.03,      // Boost per access
-    consolidationThreshold: 10,   // Min insights before consolidation
-  },
-});
-
-// Insights now trigger learning trajectories automatically
-await bridge.recordInsight({
-  category: 'debugging',
-  summary: 'Connection pool exhaustion on high load',
-  source: 'agent:tester',
-  confidence: 0.9,
-});
-
-// Consolidation runs JUDGE/DISTILL/CONSOLIDATE pipeline
-await bridge.syncToAutoMemory(); // Calls consolidate() first
-```
-
-### Standalone Usage
-
-```typescript
-import { LearningBridge } from '@monomind/memory';
-
-const lb = new LearningBridge(backend, {
-  // Optional: inject a custom neural learning system (structural interface).
-  // Without a neuralLoader, learning degrades to no-ops; pattern storage
-  // and ReasoningBank retrieval still work.
-  neuralLoader: async () => myNeuralLearningSystem,
-});
-
-// Boost confidence when insight is accessed
-await lb.onInsightAccessed('entry-123'); // +0.03 confidence
-
-// Apply time-based decay
-const decayed = await lb.decayConfidences('default'); // -0.005/hour
-
-// Find similar patterns via ReasoningBank
-const patterns = await lb.findSimilarPatterns('connection pooling');
-
-// Get learning statistics
-const stats = lb.getStats();
-// { totalTrajectories, activeTrajectories, completedTrajectories,
-//   totalConsolidations, accessBoosts, ... }
-```
-
-### Confidence Lifecycle
-
-| Event | Effect | Range |
-|-------|--------|-------|
-| Insight recorded | Initial confidence from source | 0.1 - 1.0 |
-| Insight accessed | +0.03 per access | Capped at 1.0 |
-| Time decay | -0.005 per hour since last access | Floored at 0.1 |
-| Consolidation | Neural pipeline may adjust | 0.1 - 1.0 |
-
-## Knowledge Graph (ADR-049)
-
-Pure TypeScript knowledge graph with PageRank and community detection. No external graph libraries required.
-
-### Quick Start
-
-```typescript
-import { AutoMemoryBridge, MemoryGraph } from '@monomind/memory';
-
-const bridge = new AutoMemoryBridge(backend, {
-  workingDir: '/workspaces/my-project',
-  graph: {
-    similarityThreshold: 0.8,
-    pageRankDamping: 0.85,
-    maxNodes: 5000,
-  },
-});
-
-// Graph builds automatically on import
-await bridge.importFromAutoMemory();
-
-// Curation uses PageRank to prioritize influential insights
-await bridge.curateIndex();
-```
-
-### Standalone Usage
-
-```typescript
-import { MemoryGraph } from '@monomind/memory';
-
-const graph = new MemoryGraph({
-  pageRankDamping: 0.85,
-  pageRankIterations: 50,
-  pageRankConvergence: 1e-6,
-  maxNodes: 5000,
-});
-
-// Build from backend entries
-await 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 + PageRank
-const ranked = graph.rankWithGraph(searchResults, 0.7);
-// alpha=0.7 means 70% vector score + 30% PageRank
-
-// Get most influential insights for MEMORY.md
-const topNodes = graph.getTopNodes(20);
-
-// BFS traversal for related insights
-const 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
-
-```typescript
-import { createAgentBridge, transferKnowledge } from '@monomind/memory';
-
-// Create a bridge for a specific agent scope
-const agentBridge = createAgentBridge(backend, {
-  agentName: 'my-coder',
-  scope: 'project', // 'project' | 'local' | 'user'
-  workingDir: '/workspaces/my-project',
-});
-
-// Record insights scoped to this agent
-await agentBridge.recordInsight({
-  category: 'debugging',
-  summary: 'Use connection pooling for DB calls',
-  source: 'agent:my-coder',
-  confidence: 0.95,
-});
-
-// Transfer high-confidence insights between agents
-const result = await transferKnowledge(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
-
-```typescript
-import {
-  resolveAgentMemoryDir,  // Get scope directory path
-  createAgentBridge,       // Create scoped AutoMemoryBridge
-  transferKnowledge,       // Cross-agent knowledge sharing
-  listAgentScopes,         // Discover existing agent scopes
-} from '@monomind/memory';
-
-// Resolve path for an agent scope
-const dir = resolveAgentMemoryDir('my-agent', 'project');
-// → /workspaces/my-project/.claude/agent-memory/my-agent/
-
-// List all agent scopes in a directory
-const scopes = await listAgentScopes('/workspaces/my-project');
-// [{ agentName: 'coder', scope: 'project', path: '...' }, ...]
-```
-
-## A-MEM Auto-Linking (arXiv:2409.11987)
-
-When `HybridBackend` is configured with an `embeddingGenerator`, every stored entry
-automatically discovers its top-3 semantic neighbors and creates bidirectional
-`references` edges — implementing the Zettelkasten note-linking structure from A-MEM.
-
-```typescript
-const backend = new HybridBackend({
-  embeddingGenerator: async (text) => myEmbeddingModel.embed(text),
-  // A-MEM auto-linking is automatically active when embeddingGenerator is set
-});
-
-// Store any entry — references are linked asynchronously, best-effort
-await backend.store(entry);
-
-// After linking, querySemantic PPR re-ranking propagates scores through the
-// newly created reference graph, improving recall for connected knowledge.
-backend.on('amem:linked', ({ id, linkedTo }) =>
-  console.log(`Linked ${id} to ${linkedTo.join(', ')}`));
-```
-
-## Injection-Safe Semantic Search
-
-Set `filterInjection: true` to remove entries containing prompt-injection patterns
-from semantic search results before they reach the agent context:
-
-```typescript
-const backend = new HybridBackend({
-  embeddingGenerator: myEmbedder,
-  filterInjection: true,    // Screen RAG results for indirect injection
-});
-
-// Filtered result — entries matching injection patterns are silently dropped
-const entries = await backend.querySemantic({ content: 'OAuth patterns', k: 10 });
-
-// Blocked entries are observable via event
-backend.on('injection:blocked', ({ id, namespace }) =>
-  securityLogger.warn(`Injection blocked from entry ${id}`));
-```
-
-Source: arXiv:2302.12173, arXiv:2310.12815 — indirect prompt injection in RAG pipelines.
-
-## GraphRAG Community Retrieval (arXiv:2404.16130)
-
-`querySemantic()` now captures community summaries from `MemoryGraph.getCommunitySummaries()`
-and annotates each returned entry with its GraphRAG community metadata. This implements
-the community-level summarisation strategy from Microsoft GraphRAG.
-
-```typescript
-const entries = await backend.querySemantic({ content: 'authentication patterns', k: 10 });
-// Each entry now carries:
-//   entry.community             — community ID string
-//   entry.communityNodeCount    — number of nodes in that community
-//   entry.communityAvgPageRank  — mean PageRank of community members
-```
-
-PPR re-ranking is handled by HippoRAG-style personalised PageRank (arXiv:2405.14831),
-which propagates query-node scores through the knowledge graph before returning results.
-
-## Collaborative Memory Promotion (arXiv:2505.18279)
-
-`HybridBackend.get(id, agentId?)` accepts an optional `agentId` parameter. When
-provided, it fires a read-tracking call to the SQLite backend, which promotes the
-entry's `AccessLevel` from `'private'` to `'team'` once **3 or more distinct agents**
-have accessed it within a 24-hour window.
-
-```typescript
-// Each agent reads with its own ID — no other change required
-const entry = await backend.get('entry-id-123', 'coder-agent');
-
-// After the third distinct agent reads it within 24 h:
-// entry.accessLevel === 'team'
-// (auto-promoted, visible to peer agents in the same namespace)
-```
-
-Collaborative promotion is transparent to callers that don't pass `agentId` —
-`get(id)` continues to work exactly as before (backwards-compatible).
-
-## Knowledge Graph & Temporal Edges (arXiv:2501.13956)
-
-`MemoryGraph` models causal and temporal relationships between entries as typed
-edges, inspired by the Zep/Graphiti episodic knowledge graph (arXiv:2501.13956).
-Edge types include `REFERENCES`, `CAUSES`, `PRECEDED_BY`, `RELATED_TO`, and
-`CONTRADICTS`, enabling episodic reasoning over the agent's memory history.
-
-```typescript
-import { MemoryGraph, type EdgeType } from '@monomind/memory';
-
-const graph = new MemoryGraph();
-graph.addEdge('plan-123', 'code-456', EdgeType.CAUSES, 0.9);
-graph.addEdge('code-456', 'test-789', EdgeType.PRECEDED_BY, 1.0);
-
-const ranked = graph.pprRerank(['plan-123'], candidates, 0.85);
-// Entries causally downstream of 'plan-123' score higher in PPR
-```
-
-## μACP Learning-Bridge Integration (arXiv:2601.03938)
-
-`LearningBridge` integrates with the μACP coordination substrate: when consolidation
-detects a pattern conflict between agents, it initiates a μACP round to resolve which
-variant to promote. The result is stored as a causal edge in `MemoryGraph`.
-
-```typescript
-// Conflict resolution is automatic during consolidation:
-await learningBridge.consolidate();
-// Internally calls MuACP.coordinate() when divergent patterns are detected,
-// then records the winning pattern as a CAUSES edge.
-```
-
-Source: arXiv:2601.03938.
-
-## Bi-Temporal Query Filtering (arXiv:2501.13956)
-
-`MemoryQuery` now supports `eventAfter` and `eventBefore` filters that operate on the
-`eventAt` field — the timestamp of *when the event occurred* (T), as opposed to
-`createdAt` which records *when the entry was ingested* (T'). This is the bi-temporal
-model from Zep/Graphiti that prevents retrieval failures when data arrives out-of-order
-or is backdated.
-
-```typescript
-const entries = await backend.query({
-  type: 'hybrid',
-  namespace: 'incidents',
-  limit: 50,
-  // Filter by WHEN THE INCIDENT HAPPENED — not when it was logged
-  eventAfter:  new Date('2026-01-01').getTime(),
-  eventBefore: new Date('2026-04-01').getTime(),
-});
-
-// Store with explicit event time (e.g. a past incident being recorded now)
-await backend.store({
-  key: 'outage-2026-02-14',
-  content: 'DB connection pool exhausted during peak traffic',
-  type: 'episodic',
-  namespace: 'incidents',
-  eventAt: new Date('2026-02-14T03:22:00Z').getTime(),  // event time
-  // createdAt is auto-set to Date.now() (ingestion time)
-  // ...
+  embeddingGenerator: async (text) => myEmbedder.embed(text),
 });
+await memory.initialize();
 ```
 
-Source: arXiv:2501.13956 — Zep/Graphiti bi-temporal knowledge graph.
-
-## MemoRAG Query Rewriting (arXiv:2409.05591)
-
-`HybridBackend` supports a `memoragRewriter` configuration option that adds a
-"draft clue" query-expansion stage before HNSW search. When configured, `querySemantic()`
-calls the rewriter to generate 2-3 reformulated sub-queries, searches HNSW independently
-for each, then fuses all ranked result lists using **Reciprocal Rank Fusion (RRF)** before
-continuing with HippoRAG PPR re-ranking and GraphRAG community annotation.
-
-This addresses the MemoRAG insight that naive RAG fails when the user query does not
-directly match any retrievable chunk — paraphrased sub-queries dramatically improve recall.
+Or use the standalone pure-JS index directly:
 
 ```typescript
-import { HybridBackend } from '@monomind/memory';
-
-const backend = new HybridBackend({
-  embeddingGenerator: myEmbedder,
-  memoragRewriter: async (query) => {
-    // Use a cheap LLM (Haiku) or deterministic rules to produce sub-queries
-    const reformulated = await callClaude({
-      model: 'claude-haiku-4-5',
-      prompt: `Generate 3 alternative search queries for: "${query}"\nRespond with a JSON array of strings.`,
-    });
-    return JSON.parse(reformulated); // e.g. ["...", "...", "..."]
-  },
-});
+import { HNSWIndex } from '@monoes/memory';
 
-// querySemantic() now automatically expands + fuses results
-const results = await backend.querySemantic({ content: 'memory leak in production' });
-// RRF-fused results from sub-queries: "heap usage spike", "GC pressure", "OOM error"
+const index = new HNSWIndex({ dimensions: 1536, M: 16, efConstruction: 200, metric: 'cosine' });
+await index.addPoint('mem-1', new Float32Array(embedding));
+const results = await index.search(queryVector, 10);
+// [{ id: 'mem-1', distance: 0.05 }, ...]
 ```
 
-Source: arXiv:2409.05591 — MemoRAG (TheWebConf 2025).
-
-## DiskANN Backend — Large-Scale ANN at Disk Scale (arXiv:2305.04359)
-
-`DiskAnnBackend` is an `IMemoryBackend` decorator that activates SSD-resident Vamana ANN search above entry-count thresholds. Wraps any existing backend (typically the long-term SQLite/LanceDB backend in `TierManager`).
-
-### Architecture
-
-- **Disk-persisted adjacency list** — Vamana graph written to `graphPath` as JSON
-- **In-memory Int8-quantised vectors** — `Map<string, Int8Array>` for fast beam search
-- **Beam search** — BFS traversal using Int8 dot-product as the candidate scorer
-- **Full-precision cosine re-ranking** — fetches raw embeddings from the delegate backend
-
-### Quick Start
+## Episodic memory
 
 ```typescript
-import { DiskAnnBackend, type DiskAnnBackendConfig } from '@monomind/memory';
-
-// Wrap any IMemoryBackend
-const diskann = new DiskAnnBackend(existingBackend, {
-  graphPath: './data/diskann.graph.json',
-  R: 32,          // Max graph degree (default: 32)
-  L: 64,          // Beam width (default: 64)
-  beamWidth: 10,  // Search beam candidates (default: 10)
-  dimensions: 128, // Vector dimensions (default: 128)
-});
-
-// All CRUD proxies through to the wrapped backend
-await diskann.store(entry);
-await diskann.get(id);
+import { EpisodicStore } from '@monoes/memory';
 
-// ANN search uses beam traversal + cosine re-ranking
-const results = await diskann.search(queryVector, { k: 5 });
-// [{ entry: MemoryEntry, score: number }, ...]
+const store = new EpisodicStore({ filePath: './data/episodes.jsonl', maxRunsPerEpisode: 20 });
+// Accumulates agent runs into episodes, one JSON object per line
 ```
 
-### TierManager Integration
-
-Pass `diskAnnConfig` to activate DiskANN on the long-term backend:
-
-```typescript
-import { TierManager } from '@monomind/memory';
-
-const tier = new TierManager(
-  longTermBackend,
-  { shortTermCapacity: 1000 },
-  {}, // PartitionedHNSW config
-  {   // DiskAnnBackendConfig — activates DiskANN
-    graphPath: './data/diskann.graph.json',
-    R: 32,
-    beamWidth: 12,
-  },
-);
-
-// tier.diskann is now populated — search() includes DiskANN results
-const results = await tier.search('authentication patterns', 10);
-```
-
-### DiskAnnBackendConfig
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `graphPath` | `'./diskann.graph.json'` | Path for persisted Vamana adjacency list |
-| `R` | `32` | Max out-degree per node |
-| `L` | `64` | Beam width during construction |
-| `beamWidth` | `10` | Beam width during search |
-| `dimensions` | `128` | Vector dimensions |
-
-## Performance Benchmarks
-
-| Operation | V2 Performance | V1 Performance | Improvement |
-|-----------|---------------|----------------|-------------|
-| Vector Search | 150ms | <1ms | **150x** |
-| Bulk Insert | 500ms | 5ms | **100x** |
-| Memory Write | 50ms | <5ms | **10x** |
-| Cache Hit | 5ms | <0.1ms | **50x** |
-| Index Build | 10s | 800ms | **12.5x** |
-
-### ADR-049 Benchmarks
-
-| Operation | Actual | Target | Headroom |
-|-----------|--------|--------|----------|
-| Graph build (1k nodes) | 2.78 ms | <200 ms | **71.9x** |
-| PageRank (1k nodes) | 12.21 ms | <100 ms | **8.2x** |
-| Insight recording | 0.12 ms/each | <5 ms/each | **41.0x** |
-| Consolidation | 0.26 ms | <500 ms | **1,955x** |
-| Confidence decay (1k) | 0.23 ms | <50 ms | **215x** |
-| Knowledge transfer | 1.25 ms | <100 ms | **80.0x** |
-
-## TypeScript Types
+## Query builder
 
 ```typescript
-import type {
-  // Core entry and query types
-  MemoryEntry, MemoryEntryInput, MemoryEntryUpdate,
-  MemoryQuery, MemoryType, AccessLevel,
-  SearchResult, SearchOptions,
+import { query } from '@monoes/memory';
 
-  // Query builder sort fields
-  SortField,        // 'createdAt' | 'updatedAt' | 'lastAccessedAt' | 'accessCount' | 'key' | 'score'
-  SortDirection,    // 'asc' | 'desc'
-
-  // HNSW
-  HNSWConfig, HNSWStats, QuantizationConfig, DistanceMetric,
-
-  // Backend interfaces
-  IMemoryBackend, BackendStats, HealthCheckResult,
-
-  // Cache
-  CacheConfig, CacheStats,
-
-  // Auto Memory Bridge (ADR-048)
-  AutoMemoryBridgeConfig, MemoryInsight, InsightCategory,
-  SyncMode, SyncResult, ImportResult,
-
-  // Agent Scope (ADR-049)
-  AgentMemoryScope, AgentScopedConfig,
-  TransferOptions, TransferResult,
-
-  // Learning Bridge (ADR-049)
-  LearningBridgeConfig, ConsolidateResult, PatternMatch,
-
-  // Knowledge Graph (ADR-049)
-  MemoryGraphConfig, GraphNode, GraphEdge,
-  GraphStats, RankedResult,
-
-  // Tiers
-  MemoryTier, EntityFact, SessionSummary,
-
-  // Migration
-  MigrationSource, MigrationConfig, MigrationResult,
-
-  // Checkpointing
-  AgentState, SwarmCheckpoint, CheckpointMeta,
-} from '@monomind/memory';
+const q = query()
+  .semantic('authentication patterns')
+  .inNamespace('security')
+  .withTags(['auth'])
+  .threshold(0.7)
+  .limit(20)
+  .sortByNewest()
+  .build();
 ```
 
-## Dependencies
+## Cross-platform notes
 
-- `lancedb` - Vector database engine
-- `better-sqlite3` - SQLite driver (native)
-- `sql.js` - SQLite driver (WASM fallback)
+`createDatabase()` picks the best available provider per platform:
+`better-sqlite3` (native, fastest) → `sql.js` (WASM, zero compilation, works
+everywhere including Windows without a toolchain) → JSON file fallback. See
+`docs/CROSS_PLATFORM.md` and `docs/WINDOWS_SUPPORT.md`.
 
-## Related Packages
+## Links
 
-- [@monomind/shared](../shared) - Shared types and utilities
-- [@monomind/hooks](../hooks) - Session lifecycle hooks for auto memory sync
+- [GitHub](https://github.com/monoes/monomind)
+- [Documentation](https://monoes.github.io/monomind/)
+- [Issues](https://github.com/monoes/monomind/issues)
 
 ## License