π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdnew file mode 100644index 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.jsonindex 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.tsnew file mode 100644index 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.tsindex 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 =====/**