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

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.ts
new file mode 100644
index 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.ts
index 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] -> id
private 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 index
if (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 index
for (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.ts
index 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.ts
new file mode 100644
index 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]);
+}