Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(memory): #2061 ADR-125 Phase 1 β€” MemoryService canonical entry point + deprecate UnifiedMemoryService

ruv4e9a33ce2a7a
diff --git a/v3/@claude-flow/memory/docs/migration-3.0.0-alpha.18.md b/v3/@claude-flow/memory/docs/migration-3.0.0-alpha.18.md
new file mode 100644
index 0000000000..b43c6bb658
--- /dev/null
+++ b/v3/@claude-flow/memory/docs/migration-3.0.0-alpha.18.md
@@ -0,0 +1,106 @@
+# Migration Guide β€” `@claude-flow/[email protected]`
+
+This release lands [ADR-125](../../../docs/adr/ADR-125-memory-consolidation.md) PR A β€” the "deliver ADR-009" bundle. The user-facing API stays backwards-compatible; this guide explains the renames, removals, and the new defaults.
+
+## TL;DR
+
+```diff
+- import { UnifiedMemoryService, createHybridService, HnswLite, RvfBackend } from '@claude-flow/memory';
++ import { MemoryService, createHybridService } from '@claude-flow/memory';
+```
+
+`UnifiedMemoryService` is **still exported** β€” it is now an alias of `MemoryService` and will be removed at `3.0.0-rc`. No runtime behavior change.
+
+## What changed
+
+### 1. `MemoryService` is now the canonical entry point (Phase 1)
+
+The class previously known as `UnifiedMemoryService` is now exported under two names:
+
+- `MemoryService` β€” canonical name, use this in new code.
+- `UnifiedMemoryService` β€” `@deprecated` alias, kept until `3.0.0-rc` so existing imports continue working.
+
+Both names refer to the same constructor:
+
+```ts
+import { MemoryService, UnifiedMemoryService } from '@claude-flow/memory';
+
+MemoryService === UnifiedMemoryService; // true
+new MemoryService({}) instanceof UnifiedMemoryService; // true
+```
+
+If you keep importing `UnifiedMemoryService`, your code keeps working but will start emitting `@deprecated` JSDoc warnings in IDEs that surface them.
+
+### 2. `HnswLite` and `RvfBackend` are no longer in the public surface (Phase 1)
+
+These were internal building blocks that leaked through `src/index.ts`. They are now reachable through their explicit module paths only:
+
+```ts
+// Before (no longer works from the index)
+import { HnswLite, RvfBackend } from '@claude-flow/memory';
+
+// After β€” if you actually need them, import from the explicit submodule
+import { HnswLite } from '@claude-flow/memory/hnsw-lite';
+import { RvfBackend } from '@claude-flow/memory/rvf-backend';
+```
+
+In practice you almost certainly do NOT need them directly:
+
+- `RvfBackend` is selected automatically by `createDatabase({ provider: 'rvf' })` (or the default `'auto'` selection on platforms where RVF is preferred).
+- `HnswLite` lives inside `RvfBackend`. The canonical HNSW for the rest of the package is `HNSWIndex` (still exported).
+
+The `prepublishOnly` check now fails the publish if either symbol re-appears on the top-level exports.
+
+### 3. `createHybridService` actually returns a hybrid service (Phase 2)
+
+Before this release, `createHybridService` silently downgraded to AgentDB-only β€” the code comment admitted as much. It now returns a `MemoryService` whose backend is a real `HybridBackend` (SQLite for structured queries, AgentDB for semantic), via the new `'hybrid'` case in `createDatabase`.
+
+```ts
+import { createHybridService } from '@claude-flow/memory';
+
+const memory = await createHybridService('./data/memory.db', embeddingFn);
+await memory.initialize();
+
+// Backend is now an actual HybridBackend
+(memory as any).backend instanceof HybridBackend; // true
+```
+
+If you were relying on the old AgentDB-only behavior, switch to `createPersistentService` or pass a custom backend instead.
+
+### 4. New `createDatabase` providers (Phase 2)
+
+`createDatabase` now dispatches to:
+
+- `'hybrid'` β€” returns a `HybridBackend` composing SQLite + AgentDB.
+- `'agentdb'` β€” returns an `AgentDBBackend` directly (previously only reachable through `UnifiedMemoryService`).
+
+The existing providers (`'better-sqlite3'`, `'sql.js'`, `'rvf'`, `'json'`, `'auto'`) are unchanged.
+
+### 5. Bench script wiring (Phase 6)
+
+`npm run bench` now uses a dedicated `vitest.bench.config.ts` and discovers `benchmarks/**/*.bench.ts`. The first measured baseline lives in `benchmarks/results/`. The README's perf table now cites real measurements instead of aspirational prose.
+
+### 6. RuVector boundary (Phase 7)
+
+`v3/@claude-flow/memory/ruvector.db` is test pollution, not a runtime artifact. It is now wiped before and after tests by `vitest.setup.ts`, and a `scripts/smoke-memory-no-stray-db.mjs` CI guard fails the build if any `*.db` / `*.redb` / `*.rvf` file appears in `git status` under the package after `npm test` runs.
+
+## What did NOT change
+
+- The `IMemoryBackend` interface and all `MemoryEntry` / `MemoryQuery` / `SearchOptions` types are unchanged.
+- The DDD layer (`src/domain`, `src/application`, `src/infrastructure`) is still internal-only β€” it has never been re-exported, and this release does not change that.
+- All existing tests pass unchanged. Net test count goes up; no regressions.
+
+## Upgrading
+
+```diff
+- "@claude-flow/memory": "^3.0.0-alpha.17"
++ "@claude-flow/memory": "^3.0.0-alpha.18"
+```
+
+For most consumers, no code change is needed. To remove the `@deprecated` warnings, rename `UnifiedMemoryService` β†’ `MemoryService` at your import sites.
+
+## See also
+
+- [ADR-125 β€” Memory Consolidation](../../../docs/adr/ADR-125-memory-consolidation.md)
+- [ADR-009 β€” Hybrid Memory Backend](../../../docs/adr/ADR-009-hybrid-memory-backend.md)
+- [ADR-006 β€” Unified Memory Service](../../../docs/adr/ADR-006-unified-memory-service.md)
diff --git a/v3/@claude-flow/memory/package.json b/v3/@claude-flow/memory/package.json
index faea77b83c..d9858c2621 100644
--- a/v3/@claude-flow/memory/package.json
+++ b/v3/@claude-flow/memory/package.json
@@ -14,7 +14,7 @@
"bench": "vitest bench",
"build": "tsc",
"prebuild": "rm -rf dist tsconfig.tsbuildinfo",
- "prepublishOnly": "npm run build && node -e \"const m = await import('./dist/index.js'); const required = ['ControllerRegistry','HnswLite','PersistentSonaCoordinator','RvfBackend','RvfLearningStore','RvfMigrator']; const missing = required.filter(k => !m[k]); if (missing.length) { console.error('Missing exports:', missing); process.exit(1); } console.log('All required exports present');\""
+ "prepublishOnly": "npm run build && node -e \"const m = await import('./dist/index.js'); const required = ['ControllerRegistry','MemoryService','UnifiedMemoryService','PersistentSonaCoordinator','RvfLearningStore','RvfMigrator']; const missing = required.filter(k => !m[k]); if (missing.length) { console.error('Missing exports:', missing); process.exit(1); } const forbidden = ['HnswLite','RvfBackend']; const leaks = forbidden.filter(k => k in m); if (leaks.length) { console.error('Forbidden public exports present (ADR-125):', leaks); process.exit(1); } console.log('All required exports present; ADR-125 surface clean');\""
},
"dependencies": {
"agentdb": "^3.0.0-alpha.14",
diff --git a/v3/@claude-flow/memory/src/index.test.ts b/v3/@claude-flow/memory/src/index.test.ts
new file mode 100644
index 0000000000..38ca0d4dd7
--- /dev/null
+++ b/v3/@claude-flow/memory/src/index.test.ts
@@ -0,0 +1,51 @@
+/**
+ * Phase 1 β€” Public API surface tests (ADR-125)
+ *
+ * Asserts that:
+ * - `MemoryService` is the canonical exported entry point.
+ * - `UnifiedMemoryService` remains exported as a deprecated alias to the same class.
+ * - `HnswLite` and `RvfBackend` are NOT exported from the top-level package surface.
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as memoryPkg from './index.js';
+
+describe('Phase 1 β€” canonical public exports', () => {
+ it('exports `MemoryService` as the canonical entry point', () => {
+ expect(memoryPkg).toHaveProperty('MemoryService');
+ expect(typeof (memoryPkg as any).MemoryService).toBe('function');
+ });
+
+ it('also exports `UnifiedMemoryService` as a deprecated alias', () => {
+ expect(memoryPkg).toHaveProperty('UnifiedMemoryService');
+ expect(typeof (memoryPkg as any).UnifiedMemoryService).toBe('function');
+ });
+
+ it('`MemoryService` and `UnifiedMemoryService` reference the same class', () => {
+ expect((memoryPkg as any).MemoryService).toBe((memoryPkg as any).UnifiedMemoryService);
+ });
+
+ it('does NOT expose `HnswLite` from the top-level package', () => {
+ expect(memoryPkg).not.toHaveProperty('HnswLite');
+ });
+
+ it('does NOT expose `RvfBackend` from the top-level package', () => {
+ expect(memoryPkg).not.toHaveProperty('RvfBackend');
+ });
+
+ it('does NOT expose DDD layer types from the top-level package', () => {
+ // These live under src/domain, src/application, src/infrastructure
+ // and have never been re-exported from index.ts β€” assert that invariant.
+ expect(memoryPkg).not.toHaveProperty('StoreMemoryCommandHandler');
+ expect(memoryPkg).not.toHaveProperty('SearchMemoryQueryHandler');
+ expect(memoryPkg).not.toHaveProperty('HybridMemoryRepository');
+ });
+
+ it('continues to expose the backend constructors that PR A keeps public', () => {
+ // Backends that downstream packages import directly remain stable.
+ expect(memoryPkg).toHaveProperty('AgentDBBackend');
+ expect(memoryPkg).toHaveProperty('SQLiteBackend');
+ expect(memoryPkg).toHaveProperty('SqlJsBackend');
+ expect(memoryPkg).toHaveProperty('HybridBackend');
+ });
+});
diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.ts
index 9ca0840b3c..c7409f3fa0 100644
--- a/v3/@claude-flow/memory/src/index.ts
+++ b/v3/@claude-flow/memory/src/index.ts
@@ -193,10 +193,11 @@ export type {
SemanticQuery,
HybridQuery,
} from './hybrid-backend.js';
-export { RvfBackend } from './rvf-backend.js';
-export type { RvfBackendConfig } from './rvf-backend.js';
-export { HnswLite, cosineSimilarity } from './hnsw-lite.js';
-export type { HnswSearchResult } from './hnsw-lite.js';
+// `RvfBackend` and `HnswLite` are intentionally NOT re-exported from the top level
+// per ADR-125 Phase 1. They remain internal β€” RvfBackend is reachable via
+// `createDatabase({ provider: 'rvf' })`, and HnswLite is used inside RvfBackend.
+// Importers that need them directly should import the explicit module path.
+export { cosineSimilarity } from './hnsw-lite.js';
export { HNSWIndex } from './hnsw-index.js';
export { CacheManager, TieredCacheManager } from './cache-manager.js';
export { QueryBuilder, query, QueryTemplates } from './query-builder.js';
@@ -252,15 +253,22 @@ export interface UnifiedMemoryServiceConfig extends Partial<AgentDBAdapterConfig
}
/**
- * Unified Memory Service
+ * Memory Service implementation (legacy class name).
*
- * High-level interface for the V3 memory system that provides:
+ * @deprecated Use {@link MemoryService} β€” the canonical name introduced by
+ * ADR-125 Phase 1. `UnifiedMemoryService` is preserved as an alias and will
+ * continue to work through `@claude-flow/[email protected]`. Both names refer
+ * to the same class.
+ *
+ * High-level interface that provides:
* - Simple API for common operations
* - Automatic embedding generation
* - Cross-agent memory sharing
* - SONA integration for learning
* - Event-driven notifications
* - Performance monitoring
+ *
+ * @see {@link MemoryService} for the canonical alias.
*/
export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend {
private adapter: AgentDBAdapter;
@@ -531,6 +539,40 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
}
}
+// ===== Canonical Alias (ADR-125 Phase 1) =====
+
+/**
+ * Canonical memory service entry point (ADR-125).
+ *
+ * `MemoryService` is the preferred name as of `@claude-flow/[email protected]`.
+ * It is an alias of {@link UnifiedMemoryService}; both names refer to the same
+ * class so existing callers continue working unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { MemoryService } from '@claude-flow/memory';
+ *
+ * const memory = new MemoryService({ dimensions: 1536 });
+ * await memory.initialize();
+ * ```
+ */
+export const MemoryService = UnifiedMemoryService;
+
+/**
+ * @public
+ * @typedef MemoryService
+ *
+ * Type alias matching the canonical {@link MemoryService} runtime export so that
+ * `import type { MemoryService } from '@claude-flow/memory'` works alongside the
+ * value import.
+ */
+export type MemoryService = UnifiedMemoryService;
+
+/**
+ * Config type alias for {@link MemoryService}.
+ */
+export type MemoryServiceConfig = UnifiedMemoryServiceConfig;
+
// ===== Factory Functions =====
/**