@claude-flow/memory 3.0.0-alpha.2 → 3.0.0-alpha.8

package/README.md

@@ -6,12 +6,16 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Performance](https://img.shields.io/badge/Performance-150x--12500x%20Faster-brightgreen.svg)](https://github.com/ruvnet/claude-flow)
 
-> High-performance memory module for Claude Flow V3 - AgentDB unification, HNSW indexing, vector search, and hybrid SQLite+AgentDB backend (ADR-009).
+> High-performance memory module for Claude Flow V3 - AgentDB unification, HNSW indexing, vector search, self-learning knowledge graph, and hybrid SQLite+AgentDB backend (ADR-009).
 
 ## Features
 
 - **150x-12,500x Faster Search** - HNSW (Hierarchical Navigable Small World) vector index for ultra-fast similarity search
 - **Hybrid Backend** - SQLite for structured data + AgentDB for vectors (ADR-009)
+- **Auto Memory Bridge** - Bidirectional sync between Claude Code auto memory and AgentDB (ADR-048)
+- **Self-Learning** - LearningBridge connects insights to SONA/ReasoningBank neural pipeline (ADR-049)
+- **Knowledge Graph** - PageRank + label propagation community detection over memory entries (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
@@ -188,16 +192,6 @@ await migration.execute({
 });
 ```
 
-## Performance Benchmarks
-
-| Operation | V2 Performance | V3 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** |
-
 ## Quantization Options
 
 ```typescript
@@ -220,16 +214,358 @@ const productIndex = new HNSWIndex({
 });
 ```
 
+## Auto Memory Bridge (ADR-048)
+
+Bidirectional sync between Claude Code's [auto memory](https://code.claude.com/docs/en/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
+
+```typescript
+import { AutoMemoryBridge } from '@claude-flow/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 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 files
+const 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 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 '@claude-flow/memory';
+```
+
+### Types
+
+```typescript
+import type {
+  AutoMemoryBridgeConfig,
+  MemoryInsight,
+  InsightCategory,
+  SyncDirection,
+  SyncMode,
+  PruneStrategy,
+  SyncResult,
+  ImportResult,
+} from '@claude-flow/memory';
+```
+
+## Self-Learning Bridge (ADR-049)
+
+Connects insights to the `@claude-flow/neural` learning pipeline. When neural is unavailable, all operations degrade to no-ops.
+
+### Quick Start
+
+```typescript
+import { AutoMemoryBridge, LearningBridge } from '@claude-flow/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 '@claude-flow/memory';
+
+const lb = new LearningBridge(backend, {
+  // Optional: inject neural loader for custom setups
+  neuralLoader: async () => {
+    const { NeuralLearningSystem } = await import('@claude-flow/neural');
+    return new NeuralLearningSystem();
+  },
+});
+
+// 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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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 '@claude-flow/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: '...' }, ...]
+```
+
+## Performance Benchmarks
+
+| Operation | V2 Performance | V3 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
 
 ```typescript
 import type {
-  HNSWConfig,
-  HNSWStats,
-  SearchResult,
-  MemoryEntry,
-  QuantizationConfig,
-  DistanceMetric
+  // Core
+  HNSWConfig, HNSWStats, SearchResult, MemoryEntry,
+  QuantizationConfig, DistanceMetric,
+
+  // Auto Memory Bridge (ADR-048)
+  AutoMemoryBridgeConfig, MemoryInsight, InsightCategory,
+  SyncDirection, SyncMode, PruneStrategy,
+  SyncResult, ImportResult,
+
+  // Learning Bridge (ADR-049)
+  LearningBridgeConfig, LearningStats,
+  ConsolidateResult, PatternMatch,
+
+  // Knowledge Graph (ADR-049)
+  MemoryGraphConfig, GraphNode, GraphEdge,
+  GraphStats, RankedResult, EdgeType,
+
+  // Agent Scope (ADR-049)
+  AgentMemoryScope, AgentScopedConfig,
+  TransferOptions, TransferResult,
 } from '@claude-flow/memory';
 ```
 
@@ -238,11 +574,13 @@ import type {
 - `agentdb` - Vector database engine
 - `better-sqlite3` - SQLite driver (native)
 - `sql.js` - SQLite driver (WASM fallback)
+- `@claude-flow/neural` - **Optional peer dependency** for self-learning (graceful fallback when unavailable)
 
 ## Related Packages
 
-- [@claude-flow/neural](../neural) - Neural learning integration
+- [@claude-flow/neural](../neural) - Neural learning integration (SONA, ReasoningBank, EWC++)
 - [@claude-flow/shared](../shared) - Shared types and utilities
+- [@claude-flow/hooks](../hooks) - Session lifecycle hooks for auto memory sync
 
 ## License
 

package/dist/agent-memory-scope.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Agent-Scoped Memory - Support for Claude Code's 3-scope agent memory directories
+ *
+ * Claude Code organizes agent memory into three scopes:
+ * - **project**: Shared across all collaborators (checked into git)
+ * - **local**: Machine-specific, not shared (gitignored)
+ * - **user**: Global per-user, spans all projects
+ *
+ * Each scope stores agent-specific memory in a named subdirectory,
+ * enabling isolated yet transferable knowledge between agents.
+ *
+ * @module @claude-flow/memory/agent-memory-scope
+ */
+import type { IMemoryBackend } from './types.js';
+import { AutoMemoryBridge } from './auto-memory-bridge.js';
+import type { AutoMemoryBridgeConfig, InsightCategory } from './auto-memory-bridge.js';
+/** Claude Code's 3-scope agent memory system */
+export type AgentMemoryScope = 'project' | 'local' | 'user';
+/** Configuration for agent-scoped memory bridge */
+export interface AgentScopedConfig extends AutoMemoryBridgeConfig {
+    /** Agent name (used in directory path) */
+    agentName: string;
+    /** Memory scope */
+    scope: AgentMemoryScope;
+}
+/** Options for knowledge transfer between agents */
+export interface TransferOptions {
+    /** Source namespace to transfer from */
+    sourceNamespace: string;
+    /** Minimum confidence to include (default: 0.8) */
+    minConfidence?: number;
+    /** Maximum entries to transfer (default: 20) */
+    maxEntries?: number;
+    /** Filter by categories */
+    categories?: InsightCategory[];
+}
+/** Result of a knowledge transfer */
+export interface TransferResult {
+    /** Number of entries transferred */
+    transferred: number;
+    /** Number of entries skipped (below threshold or duplicate) */
+    skipped: number;
+}
+/**
+ * Resolve the agent memory directory for a given agent name, scope, and working directory.
+ *
+ * Path resolution matches Claude Code binary behavior:
+ * ```
+ * project: <gitRoot>/.claude/agent-memory/<agentName>/
+ * local:   <gitRoot>/.claude/agent-memory-local/<agentName>/
+ * user:    ~/.claude/agent-memory/<agentName>/
+ * ```
+ *
+ * Agent names are sanitized to prevent path traversal attacks.
+ *
+ * @param agentName - The agent identifier
+ * @param scope - Memory scope: project, local, or user
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Absolute path to the agent's memory directory
+ */
+export declare function resolveAgentMemoryDir(agentName: string, scope: AgentMemoryScope, workingDir?: string): string;
+/**
+ * Create an AutoMemoryBridge configured for a specific agent scope.
+ *
+ * This is the primary factory for creating scoped bridges. It resolves
+ * the correct memory directory based on agent name and scope, then
+ * delegates to AutoMemoryBridge for the actual sync logic.
+ *
+ * @param backend - The AgentDB memory backend
+ * @param config - Agent-scoped configuration
+ * @returns A configured AutoMemoryBridge instance
+ *
+ * @example
+ * ```typescript
+ * const bridge = createAgentBridge(backend, {
+ *   agentName: 'coder',
+ *   scope: 'project',
+ *   syncMode: 'on-write',
+ * });
+ * await bridge.recordInsight({ ... });
+ * ```
+ */
+export declare function createAgentBridge(backend: IMemoryBackend, config: AgentScopedConfig): AutoMemoryBridge;
+/**
+ * Transfer knowledge from a source backend namespace into a target bridge.
+ *
+ * Queries high-confidence entries from the source and records them as
+ * insights in the target bridge. Useful for cross-agent knowledge sharing
+ * or promoting learnings from one scope to another.
+ *
+ * @param sourceBackend - Backend to query entries from
+ * @param targetBridge - Bridge to record insights into
+ * @param options - Transfer options (namespace, filters, limits)
+ * @returns Transfer result with counts of transferred and skipped entries
+ *
+ * @example
+ * ```typescript
+ * const result = await transferKnowledge(sourceBackend, targetBridge, {
+ *   sourceNamespace: 'learnings',
+ *   minConfidence: 0.9,
+ *   maxEntries: 10,
+ *   categories: ['architecture', 'security'],
+ * });
+ * console.log(`Transferred ${result.transferred}, skipped ${result.skipped}`);
+ * ```
+ */
+export declare function transferKnowledge(sourceBackend: IMemoryBackend, targetBridge: AutoMemoryBridge, options: TransferOptions): Promise<TransferResult>;
+/**
+ * List all agent scopes and their agents for the current project.
+ *
+ * Scans the three scope directories (project, local, user) and returns
+ * the agent names found in each. Useful for discovery and diagnostics.
+ *
+ * @param workingDir - Working directory for git root detection (defaults to cwd)
+ * @returns Array of scope/agents pairs
+ *
+ * @example
+ * ```typescript
+ * const scopes = listAgentScopes('/workspaces/my-project');
+ * // [
+ * //   { scope: 'project', agents: ['coder', 'tester'] },
+ * //   { scope: 'local', agents: ['researcher'] },
+ * //   { scope: 'user', agents: ['planner'] },
+ * // ]
+ * ```
+ */
+export declare function listAgentScopes(workingDir?: string): Array<{
+    scope: AgentMemoryScope;
+    agents: string[];
+}>;
+//# sourceMappingURL=agent-memory-scope.d.ts.map

package/dist/agent-memory-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory-scope.d.ts","sourceRoot":"","sources":["../src/agent-memory-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EACV,sBAAsB,EAEtB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAIjC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5D,mDAAmD;AACnD,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AA2CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,gBAAgB,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAoBR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,CAWlB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,gBAAgB,EAC9B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAwDzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,UAAU,CAAC,EAAE,MAAM,GAClB,KAAK,CAAC;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAetD"}