🌊 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
fix(memory): preserve distinct namespace and key tuples in upserts
Rudy Celekli7f6fd2d76aa9
diff --git a/v3/@claude-flow/memory/src/agentdb-adapter-key-isolation.test.ts b/v3/@claude-flow/memory/src/agentdb-adapter-key-isolation.test.tsnew file mode 100644index 0000000000..371c5e199b--- /dev/null+++ b/v3/@claude-flow/memory/src/agentdb-adapter-key-isolation.test.ts@@ -0,0 +1,171 @@+/** Regression coverage for #3358: distinct namespace/key tuples must not evict each other. */+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { afterEach, describe, expect, it } from 'vitest';+import { AgentDBAdapter, type AgentDBAdapterConfig } from './agentdb-adapter.js';+import { MemoryConsolidator } from './consolidator.js';+import { createDefaultEntry, type MemoryEntry } from './types.js';++const vector = () => Float32Array.of(1, 0, 0, 0, 0, 0, 0, 0);+function pair(): [MemoryEntry, MemoryEntry] {+ const a = createDefaultEntry({ namespace: 'team:alice', key: 'profile', content: 'Alice profile' });+ const b = createDefaultEntry({ namespace: 'team', key: 'alice:profile', content: 'Other profile' });+ a.embedding = vector();+ b.embedding = vector();+ return [a, b];+}++const adapters: AgentDBAdapter[] = [];+const directories: string[] = [];+async function open(config: Partial<AgentDBAdapterConfig> = {}) {+ const adapter = new AgentDBAdapter({ dimensions: 8, cacheEnabled: true, ...config });+ adapters.push(adapter);+ await adapter.initialize();+ return adapter;+}+function persistence() {+ const dir = mkdtempSync(join(tmpdir(), 'memory-key-isolation-'));+ directories.push(dir);+ return { persistenceEnabled: true, persistencePath: join(dir, 'store') };+}+async function expectPair(adapter: AgentDBAdapter, a: MemoryEntry, b: MemoryEntry) {+ expect((await adapter.get(a.id))?.id).toBe(a.id);+ expect((await adapter.get(b.id))?.id).toBe(b.id);+ expect((await adapter.getByKey(a.namespace, a.key))?.id).toBe(a.id);+ expect((await adapter.getByKey(b.namespace, b.key))?.id).toBe(b.id);+ expect((await adapter.search(vector(), { k: 10 })).map(r => r.entry.id).sort()).toEqual([a.id, b.id].sort());+ for (const entry of [a, b]) {+ expect((await adapter.query({ type: 'prefix', namespace: entry.namespace, keyPrefix: '', limit: 10 })).map(e => e.id)).toEqual([entry.id]);+ expect((await adapter.query({ type: 'exact', namespace: entry.namespace, key: entry.key, limit: 10 })).map(e => e.id)).toEqual([entry.id]);+ }+}++afterEach(async () => {+ for (const adapter of adapters.splice(0)) await adapter.shutdown();+ for (const dir of directories.splice(0)) rmSync(dir, { recursive: true, force: true });+});++describe('namespace/key isolation (#3358)', () => {+ it.each(['scalar', 'batch', 'pre-existing then batch'] as const)('preserves colliding legacy tuples through %s writes', async (mode) => {+ const adapter = await open();+ const [a, b] = pair();+ if (mode === 'batch') await adapter.bulkInsert([a, b]);+ else {+ await adapter.store(a);+ if (mode === 'scalar') await adapter.store(b);+ else await adapter.bulkInsert([b]);+ }+ await expectPair(adapter, a, b);+ });++ it.each(['scalar', 'batch'] as const)('still replaces an identical tuple through %s writes without deleting the neighboring tuple', async (mode) => {+ const adapter = await open();+ const [a, b] = pair();+ await adapter.store(a);+ await adapter.store(b);+ const replacement = createDefaultEntry({ namespace: a.namespace, key: a.key, content: 'Updated Alice profile' });+ replacement.embedding = vector();+ if (mode === 'scalar') await adapter.store(replacement);+ else await adapter.bulkInsert([replacement]);+ expect(await adapter.get(a.id)).toBeNull();+ await expectPair(adapter, replacement, b);+ });++ it.each(['delete', 'bulkDelete', 'clearNamespace'] as const)('%s removes only the requested tuple and clears its lookup', async (mode) => {+ const adapter = await open();+ const [a, b] = pair();+ await adapter.bulkInsert([a, b]);+ if (mode === 'delete') await adapter.delete(a.id);+ else if (mode === 'bulkDelete') await adapter.bulkDelete([a.id]);+ else await adapter.clearNamespace(a.namespace);+ expect(await adapter.get(a.id)).toBeNull();+ expect(await adapter.getByKey(a.namespace, a.key)).toBeNull();+ expect((await adapter.getByKey(b.namespace, b.key))?.id).toBe(b.id);+ expect((await adapter.search(vector(), { k: 10 })).map(r => r.entry.id)).toEqual([b.id]);+ });++ it('matches prefixes against raw keys, including quotes, slashes and Unicode', async () => {+ const adapter = await open();+ const namespace = 'team:"\\雪';+ const matching = createDefaultEntry({ namespace, key: '"\\雪:profile', content: 'matching' });+ const otherKey = createDefaultEntry({ namespace, key: 'elsewhere', content: 'other key' });+ const otherNamespace = createDefaultEntry({ namespace: `${namespace}:child`, key: matching.key, content: 'other namespace' });+ await adapter.bulkInsert([matching, otherKey, otherNamespace]);+ expect((await adapter.getByKey(namespace, matching.key))?.id).toBe(matching.id);+ expect((await adapter.query({ type: 'prefix', namespace, keyPrefix: '"\\雪:', limit: 10 })).map(e => e.id)).toEqual([matching.id]);+ });++ it('preserves both tuples and subsequent same-tuple replacement across restarts', async () => {+ const config = persistence();+ const first = await open(config);+ const [a, b] = pair();+ await first.bulkInsert([a, b]);+ await first.shutdown();+ const reloaded = await open(config);+ await expectPair(reloaded, a, b);+ const replacement = createDefaultEntry({ namespace: a.namespace, key: a.key, content: 'Updated Alice profile' });+ replacement.embedding = vector();+ await reloaded.store(replacement);+ await reloaded.shutdown();+ const again = await open(config);+ expect(await again.get(a.id)).toBeNull();+ await expectPair(again, replacement, b);+ });++ it.each(['delete', 'bulkDelete'] as const)('loads v1 colliding keys and preserves the saved winner when %s removes a stale duplicate', async (mode) => {+ const config = persistence();+ const first = await open(config);+ const [a, b] = pair();+ const winner = createDefaultEntry({ namespace: 'dup', key: 'duplicate', content: 'winner' });+ const stale = createDefaultEntry({ namespace: 'dup', key: 'temporary', content: 'stale' });+ // Persisted entry order must not accidentally choose the intended winner.+ winner.id = 'a-winner';+ stale.id = 'z-stale';+ await first.bulkInsert([a, b, winner, stale]);+ await first.shutdown();++ const metaPath = `${config.persistencePath}.meta.json`;+ const meta = JSON.parse(readFileSync(metaPath, 'utf8'));+ meta.version = 1;+ meta.entries.find((e: MemoryEntry) => e.id === stale.id).key = winner.key;+ // An authentic v1 index could only retain B for the colliding pair,+ // while same-tuple orphans remained in entries under distinct IDs.+ meta.keyIndex = { 'team:alice:profile': b.id, 'dup:duplicate': winner.id };+ writeFileSync(metaPath, JSON.stringify(meta));++ const reloaded = await open(config);+ await expectPair(reloaded, a, b);+ expect((await reloaded.getByKey('dup', 'duplicate'))?.id).toBe(winner.id);+ expect((await reloaded.get(stale.id))?.id).toBe(stale.id);+ if (mode === 'delete') await reloaded.delete(stale.id);+ else await reloaded.bulkDelete([stale.id]);+ expect(await reloaded.get(stale.id)).toBeNull();+ expect((await reloaded.getByKey('dup', 'duplicate'))?.id).toBe(winner.id);+ await reloaded.shutdown();+ expect(JSON.parse(readFileSync(metaPath, 'utf8')).version).toBe(2);+ const again = await open(config);+ await expectPair(again, a, b);+ expect((await again.getByKey('dup', 'duplicate'))?.id).toBe(winner.id);+ });++ it.each(['sweep', 'dedup'] as const)('clears the encoded lookup during consolidator %s', async (mode) => {+ const adapter = await open();+ const [a, b] = pair();+ if (mode === 'sweep') a.expiresAt = Date.now() - 1000;+ else {+ a.content = b.content;+ a.updatedAt = 1;+ b.updatedAt = 2;+ }+ await adapter.bulkInsert([a, b]);+ const consolidator = new MemoryConsolidator({ getAdapter: () => adapter } as any, { similarityThreshold: 1 });+ if (mode === 'sweep') expect((await consolidator.sweepExpired()).removed).toBe(1);+ else expect((await consolidator.dedup('keep-newest')).merged).toBe(1);+ // Both values were cached on insert; a stale keyIndex pointer would+ // incorrectly return the removed entry from cache even after cleanup.+ expect(await adapter.getByKey(a.namespace, a.key)).toBeNull();+ expect((await adapter.getByKey(b.namespace, b.key))?.id).toBe(b.id);+ expect((await adapter.search(vector(), { k: 10 })).map(r => r.entry.id)).toEqual([b.id]);+ });+});diff --git a/v3/@claude-flow/memory/src/agentdb-adapter.ts b/v3/@claude-flow/memory/src/agentdb-adapter.tsindex e14457d03e..3a2897c242 100644--- a/v3/@claude-flow/memory/src/agentdb-adapter.ts+++ b/v3/@claude-flow/memory/src/agentdb-adapter.ts@@ -30,6 +30,7 @@ import {} from './types.js';import { HNSWIndex } from './hnsw-index.js';import { CacheManager } from './cache-manager.js';+import { encodeMemoryKey } from './memory-key.js';/*** Configuration for AgentDB Adapter@@ -100,7 +101,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {private index: HNSWIndex;private cache: CacheManager<MemoryEntry>;private namespaceIndex: Map<string, Set<string>> = new Map();- private keyIndex: Map<string, string> = new Map(); // namespace:key -> id+ private keyIndex: Map<string, string> = new Map(); // encoded [namespace, key] -> idprivate tagIndex: Map<string, Set<string>> = new Map();private initialized: boolean = false;@@ -185,7 +186,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {// Namespace is resolved once, up front, so the dedup lookup below and the// index updates further down agree on the same value.const namespace = entry.namespace || this.config.defaultNamespace;- const keyIndexKey = `${namespace}:${entry.key}`;+ const keyIndexKey = encodeMemoryKey(namespace, entry.key);// Idempotent upsert-by-key (Dream Cycle 2026-09-18, hardened post-review):// entry.id is always a fresh random id (generateMemoryId()), so a second@@ -276,7 +277,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {* Get a memory entry by key within a namespace*/async getByKey(namespace: string, key: string): Promise<MemoryEntry | null> {- const keyIndexKey = `${namespace}:${key}`;+ const keyIndexKey = encodeMemoryKey(namespace, key, this.config.defaultNamespace);const id = this.keyIndex.get(keyIndexKey);if (!id) return null;return this.get(id);@@ -371,8 +372,8 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {// Remove from key indexif (touchKeyIndex) {- const keyIndexKey = `${entry.namespace}:${entry.key}`;- this.keyIndex.delete(keyIndexKey);+ const keyIndexKey = encodeMemoryKey(entry.namespace, entry.key, this.config.defaultNamespace);+ if (this.keyIndex.get(keyIndexKey) === id) this.keyIndex.delete(keyIndexKey);}// Remove from tag index@@ -511,7 +512,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {// id that isn't the winner for its key -- a pre-existing occupant or an// earlier same-key entry within this very batch -- is scheduled for// eviction once the winners are safely indexed.- const keyOf = (e: MemoryEntry) => `${e.namespace || this.config.defaultNamespace}:${e.key}`;+ const keyOf = (e: MemoryEntry) => encodeMemoryKey(e.namespace, e.key, this.config.defaultNamespace);const winnerIdForKey = new Map<string, string>();for (const entry of entries) {winnerIdForKey.set(keyOf(entry), entry.id);@@ -623,8 +624,8 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {this.namespaceIndex.get(entry.namespace)?.delete(id);// Remove from key index- const keyIndexKey = `${entry.namespace}:${entry.key}`;- this.keyIndex.delete(keyIndexKey);+ const keyIndexKey = encodeMemoryKey(entry.namespace, entry.key, this.config.defaultNamespace);+ if (this.keyIndex.get(keyIndexKey) === id) this.keyIndex.delete(keyIndexKey);// Remove from tag indexfor (const tag of entry.tags) {@@ -905,10 +906,10 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {const prefix = query.keyPrefix || '';const namespace = query.namespace || this.config.defaultNamespace;- for (const [key, id] of this.keyIndex) {- if (key.startsWith(`${namespace}:${prefix}`)) {- const entry = this.entries.get(id);- if (entry) results.push(entry);+ for (const id of this.keyIndex.values()) {+ const entry = this.entries.get(id);+ if (entry && (entry.namespace || this.config.defaultNamespace) === namespace && entry.key.startsWith(prefix)) {+ results.push(entry);}}@@ -1241,12 +1242,21 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {: undefined,};this.entries.set(entry.id, entry);+ // Rebuild from full tuple fields: legacy v1 keys used ambiguous+ // namespace:key strings and could omit a colliding tuple entirely.+ this.keyIndex.set(encodeMemoryKey(entry.namespace, entry.key, this.config.defaultNamespace), entry.id);}for (const [ns, ids] of Object.entries(meta.namespaceIndex)) {this.namespaceIndex.set(ns, new Set(ids));}- for (const [key, id] of Object.entries(meta.keyIndex)) {- this.keyIndex.set(key, id);+ // Preserve the saved winner for true same-tuple duplicates. Entries+ // are sorted by random ID on disk, not by their original write order.+ // Reading IDs also accepts both v1 and v2 key encodings.+ for (const id of Object.values(meta.keyIndex)) {+ const entry = this.entries.get(id);+ if (entry) {+ this.keyIndex.set(encodeMemoryKey(entry.namespace, entry.key, this.config.defaultNamespace), id);+ }}for (const [tag, ids] of Object.entries(meta.tagIndex)) {this.tagIndex.set(tag, new Set(ids));@@ -1351,7 +1361,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {tagIndex[t] = [...this.tagIndex.get(t)!].sort();}- return { version: 1, entries: persistedEntries, namespaceIndex, keyIndex, tagIndex };+ return { version: 2, entries: persistedEntries, namespaceIndex, keyIndex, tagIndex };}}@@ -1360,7 +1370,7 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {* `embedding` is stored as a plain number[] to keep the JSON canonical.*/interface PersistedMeta {- version: 1;+ version: 1 | 2;entries: Array<Omit<MemoryEntry, 'embedding'> & { embedding?: number[] }>;namespaceIndex: Record<string, string[]>;keyIndex: Record<string, string>;diff --git a/v3/@claude-flow/memory/src/consolidator.ts b/v3/@claude-flow/memory/src/consolidator.tsindex abcc4f0fb4..90a5068999 100644--- a/v3/@claude-flow/memory/src/consolidator.ts+++ b/v3/@claude-flow/memory/src/consolidator.ts@@ -25,6 +25,7 @@import { createHash } from 'node:crypto';import { HNSWIndex } from './hnsw-index.js';import type { MemoryEntry } from './types.js';+import { encodeMemoryKey } from './memory-key.js';/*** Strategy for resolving content-hash duplicates inside {@link MemoryConsolidator.dedup}.@@ -134,7 +135,8 @@ export class MemoryConsolidator {for (const entry of toRemove) {entries.delete(entry.id);namespaceIndex.get(entry.namespace)?.delete(entry.id);- keyIndex.delete(`${entry.namespace}:${entry.key}`);+ const compositeKey = encodeMemoryKey(entry.namespace, entry.key, adapter.config?.defaultNamespace);+ if (keyIndex.get(compositeKey) === entry.id) keyIndex.delete(compositeKey);for (const tag of entry.tags) tagIndex.get(tag)?.delete(entry.id);if (entry.embedding) {const removed = await index.removePoint(entry.id);@@ -185,6 +187,7 @@ export class MemoryConsolidator {keyIndex: Map<string, string>;tagIndex: Map<string, Set<string>>;index: HNSWIndex;+ defaultNamespace?: string;}): Promise<{ keeperId: string; dropped: number }> {const keeper = this.selectKeeper(bucket, strategy);@@ -208,7 +211,7 @@ export class MemoryConsolidator {if (e.id === keeper.id) continue;ctx.entries.delete(e.id);ctx.namespaceIndex.get(e.namespace)?.delete(e.id);- const compositeKey = `${e.namespace}:${e.key}`;+ const compositeKey = encodeMemoryKey(e.namespace, e.key, ctx.defaultNamespace);if (ctx.keyIndex.get(compositeKey) === e.id) {ctx.keyIndex.delete(compositeKey);}@@ -249,7 +252,7 @@ export class MemoryConsolidator {const keyIndex: Map<string, string> = adapter.keyIndex;const tagIndex: Map<string, Set<string>> = adapter.tagIndex;const index: HNSWIndex = adapter.index;- const ctx = { entries, namespaceIndex, keyIndex, tagIndex, index };+ const ctx = { entries, namespaceIndex, keyIndex, tagIndex, index, defaultNamespace: adapter.config?.defaultNamespace };const effective = strategy ?? this.opts.dedupStrategy ?? 'keep-newest';diff --git a/v3/@claude-flow/memory/src/memory-key.ts b/v3/@claude-flow/memory/src/memory-key.tsnew file mode 100644index 0000000000..7ab12a7317--- /dev/null+++ b/v3/@claude-flow/memory/src/memory-key.ts@@ -0,0 +1,4 @@+/** Encode a memory's namespace/key tuple without delimiter collisions. */+export function encodeMemoryKey(namespace: string, key: string, defaultNamespace = 'default'): string {+ return JSON.stringify([namespace || defaultNamespace, key]);+}