Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi, beforeEach } from 'vitest';
import EventEmitter from 'events';
// Mock fs/promises
vi.mock('fs/promises', () => ({
readdir: vi.fn().mockResolvedValue([]),
rm: vi.fn().mockResolvedValue(undefined)
}));
// Mock fs (sync)
vi.mock('fs', () => ({
existsSync: vi.fn().mockReturnValue(true)
}));
// Mock uuid
vi.mock('../lib/uuid.js', () => ({
v4: vi.fn().mockReturnValue('test-uuid-1234')
}));
// Mock cosEvents (memory.js imports from cosEvents.js directly)
vi.mock('./cosEvents.js', () => ({
cosEvents: new EventEmitter()
}));
// Mock vectorMath
vi.mock('../lib/vectorMath.js', () => ({
findTopK: vi.fn().mockReturnValue([]),
findAboveThreshold: vi.fn().mockReturnValue([]),
clusterBySimilarity: vi.fn().mockReturnValue([])
}));
// Mock notifications
vi.mock('./notifications.js', () => ({
removeByMetadata: vi.fn().mockResolvedValue(undefined)
}));
// Mock fileUtils
vi.mock('../lib/fileUtils.js', () => ({
tryReadFile: vi.fn().mockResolvedValue(null),
ensureDir: vi.fn(),
ensureDirs: vi.fn(),
readJSONFile: vi.fn(),
atomicWrite: vi.fn().mockResolvedValue(undefined),
rmGuarded: vi.fn().mockResolvedValue(undefined),
PATHS: { memory: '/tmp/test/memory' }
}));
// Mock memoryBM25
vi.mock('./memoryBM25.js', () => ({
indexMemory: vi.fn().mockResolvedValue(undefined),
removeMemoryFromIndex: vi.fn().mockResolvedValue(undefined),
searchBM25: vi.fn().mockResolvedValue([]),
rebuildIndex: vi.fn().mockResolvedValue({ indexed: 0 }),
getStats: vi.fn().mockResolvedValue({ documentCount: 0 }),
flush: vi.fn().mockResolvedValue(undefined)
}));
// Mock asyncMutex - pass-through (no actual locking)
vi.mock('../lib/asyncMutex.js', () => ({
createMutex: () => (fn) => fn()
}));
vi.mock('./cosAgentLifecycle.js', () => ({ getAgent: vi.fn(), updateAgent: vi.fn() }));
// Mock memoryConfig
vi.mock('./memoryConfig.js', () => ({
DEFAULT_MEMORY_CONFIG: {
enabled: true,
embeddingModel: 'test-embedding-model',
embeddingDimension: 768
},
generateSummary: vi.fn((content) => {
if (content.length <= 150) return content;
return content.substring(0, 147) + '...';
}),
decrementAgentPendingApproval: vi.fn().mockResolvedValue(undefined)
}));
import { existsSync } from 'fs';
import { ensureDir, ensureDirs, readJSONFile, atomicWrite, rmGuarded } from '../lib/fileUtils.js';
import * as memoryBM25 from './memoryBM25.js';
import * as notifications from './notifications.js';
import { findTopK, findAboveThreshold, clusterBySimilarity } from '../lib/vectorMath.js';
import { generateSummary, decrementAgentPendingApproval } from './memoryConfig.js';
import { cosEvents } from './cosEvents.js';
import {
createMemory,
getMemory,
countMemories,
getMemories,
updateMemory,
updateMemoryEmbedding,
archiveMemory,
purgeMemory,
approveMemory,
rejectMemory,
searchMemories,
hybridSearchMemories,
rebuildBM25Index,
getBM25Stats,
getTimeline,
getCategories,
getTags,
getRelatedMemories,
getGraphData,
linkMemories,
consolidateMemories,
applyDecay,
clearExpired,
getStats,
invalidateCaches,
flushBM25Index
} from './memory.js';
describe('memory service', () => {
beforeEach(() => {
vi.clearAllMocks();
// Reset caches between tests
invalidateCaches();
// Default readJSONFile behavior: return default index or embeddings based on call order
readJSONFile.mockImplementation((filePath, defaultVal) => Promise.resolve(defaultVal));
existsSync.mockReturnValue(true);
});
// Shared readJSONFile mock builder: routes memory.json / index.json / embeddings.json
// reads to the supplied fixtures, falling back to the default for everything else.
const makeReadMock = (memory, index, embeddings) => (path, def) => {
if (path.includes('memory.json')) return Promise.resolve(memory ? { ...memory } : def);
if (path.includes('index.json')) return Promise.resolve(index || def);
if (path.includes('embeddings.json')) return Promise.resolve(embeddings || def);
return Promise.resolve(def);
};
// ===========================================================================
// createMemory
// ===========================================================================
describe('createMemory', () => {
it('should create a memory with defaults', async () => {
const data = { type: 'fact', content: 'The sky is blue' };
const result = await createMemory(data);
expect(result.id).toBe('test-uuid-1234');
expect(result.type).toBe('fact');
expect(result.content).toBe('The sky is blue');
expect(result.category).toBe('other');
expect(result.tags).toEqual([]);
expect(result.relatedMemories).toEqual([]);
expect(result.confidence).toBe(0.8);
expect(result.importance).toBe(0.5);
expect(result.accessCount).toBe(0);
expect(result.status).toBe('active');
expect(result.embedding).toBeNull();
expect(result.embeddingModel).toBeNull();
expect(result.createdAt).toBeDefined();
expect(result.updatedAt).toBeDefined();
});
it('should create directories when they do not exist', async () => {
existsSync.mockReturnValue(false);
const data = { type: 'fact', content: 'new dir test' };
await createMemory(data);
expect(ensureDirs).toHaveBeenCalled();
});
it('should use provided fields when given', async () => {
const data = {
type: 'decision',
content: 'Use React',
summary: 'Custom summary',
category: 'engineering',
tags: ['frontend', 'react'],
confidence: 0.95,
importance: 0.9,
sourceTaskId: 'task-1',
sourceAgentId: 'agent-1',
sourceAppId: 'app-1',
status: 'pending_approval',
expiresAt: '2026-01-01T00:00:00.000Z',
relatedMemories: ['mem-1']
};
const result = await createMemory(data);
expect(result.summary).toBe('Custom summary');
expect(result.category).toBe('engineering');
expect(result.tags).toEqual(['frontend', 'react']);
expect(result.confidence).toBe(0.95);
expect(result.importance).toBe(0.9);
expect(result.sourceTaskId).toBe('task-1');
expect(result.sourceAgentId).toBe('agent-1');
expect(result.sourceAppId).toBe('app-1');
expect(result.status).toBe('pending_approval');
expect(result.relatedMemories).toEqual(['mem-1']);
});
it('should generate summary when not provided', async () => {
const data = { type: 'fact', content: 'Short content' };
await createMemory(data);
expect(generateSummary).toHaveBeenCalledWith('Short content');
});
it('should store embedding when provided', async () => {
const embedding = [0.1, 0.2, 0.3];
const data = { type: 'fact', content: 'test' };
const result = await createMemory(data, embedding);
expect(result.embedding).toEqual([0.1, 0.2, 0.3]);
expect(result.embeddingModel).toBe('test-embedding-model');
// Should save embeddings file
const embeddingsCall = atomicWrite.mock.calls.find(c => c[0].includes('embeddings.json'));
expect(embeddingsCall).toBeDefined();
});
it('should not save embeddings file when no embedding provided', async () => {
const data = { type: 'fact', content: 'no embedding' };
await createMemory(data);
const embeddingsCall = atomicWrite.mock.calls.find(c => c[0].includes('embeddings.json'));
expect(embeddingsCall).toBeUndefined();
});
it('should add entry to index and update count', async () => {
const data = { type: 'learning', content: 'Learned something' };
await createMemory(data);
// atomicWrite is called for saving memory and saving index
const indexCall = atomicWrite.mock.calls.find(call =>
call[0].includes('index.json')
);
expect(indexCall).toBeDefined();
const savedIndex = indexCall[1];
expect(savedIndex.count).toBe(1);
expect(savedIndex.memories).toHaveLength(1);
expect(savedIndex.memories[0].id).toBe('test-uuid-1234');
});
it('should index in BM25', async () => {
const data = { type: 'fact', content: 'Indexed content', tags: ['tag1'] };
await createMemory(data);
expect(memoryBM25.indexMemory).toHaveBeenCalledWith(
expect.objectContaining({
id: 'test-uuid-1234',
content: 'Indexed content',
type: 'fact',
tags: ['tag1']
})
);
});
it('should emit memory:created event', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const data = { type: 'fact', content: 'test' };
await createMemory(data);
expect(emitSpy).toHaveBeenCalledWith('memory:created', expect.objectContaining({
id: 'test-uuid-1234',
type: 'fact'
}));
});
it('should handle confidence of 0 via nullish coalescing', async () => {
const data = { type: 'fact', content: 'test', confidence: 0 };
const result = await createMemory(data);
expect(result.confidence).toBe(0);
});
});
// ===========================================================================
// getMemory
// ===========================================================================
describe('getMemory', () => {
it('should return memory and update access stats', async () => {
const mockMemory = {
id: 'mem-1',
type: 'fact',
content: 'test',
accessCount: 5,
lastAccessed: null
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
return Promise.resolve(def);
});
const result = await getMemory('mem-1');
expect(result.accessCount).toBe(6);
expect(result.lastAccessed).toBeDefined();
});
it('should return null for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await getMemory('non-existent');
expect(result).toBeNull();
});
});
// ===========================================================================
// getMemories
// ===========================================================================
describe('getMemories', () => {
const makeIndex = (memories) => ({
version: 1,
lastUpdated: '2025-01-01T00:00:00.000Z',
count: memories.length,
memories
});
const mem1 = { id: 'm1', type: 'fact', category: 'science', tags: ['physics'], summary: 'Gravity', importance: 0.8, createdAt: '2025-01-01T00:00:00.000Z', status: 'active', sourceAppId: 'app1' };
const mem2 = { id: 'm2', type: 'decision', category: 'engineering', tags: ['react'], summary: 'Use React', importance: 0.6, createdAt: '2025-01-02T00:00:00.000Z', status: 'active', sourceAppId: 'brain' };
const mem3 = { id: 'm3', type: 'fact', category: 'science', tags: ['math'], summary: 'Pi', importance: 0.9, createdAt: '2025-01-03T00:00:00.000Z', status: 'archived', sourceAppId: 'app1' };
beforeEach(() => {
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(makeIndex([mem1, mem2, mem3]));
return Promise.resolve(def);
});
});
it('should return active memories by default', async () => {
const result = await getMemories();
expect(result.total).toBe(2);
expect(result.memories.every(m => m.status === 'active')).toBe(true);
});
it('should filter by status', async () => {
const result = await getMemories({ status: 'archived' });
expect(result.total).toBe(1);
expect(result.memories[0].id).toBe('m3');
});
it('should filter by types', async () => {
const result = await getMemories({ types: ['fact'] });
expect(result.total).toBe(1);
expect(result.memories[0].type).toBe('fact');
});
it('should filter by categories', async () => {
const result = await getMemories({ categories: ['engineering'] });
expect(result.total).toBe(1);
expect(result.memories[0].category).toBe('engineering');
});
it('should filter by tags (any match)', async () => {
const result = await getMemories({ tags: ['physics', 'react'] });
expect(result.total).toBe(2);
});
it('should filter by appId', async () => {
const result = await getMemories({ appId: 'app1' });
expect(result.total).toBe(1);
expect(result.memories[0].sourceAppId).toBe('app1');
});
it('should filter by __not_brain appId', async () => {
const result = await getMemories({ appId: '__not_brain' });
expect(result.total).toBe(1);
expect(result.memories[0].sourceAppId).not.toBe('brain');
});
it('should sort by createdAt desc by default', async () => {
const result = await getMemories();
expect(result.memories[0].id).toBe('m2');
expect(result.memories[1].id).toBe('m1');
});
it('should sort ascending when specified', async () => {
const result = await getMemories({ sortOrder: 'asc' });
expect(result.memories[0].id).toBe('m1');
});
it('should sort by importance', async () => {
const result = await getMemories({ sortBy: 'importance', sortOrder: 'desc' });
expect(result.memories[0].importance).toBeGreaterThanOrEqual(result.memories[1].importance);
});
it('should paginate results', async () => {
const result = await getMemories({ offset: 0, limit: 1 });
expect(result.total).toBe(2);
expect(result.memories).toHaveLength(1);
});
it('should handle offset pagination', async () => {
const result = await getMemories({ offset: 1, limit: 1 });
expect(result.memories).toHaveLength(1);
});
it('should return empty when no memories match filters', async () => {
const result = await getMemories({ types: ['preference'] });
expect(result.total).toBe(0);
expect(result.memories).toEqual([]);
});
});
// ===========================================================================
// countMemories
// ===========================================================================
describe('countMemories', () => {
const makeIndex = (memories) => ({
version: 1,
lastUpdated: '2025-01-01T00:00:00.000Z',
count: memories.length,
memories
});
const mem1 = { id: 'm1', type: 'fact', category: 'science', tags: ['physics'], summary: 'Gravity', importance: 0.8, createdAt: '2025-01-01T00:00:00.000Z', status: 'active', sourceAppId: 'app1' };
const mem2 = { id: 'm2', type: 'decision', category: 'engineering', tags: ['react'], summary: 'Use React', importance: 0.6, createdAt: '2025-01-02T00:00:00.000Z', status: 'active', sourceAppId: 'brain' };
const mem3 = { id: 'm3', type: 'fact', category: 'science', tags: ['math'], summary: 'Pi', importance: 0.9, createdAt: '2025-01-03T00:00:00.000Z', status: 'archived', sourceAppId: 'app1' };
beforeEach(() => {
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(makeIndex([mem1, mem2, mem3]));
return Promise.resolve(def);
});
});
it('counts active memories by default', async () => {
await expect(countMemories()).resolves.toBe(2);
});
it('applies the same filters as getMemories without sorting or paginating', async () => {
const sortSpy = vi.spyOn(Array.prototype, 'sort');
try {
const result = await countMemories({
status: 'active',
tags: ['physics', 'react'],
limit: 1,
offset: 1,
sortBy: 'importance'
});
expect(result).toBe(2);
expect(sortSpy).not.toHaveBeenCalled();
} finally {
sortSpy.mockRestore();
}
});
});
// ===========================================================================
// updateMemory
// ===========================================================================
describe('updateMemory', () => {
it('should update allowed fields', async () => {
const mockMemory = {
id: 'mem-1',
type: 'fact',
content: 'old content',
summary: 'old summary',
category: 'other',
tags: [],
importance: 0.5,
relatedMemories: [],
status: 'active',
sourceAppId: null
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'old', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }]
});
return Promise.resolve(def);
});
const result = await updateMemory('mem-1', {
content: 'new content',
category: 'engineering',
tags: ['updated'],
importance: 0.9
});
expect(result.content).toBe('new content');
expect(result.category).toBe('engineering');
expect(result.tags).toEqual(['updated']);
expect(result.importance).toBe(0.9);
expect(result.updatedAt).toBeDefined();
});
it('should auto-generate summary when content changes without explicit summary', async () => {
const mockMemory = { id: 'mem-1', type: 'fact', content: 'old', summary: 'old', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'old', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }] });
return Promise.resolve(def);
});
await updateMemory('mem-1', { content: 'brand new content' });
expect(generateSummary).toHaveBeenCalledWith('brand new content');
});
it('should not regenerate summary when both content and summary provided', async () => {
const mockMemory = { id: 'mem-1', type: 'fact', content: 'old', summary: 'old', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'old', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }] });
return Promise.resolve(def);
});
const result = await updateMemory('mem-1', { content: 'new', summary: 'explicit summary' });
expect(result.summary).toBe('explicit summary');
});
it('should regenerate summary when content is cleared to empty string', async () => {
// Absent-vs-cleared: clearing content to "" is an intentional edit and must
// refresh the (now-empty) summary, not leave the stale one behind (#1826).
const mockMemory = { id: 'mem-1', type: 'fact', content: 'old', summary: 'old summary', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation(makeReadMock(mockMemory, { version: 1, memories: [{ id: 'mem-1', status: 'active' }] }));
const result = await updateMemory('mem-1', { content: '' });
expect(generateSummary).toHaveBeenCalledWith('');
expect(result.summary).toBe('');
});
it('should not regenerate summary (or throw) when content is absent', async () => {
// The string-typed gate must keep a content-less update out of generateSummary,
// which would throw on `undefined.length` (#1826).
const mockMemory = { id: 'mem-1', type: 'fact', content: 'old', summary: 'old summary', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation(makeReadMock(mockMemory, { version: 1, memories: [{ id: 'mem-1', status: 'active' }] }));
const result = await updateMemory('mem-1', { status: 'archived' });
expect(generateSummary).not.toHaveBeenCalled();
expect(result.summary).toBe('old summary');
});
it('should return null for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await updateMemory('non-existent', { content: 'test' });
expect(result).toBeNull();
});
it('should update BM25 index when content changes', async () => {
const mockMemory = { id: 'mem-1', type: 'fact', content: 'old', summary: 'old', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'old', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }] });
return Promise.resolve(def);
});
await updateMemory('mem-1', { content: 'new content' });
expect(memoryBM25.indexMemory).toHaveBeenCalled();
});
it('should update BM25 index when tags change', async () => {
const mockMemory = { id: 'mem-1', type: 'fact', content: 'test', summary: 'test', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'test', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }] });
return Promise.resolve(def);
});
await updateMemory('mem-1', { tags: ['new-tag'] });
expect(memoryBM25.indexMemory).toHaveBeenCalled();
});
it('should reindex BM25 when content is cleared to empty string', async () => {
// Absent-vs-cleared: clearing content to "" must reindex so the now-empty
// document stops matching its old terms — the falsy-gated version skipped
// the reindex and left the old text searchable (#1826).
const mockMemory = { id: 'mem-1', type: 'fact', content: 'searchable old text', summary: 'old', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation(makeReadMock(mockMemory, { version: 1, memories: [{ id: 'mem-1', status: 'active' }] }));
await updateMemory('mem-1', { content: '' });
expect(memoryBM25.indexMemory).toHaveBeenCalledWith(
expect.objectContaining({ id: 'mem-1', content: '' })
);
});
it('should not reindex BM25 when neither content nor tags are in the update', async () => {
const mockMemory = { id: 'mem-1', type: 'fact', content: 'test', summary: 'test', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation(makeReadMock(mockMemory, { version: 1, memories: [{ id: 'mem-1', status: 'active' }] }));
await updateMemory('mem-1', { category: 'engineering' });
expect(memoryBM25.indexMemory).not.toHaveBeenCalled();
});
it('should emit memory:updated event', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const mockMemory = { id: 'mem-1', type: 'fact', content: 'test', summary: 'test', category: 'other', tags: [], importance: 0.5, relatedMemories: [], status: 'active', sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', type: 'fact', category: 'other', tags: [], summary: 'test', importance: 0.5, createdAt: '', status: 'active', sourceAppId: null }] });
return Promise.resolve(def);
});
await updateMemory('mem-1', { category: 'updated' });
expect(emitSpy).toHaveBeenCalledWith('memory:updated', { id: 'mem-1', updates: { category: 'updated' } });
});
});
// ===========================================================================
// updateMemoryEmbedding
// ===========================================================================
describe('updateMemoryEmbedding', () => {
it('should update embedding on memory and embeddings file', async () => {
const mockMemory = { id: 'mem-1', embedding: null, embeddingModel: null, updatedAt: '' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
const embedding = [0.5, 0.6, 0.7];
const result = await updateMemoryEmbedding('mem-1', embedding);
expect(result.embedding).toEqual([0.5, 0.6, 0.7]);
expect(result.embeddingModel).toBe('test-embedding-model');
});
it('should return null for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await updateMemoryEmbedding('non-existent', [0.1]);
expect(result).toBeNull();
});
});
// ===========================================================================
// archiveMemory / purgeMemory
// ===========================================================================
describe('archiveMemory / purgeMemory', () => {
it('should archive', async () => {
const mockMemory = { id: 'mem-1', status: 'active', updatedAt: '' };
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'active' }] };
readJSONFile.mockImplementation(makeReadMock(mockMemory, mockIndex));
const result = await archiveMemory('mem-1');
expect(result).toEqual({ success: true, id: 'mem-1' });
expect(rmGuarded).not.toHaveBeenCalled();
// The memory should have been saved with archived status
const memorySaveCall = atomicWrite.mock.calls.find(c => c[0].includes('memory.json'));
expect(memorySaveCall).toBeDefined();
const savedMemory = memorySaveCall[1];
expect(savedMemory.status).toBe('archived');
});
it('should purge', async () => {
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'active' }] };
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { 'mem-1': [0.1, 0.2, 0.3] } };
readJSONFile.mockImplementation(makeReadMock(null, mockIndex, mockEmbeddings));
const result = await purgeMemory('mem-1');
expect(result).toEqual({ success: true, id: 'mem-1' });
expect(rmGuarded).toHaveBeenCalled();
expect(memoryBM25.removeMemoryFromIndex).toHaveBeenCalledWith('mem-1');
});
it('should emit memory:deleted event', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const mockMemory = { id: 'mem-1', status: 'active', updatedAt: '' };
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'active' }] };
readJSONFile.mockImplementation(makeReadMock(mockMemory, mockIndex));
await archiveMemory('mem-1');
expect(emitSpy).toHaveBeenCalledWith('memory:deleted', { id: 'mem-1', hard: false });
});
it('should emit memory:deleted with hard=true on purge', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'active' }] };
readJSONFile.mockImplementation(makeReadMock(null, mockIndex));
await purgeMemory('mem-1');
expect(emitSpy).toHaveBeenCalledWith('memory:deleted', { id: 'mem-1', hard: true });
});
});
// ===========================================================================
// approveMemory
// ===========================================================================
describe('approveMemory', () => {
it('should approve a pending_approval memory', async () => {
const mockMemory = { id: 'mem-1', status: 'pending_approval', sourceAgentId: 'agent-1', updatedAt: '' };
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'pending_approval' }] };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ ...mockIndex, memories: [...mockIndex.memories] });
return Promise.resolve(def);
});
// Exercise the real approval-count side effect behind the public memory workflow.
const lifecycle = await import('./cosAgentLifecycle.js');
lifecycle.getAgent.mockResolvedValue({ memoryExtraction: { pendingApproval: 2, created: 4 } });
lifecycle.updateAgent.mockResolvedValue(undefined);
const actualConfig = await vi.importActual('./memoryConfig.js');
decrementAgentPendingApproval.mockImplementationOnce(actualConfig.decrementAgentPendingApproval);
const result = await approveMemory('mem-1');
expect(lifecycle.updateAgent).toHaveBeenCalledWith('agent-1', {
memoryExtraction: { pendingApproval: 1, created: 4 },
});
expect(result.success).toBe(true);
expect(result.memory.status).toBe('active');
expect(notifications.removeByMetadata).toHaveBeenCalledWith('memoryId', 'mem-1');
expect(decrementAgentPendingApproval).toHaveBeenCalledWith('agent-1');
});
it('should return error for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await approveMemory('non-existent');
expect(result.success).toBe(false);
expect(result.error).toBe('Memory not found');
});
it('should return error if not pending_approval', async () => {
const mockMemory = { id: 'mem-1', status: 'active' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
return Promise.resolve(def);
});
const result = await approveMemory('mem-1');
expect(result.success).toBe(false);
expect(result.error).toBe('Memory is not pending approval');
});
it('should emit memory:approved event', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const mockMemory = { id: 'mem-1', status: 'pending_approval', sourceAgentId: 'agent-1', updatedAt: '' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'pending_approval' }] });
return Promise.resolve(def);
});
await approveMemory('mem-1');
expect(emitSpy).toHaveBeenCalledWith('memory:approved', expect.objectContaining({ id: 'mem-1' }));
});
});
// ===========================================================================
// rejectMemory
// ===========================================================================
describe('rejectMemory', () => {
it('should hard delete a pending_approval memory', async () => {
const mockMemory = { id: 'mem-1', status: 'pending_approval', sourceAgentId: 'agent-1' };
const mockIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'pending_approval' }] };
const mockEmbeddings = { model: 'test', dimension: 0, vectors: {} };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ ...mockIndex, memories: [...mockIndex.memories] });
if (path.includes('embeddings.json')) return Promise.resolve({ ...mockEmbeddings });
return Promise.resolve(def);
});
const result = await rejectMemory('mem-1');
expect(result.success).toBe(true);
expect(rmGuarded).toHaveBeenCalled();
expect(notifications.removeByMetadata).toHaveBeenCalledWith('memoryId', 'mem-1');
expect(decrementAgentPendingApproval).toHaveBeenCalledWith('agent-1');
});
it('should return error for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await rejectMemory('non-existent');
expect(result.success).toBe(false);
expect(result.error).toBe('Memory not found');
});
it('should return error if not pending_approval', async () => {
const mockMemory = { id: 'mem-1', status: 'active' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
return Promise.resolve(def);
});
const result = await rejectMemory('mem-1');
expect(result.success).toBe(false);
expect(result.error).toBe('Memory is not pending approval');
});
it('should emit memory:rejected event', async () => {
const emitSpy = vi.spyOn(cosEvents, 'emit');
const mockMemory = { id: 'mem-1', status: 'pending_approval', sourceAgentId: 'agent-1' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 1, memories: [{ id: 'mem-1', status: 'pending_approval' }] });
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
await rejectMemory('mem-1');
expect(emitSpy).toHaveBeenCalledWith('memory:rejected', { id: 'mem-1' });
});
});
// ===========================================================================
// searchMemories
// ===========================================================================
describe('searchMemories', () => {
it('should return empty when no query embedding provided', async () => {
const result = await searchMemories(null);
expect(result).toEqual({ total: 0, memories: [] });
});
it('should return empty when no embeddings exist', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await searchMemories([0.1, 0.2]);
expect(result).toEqual({ total: 0, memories: [] });
});
it('should filter out non-active results', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', status: 'active', tags: [] },
{ id: 'm2', type: 'fact', status: 'archived', tags: [] }
]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1], m2: [0.2] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findAboveThreshold.mockReturnValue([
{ id: 'm1', similarity: 0.9 },
{ id: 'm2', similarity: 0.85 }
]);
const result = await searchMemories([0.1, 0.2]);
expect(result.total).toBe(1);
expect(result.memories[0].id).toBe('m1');
});
it('should apply type filter', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', category: 'other', status: 'active', tags: [] },
{ id: 'm2', type: 'decision', category: 'other', status: 'active', tags: [] }
]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1], m2: [0.2] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findAboveThreshold.mockReturnValue([
{ id: 'm1', similarity: 0.9 },
{ id: 'm2', similarity: 0.85 }
]);
const result = await searchMemories([0.1], { types: ['fact'] });
expect(result.total).toBe(1);
expect(result.memories[0].id).toBe('m1');
});
it('should apply __not_brain filter', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', status: 'active', tags: [], sourceAppId: 'brain' },
{ id: 'm2', type: 'fact', status: 'active', tags: [], sourceAppId: 'other' }
]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1], m2: [0.2] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findAboveThreshold.mockReturnValue([
{ id: 'm1', similarity: 0.9 },
{ id: 'm2', similarity: 0.85 }
]);
const result = await searchMemories([0.1], { appId: '__not_brain' });
expect(result.total).toBe(1);
expect(result.memories[0].id).toBe('m2');
});
it('should include similarity score in results', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', type: 'fact', status: 'active', tags: [] }]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findAboveThreshold.mockReturnValue([{ id: 'm1', similarity: 0.95 }]);
const result = await searchMemories([0.1]);
expect(result.memories[0].similarity).toBe(0.95);
});
});
// ===========================================================================
// hybridSearchMemories
// ===========================================================================
describe('hybridSearchMemories', () => {
it('should combine BM25 and vector results via RRF', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', status: 'active', tags: [], category: 'other', sourceAppId: null },
{ id: 'm2', type: 'fact', status: 'active', tags: [], category: 'other', sourceAppId: null }
]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1], m2: [0.2] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
memoryBM25.searchBM25.mockResolvedValue([{ id: 'm1', score: 0.8 }]);
findAboveThreshold.mockReturnValue([{ id: 'm2', similarity: 0.9 }]);
const result = await hybridSearchMemories('test query', [0.1, 0.2]);
expect(result.total).toBe(2);
// Both should appear with RRF scores
const ids = result.memories.map(m => m.id);
expect(ids).toContain('m1');
expect(ids).toContain('m2');
});
it('should mark searchMethod correctly', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', type: 'fact', status: 'active', tags: [], category: 'other', sourceAppId: null }]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
memoryBM25.searchBM25.mockResolvedValue([{ id: 'm1', score: 0.8 }]);
findAboveThreshold.mockReturnValue([{ id: 'm1', similarity: 0.9 }]);
const result = await hybridSearchMemories('query', [0.1]);
expect(result.memories[0].searchMethod).toBe('hybrid');
});
it('should handle empty query (no BM25)', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', type: 'fact', status: 'active', tags: [], category: 'other', sourceAppId: null }]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findAboveThreshold.mockReturnValue([{ id: 'm1', similarity: 0.9 }]);
const result = await hybridSearchMemories('', [0.1]);
expect(result.memories[0].searchMethod).toBe('vector');
expect(memoryBM25.searchBM25).not.toHaveBeenCalled();
});
it('should handle no embedding (BM25 only)', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', type: 'fact', status: 'active', tags: [], category: 'other', sourceAppId: null }]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
memoryBM25.searchBM25.mockResolvedValue([{ id: 'm1', score: 0.8 }]);
const result = await hybridSearchMemories('query', null);
expect(result.memories[0].searchMethod).toBe('bm25');
});
it('should filter out non-active in hybrid results', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', type: 'fact', status: 'archived', tags: [], category: 'other', sourceAppId: null }]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
memoryBM25.searchBM25.mockResolvedValue([{ id: 'm1', score: 0.8 }]);
const result = await hybridSearchMemories('query', null);
expect(result.total).toBe(0);
});
});
// ===========================================================================
// rebuildBM25Index
// ===========================================================================
describe('rebuildBM25Index', () => {
it('should rebuild index from active memories', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', status: 'active' },
{ id: 'm2', status: 'archived' }
]
};
const mockMemory = { id: 'm1', content: 'test', type: 'fact', tags: ['t1'], sourceAppId: 'app1' };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (/[\\/]m1[\\/]memory\.json$/.test(path)) return Promise.resolve(mockMemory);
return Promise.resolve(def);
});
memoryBM25.rebuildIndex.mockResolvedValue({ indexed: 1 });
const result = await rebuildBM25Index();
expect(memoryBM25.rebuildIndex).toHaveBeenCalledWith([
expect.objectContaining({ id: 'm1', content: 'test' })
]);
expect(result).toEqual({ indexed: 1 });
});
});
// ===========================================================================
// getBM25Stats
// ===========================================================================
describe('getBM25Stats', () => {
it('should delegate to memoryBM25.getStats', async () => {
memoryBM25.getStats.mockResolvedValue({ documentCount: 42 });
const result = await getBM25Stats();
expect(result).toEqual({ documentCount: 42 });
});
});
// ===========================================================================
// getTimeline
// ===========================================================================
describe('getTimeline', () => {
it('should group active memories by date', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 3,
memories: [
{ id: 'm1', createdAt: '2025-01-15T10:00:00.000Z', status: 'active', sourceAppId: null },
{ id: 'm2', createdAt: '2025-01-15T14:00:00.000Z', status: 'active', sourceAppId: null },
{ id: 'm3', createdAt: '2025-01-16T08:00:00.000Z', status: 'active', sourceAppId: null }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline();
expect(timeline['2025-01-15']).toHaveLength(2);
expect(timeline['2025-01-16']).toHaveLength(1);
});
it('should filter by date range', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', createdAt: '2025-01-10T00:00:00.000Z', status: 'active', sourceAppId: null },
{ id: 'm2', createdAt: '2025-01-20T00:00:00.000Z', status: 'active', sourceAppId: null }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline({ startDate: '2025-01-15T00:00:00.000Z' });
expect(Object.keys(timeline)).toHaveLength(1);
expect(timeline['2025-01-20']).toBeDefined();
});
it('should compare a boundary carrying an offset as an instant, not a string', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
// 03:00Z is BEFORE the 2025-01-15T05:00:00+02:00 boundary (03:00Z)…
{ id: 'm1', createdAt: '2025-01-15T02:00:00.000Z', status: 'active', sourceAppId: null },
// …and 04:00Z is after it, though both sort ahead of it as strings.
{ id: 'm2', createdAt: '2025-01-15T04:00:00.000Z', status: 'active', sourceAppId: null }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline({ startDate: '2025-01-15T05:00:00+02:00' });
expect(timeline['2025-01-15']).toHaveLength(1);
expect(timeline['2025-01-15'][0].id).toBe('m2');
});
it('should filter by types', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', createdAt: '2025-01-15T00:00:00.000Z', status: 'active', sourceAppId: null },
{ id: 'm2', type: 'decision', createdAt: '2025-01-15T00:00:00.000Z', status: 'active', sourceAppId: null }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline({ types: ['fact'] });
expect(timeline['2025-01-15']).toHaveLength(1);
});
it('should exclude archived memories', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', createdAt: '2025-01-15T00:00:00.000Z', status: 'active', sourceAppId: null },
{ id: 'm2', createdAt: '2025-01-15T00:00:00.000Z', status: 'archived', sourceAppId: null }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline();
expect(timeline['2025-01-15']).toHaveLength(1);
});
it('should apply limit', async () => {
const memories = Array.from({ length: 10 }, (_, i) => ({
id: `m${i}`, createdAt: `2025-01-${String(i + 10).padStart(2, '0')}T00:00:00.000Z`, status: 'active', sourceAppId: null
}));
const mockIndex = { version: 1, lastUpdated: '', count: 10, memories };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline({ limit: 3 });
const totalEntries = Object.values(timeline).reduce((sum, arr) => sum + arr.length, 0);
expect(totalEntries).toBe(3);
});
it('should filter by __not_brain appId', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', createdAt: '2025-01-15T00:00:00.000Z', status: 'active', sourceAppId: 'brain' },
{ id: 'm2', createdAt: '2025-01-15T00:00:00.000Z', status: 'active', sourceAppId: 'other' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const timeline = await getTimeline({ appId: '__not_brain' });
expect(timeline['2025-01-15']).toHaveLength(1);
expect(timeline['2025-01-15'][0].sourceAppId).toBe('other');
});
});
// ===========================================================================
// getCategories
// ===========================================================================
describe('getCategories', () => {
it('should return unique categories with counts', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 3,
memories: [
{ id: 'm1', category: 'science', status: 'active' },
{ id: 'm2', category: 'science', status: 'active' },
{ id: 'm3', category: 'engineering', status: 'active' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const categories = await getCategories();
expect(categories).toContainEqual({ name: 'science', count: 2 });
expect(categories).toContainEqual({ name: 'engineering', count: 1 });
});
it('should exclude archived memories', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', category: 'science', status: 'active' },
{ id: 'm2', category: 'science', status: 'archived' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const categories = await getCategories();
expect(categories).toEqual([{ name: 'science', count: 1 }]);
});
it('should return empty array when no active memories', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const categories = await getCategories();
expect(categories).toEqual([]);
});
});
// ===========================================================================
// getTags
// ===========================================================================
describe('getTags', () => {
it('should return unique tags with counts sorted by count desc', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 3,
memories: [
{ id: 'm1', tags: ['react', 'js'], status: 'active' },
{ id: 'm2', tags: ['react', 'node'], status: 'active' },
{ id: 'm3', tags: ['python'], status: 'active' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const tags = await getTags();
expect(tags[0]).toEqual({ name: 'react', count: 2 });
expect(tags).toContainEqual({ name: 'js', count: 1 });
expect(tags).toContainEqual({ name: 'node', count: 1 });
expect(tags).toContainEqual({ name: 'python', count: 1 });
});
it('should exclude archived memories', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', tags: ['react'], status: 'active' },
{ id: 'm2', tags: ['react', 'vue'], status: 'archived' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
return Promise.resolve(def);
});
const tags = await getTags();
expect(tags).toEqual([{ name: 'react', count: 1 }]);
});
});
// ===========================================================================
// getRelatedMemories
// ===========================================================================
describe('getRelatedMemories', () => {
it('should return explicitly linked memories', async () => {
const mockMemory = { id: 'mem-1', relatedMemories: ['mem-2'], embedding: null };
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'mem-1', status: 'active' },
{ id: 'mem-2', status: 'active', summary: 'linked' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
const related = await getRelatedMemories('mem-1');
expect(related).toHaveLength(1);
expect(related[0].relationship).toBe('linked');
expect(related[0].similarity).toBe(1.0);
});
it('should include similar memories by embedding', async () => {
const mockMemory = { id: 'mem-1', relatedMemories: [], embedding: [0.1, 0.2] };
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'mem-1', status: 'active' },
{ id: 'mem-3', status: 'active', summary: 'similar' }
]
};
const mockEmbeddings = { model: 'test', dimension: 2, vectors: { 'mem-1': [0.1, 0.2], 'mem-3': [0.15, 0.25] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
findTopK.mockReturnValue([{ id: 'mem-3', similarity: 0.85 }]);
const related = await getRelatedMemories('mem-1');
expect(related).toHaveLength(1);
expect(related[0].relationship).toBe('similar');
expect(related[0].similarity).toBe(0.85);
});
it('should return empty for non-existent memory', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const related = await getRelatedMemories('non-existent');
expect(related).toEqual([]);
});
it('should not duplicate linked and similar results', async () => {
const mockMemory = { id: 'mem-1', relatedMemories: ['mem-2'], embedding: [0.1] };
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'mem-1', status: 'active' },
{ id: 'mem-2', status: 'active' }
]
};
const mockEmbeddings = { model: 'test', dimension: 1, vectors: { 'mem-1': [0.1], 'mem-2': [0.15] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
// findTopK returns mem-2 as similar too
findTopK.mockReturnValue([{ id: 'mem-2', similarity: 0.9 }]);
const related = await getRelatedMemories('mem-1');
expect(related).toHaveLength(1);
expect(related[0].relationship).toBe('linked');
});
it('should respect limit parameter', async () => {
const mockMemory = { id: 'mem-1', relatedMemories: ['mem-2', 'mem-3', 'mem-4'], embedding: null };
const mockIndex = {
version: 1, lastUpdated: '', count: 4,
memories: [
{ id: 'mem-1', status: 'active' },
{ id: 'mem-2', status: 'active' },
{ id: 'mem-3', status: 'active' },
{ id: 'mem-4', status: 'active' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
const related = await getRelatedMemories('mem-1', 2);
expect(related).toHaveLength(2);
});
});
// ===========================================================================
// linkMemories
// ===========================================================================
describe('linkMemories', () => {
it('should create bidirectional links', async () => {
const source = { id: 'src', relatedMemories: [], updatedAt: '' };
const target = { id: 'tgt', relatedMemories: [], updatedAt: '' };
let callCount = 0;
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) {
callCount++;
// First call is source, second is target
return Promise.resolve(callCount <= 1 ? { ...source } : { ...target });
}
return Promise.resolve(def);
});
const result = await linkMemories('src', 'tgt');
expect(result.success).toBe(true);
expect(result.sourceId).toBe('src');
expect(result.targetId).toBe('tgt');
// Both memories should be saved with the link
const memorySaves = atomicWrite.mock.calls.filter(c => c[0].includes('memory.json'));
expect(memorySaves.length).toBe(2);
});
it('stores a directed typed link on the source only', async () => {
const source = { id: 'src', relatedMemories: [], updatedAt: '' };
const target = { id: 'tgt', relatedMemories: [], updatedAt: '' };
let callCount = 0;
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) {
callCount++;
return Promise.resolve(callCount <= 1 ? { ...source } : { ...target });
}
return Promise.resolve(def);
});
const result = await linkMemories('src', 'tgt', { linkType: 'contradicts', note: 'n' });
expect(result).toMatchObject({ success: true, linkType: 'contradicts', linkId: expect.any(String) });
const memorySaves = atomicWrite.mock.calls.filter(c => c[0].includes('memory.json'));
expect(memorySaves.length).toBe(1);
expect(JSON.stringify(memorySaves[0][1])).toContain('"linkType":"contradicts"');
});
it('should return error when source not found', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const result = await linkMemories('missing-src', 'missing-tgt');
expect(result.success).toBe(false);
expect(result.error).toBe('Memory not found');
});
it('should not duplicate existing links', async () => {
const source = { id: 'src', relatedMemories: ['tgt'], updatedAt: '' };
const target = { id: 'tgt', relatedMemories: ['src'], updatedAt: '' };
let callCount = 0;
readJSONFile.mockImplementation((path, def) => {
if (path.includes('memory.json')) {
callCount++;
return Promise.resolve(callCount <= 1 ? { ...source } : { ...target });
}
return Promise.resolve(def);
});
await linkMemories('src', 'tgt');
// Should not add duplicate - memories saved but relatedMemories should still be length 1
const memorySaves = atomicWrite.mock.calls.filter(c => c[0].includes('memory.json'));
for (const save of memorySaves) {
const saved = save[1];
expect(saved.relatedMemories).toHaveLength(1);
}
});
});
// ===========================================================================
// getGraphData
// ===========================================================================
describe('getGraphData', () => {
it('should return nodes and edges', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', category: 'science', summary: 'test1', importance: 0.8, status: 'active' },
{ id: 'm2', type: 'decision', category: 'eng', summary: 'test2', importance: 0.6, status: 'active' }
]
};
const mockMem1 = { id: 'm1', relatedMemories: ['m2'] };
const mockMem2 = { id: 'm2', relatedMemories: [] };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
if (/[\\/]m1[\\/]memory\.json$/.test(path)) return Promise.resolve(mockMem1);
if (/[\\/]m2[\\/]memory\.json$/.test(path)) return Promise.resolve(mockMem2);
return Promise.resolve(def);
});
const result = await getGraphData();
expect(result.nodes).toHaveLength(2);
expect(result.edges).toHaveLength(1);
expect(result.edges[0].type).toBe('linked');
});
it('should exclude archived memories from nodes', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', type: 'fact', category: 'other', summary: 'test', importance: 0.5, status: 'active' },
{ id: 'm2', type: 'fact', category: 'other', summary: 'archived', importance: 0.5, status: 'archived' }
]
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
if (/[\\/]m1[\\/]memory\.json$/.test(path)) return Promise.resolve({ id: 'm1', relatedMemories: [] });
return Promise.resolve(def);
});
const result = await getGraphData();
expect(result.nodes).toHaveLength(1);
});
// #10953: a scoped read equals the full graph filtered to scoped endpoints,
// ranking similarity against every vector. m1's global top three are
// m2, m3, m5 (m3/m5 out of scope); the in-scope m4 is fourth. A scope applied
// BEFORE the top-K would promote m4 and invent an m1–m4 edge.
it('scopes to sourceIds without promoting a lower-ranked in-scope neighbour', async () => {
const { findTopK: realFindTopK } = await vi.importActual('../lib/vectorMath.js');
findTopK.mockImplementation(realFindTopK);
try {
const meta = (id, status = 'active') => ({ id, type: 'fact', category: 'other', summary: id, importance: 0.5, status });
const ids = ['m1', 'm2', 'm3', 'm4', 'm5', 'm6', 'm7', 'm8'];
const mockIndex = { version: 1, lastUpdated: '', count: 9, memories: [...ids.map(id => meta(id)), meta('m9', 'archived')] };
const vectors = {
m1: [1, 0, 0, 0], m2: [1, 0.1, 0, 0], m3: [1, 0.15, 0, 0], m5: [1, 0, 0.2, 0],
m4: [1, 0, 0, 0.45], m6: [1, 0, 0, 0.5], m7: [1, 0, 0, 0.55], m8: [1, 0, 0, 0.6]
};
const files = {
m2: { id: 'm2', relatedMemories: ['m4'], typedLinks: [{ id: 'l1', targetId: 'm4', linkType: 'supersedes' }] },
m4: { id: 'm4', relatedMemories: ['m2', 'm6', 'm9'] }
};
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve({ model: 'test', dimension: 4, vectors });
const id = path.match(/[\\/](m\d)[\\/]memory\.json$/)?.[1];
if (id) return Promise.resolve(files[id] ?? { id, relatedMemories: [] });
return Promise.resolve(def);
});
const scope = new Set(['m1', 'm2', 'm4', 'm9', 'not-a-memory']);
const full = await getGraphData();
const scoped = await getGraphData({ sourceIds: [...scope] });
expect(full.edges.length).toBeGreaterThan(scoped.edges.length);
expect(scoped).toEqual({
nodes: full.nodes.filter(n => scope.has(n.id)),
edges: full.edges.filter(e => scope.has(e.source) && scope.has(e.target))
});
const pairs = scoped.edges.map(e => `${[e.source, e.target].sort().join('-')}:${e.type}`);
expect(pairs).toContain('m1-m2:similar');
expect(pairs).not.toContain('m1-m4:similar');
// The archived m9 is linked from m4 in BOTH modes (the full graph does not
// gate relatedMemories targets on status); scoping must not change that.
expect(pairs).toContain('m4-m9:linked');
// Empty scope stays empty (no file reads); absent scope stays the full graph.
readJSONFile.mockClear();
expect(await getGraphData({ sourceIds: [] })).toEqual({ nodes: [], edges: [] });
expect(readJSONFile).not.toHaveBeenCalled();
expect(await getGraphData({})).toEqual(full);
} finally {
findTopK.mockReturnValue([]);
}
});
});
// ===========================================================================
// consolidateMemories
// ===========================================================================
describe('consolidateMemories', () => {
it('should return dry run results without modifying data', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 2,
memories: [
{ id: 'm1', summary: 'Similar A', importance: 0.8, status: 'active' },
{ id: 'm2', summary: 'Similar B', importance: 0.6, status: 'active' }
]
};
const mockEmbeddings = { model: 'test', dimension: 2, vectors: { m1: [0.1, 0.2], m2: [0.15, 0.25] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
clusterBySimilarity.mockReturnValue([
[{ id: 'm1', summary: 'Similar A' }, { id: 'm2', summary: 'Similar B' }]
]);
const result = await consolidateMemories(0.9, true);
expect(result.dryRun).toBe(true);
expect(result.clustersFound).toBe(1);
expect(result.memoriesAffected).toBe(2);
});
it('should return no clusters when all are unique', async () => {
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 0, memories: [] });
if (path.includes('embeddings.json')) return Promise.resolve({ model: null, dimension: 0, vectors: {} });
return Promise.resolve(def);
});
clusterBySimilarity.mockReturnValue([]);
const result = await consolidateMemories(0.9, true);
expect(result.clustersFound).toBe(0);
});
});
// ===========================================================================
// applyDecay
// ===========================================================================
describe('applyDecay', () => {
it('preserves protected records during background decay and expiration', async () => {
const record = { id: 'protected', status: 'active', importance: 0.1, tags: ['mind:core-identity'], createdAt: '2000-01-01T00:00:00.000Z', expiresAt: '2001-01-01T00:00:00.000Z' };
readJSONFile.mockImplementation((path, fallback) => {
if (path.includes('index.json')) return Promise.resolve({ memories: [record], count: 1 });
if (path.includes('memory.json')) return Promise.resolve(record);
return Promise.resolve(fallback);
});
expect(await applyDecay()).toEqual({ updated: 0 });
expect(await clearExpired()).toEqual({ cleared: 0 });
expect(atomicWrite).not.toHaveBeenCalled();
});
it('should apply decay to old memories', async () => {
const oldDate = new Date(Date.now() - 100 * 24 * 60 * 60 * 1000).toISOString(); // 100 days ago
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', status: 'active' }]
};
const mockMemory = { id: 'm1', importance: 0.5, createdAt: oldDate, lastAccessed: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
return Promise.resolve(def);
});
const result = await applyDecay(0.01);
expect(result.updated).toBeGreaterThanOrEqual(0);
});
it('should return zero updates when no memories exist', async () => {
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve({ version: 1, lastUpdated: '', count: 0, memories: [] });
return Promise.resolve(def);
});
const result = await applyDecay();
expect(result.updated).toBe(0);
});
});
// ===========================================================================
// clearExpired
// ===========================================================================
describe('clearExpired', () => {
it('should clear expired memories', async () => {
const pastDate = '2020-01-01T00:00:00.000Z';
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', status: 'active' }]
};
const mockMemory = { id: 'm1', expiresAt: pastDate, status: 'active', content: 'test', summary: 'test', category: 'other', tags: [], importance: 0.5, relatedMemories: [], sourceAppId: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve({ ...mockIndex, memories: [...mockIndex.memories] });
if (path.includes('memory.json')) return Promise.resolve({ ...mockMemory });
return Promise.resolve(def);
});
const result = await clearExpired();
expect(result.cleared).toBe(1);
});
it('should not clear non-expired memories', async () => {
const futureDate = '2099-01-01T00:00:00.000Z';
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', status: 'active' }]
};
const mockMemory = { id: 'm1', expiresAt: futureDate };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('memory.json')) return Promise.resolve(mockMemory);
return Promise.resolve(def);
});
const result = await clearExpired();
expect(result.cleared).toBe(0);
});
it('should skip memories without expiresAt', async () => {
const mockIndex = {
version: 1, lastUpdated: '', count: 1,
memories: [{ id: 'm1', status: 'active' }]
};
const mockMemory = { id: 'm1', expiresAt: null };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('memory.json')) return Promise.resolve(mockMemory);
return Promise.resolve(def);
});
const result = await clearExpired();
expect(result.cleared).toBe(0);
});
});
// ===========================================================================
// getStats
// ===========================================================================
describe('getStats', () => {
it('should return correct stats breakdown', async () => {
const mockIndex = {
version: 1, lastUpdated: '2025-01-01T00:00:00.000Z', count: 4,
memories: [
{ id: 'm1', type: 'fact', category: 'science', status: 'active' },
{ id: 'm2', type: 'decision', category: 'engineering', status: 'active' },
{ id: 'm3', type: 'fact', category: 'science', status: 'archived' },
{ id: 'm4', type: 'fact', category: 'other', status: 'pending_approval' }
]
};
const mockEmbeddings = { model: 'test', dimension: 3, vectors: { m1: [0.1], m2: [0.2] } };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(mockIndex);
if (path.includes('embeddings.json')) return Promise.resolve(mockEmbeddings);
return Promise.resolve(def);
});
const stats = await getStats();
expect(stats.total).toBe(4);
expect(stats.active).toBe(2);
expect(stats.archived).toBe(1);
expect(stats.pendingApproval).toBe(1);
expect(stats.expired).toBe(0);
expect(stats.withEmbeddings).toBe(2);
expect(stats.byType.fact).toBe(3);
expect(stats.byType.decision).toBe(1);
expect(stats.byCategory.science).toBe(2);
expect(stats.lastUpdated).toBe('2025-01-01T00:00:00.000Z');
});
it('should handle empty index', async () => {
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
const stats = await getStats();
expect(stats.total).toBe(0);
expect(stats.active).toBe(0);
expect(stats.withEmbeddings).toBe(0);
});
});
// ===========================================================================
// invalidateCaches
// ===========================================================================
describe('invalidateCaches', () => {
it('should force reload on next access', async () => {
// First call loads and caches
readJSONFile.mockImplementation((path, def) => Promise.resolve(def));
await getStats();
// Reset readJSONFile to return different data
const newIndex = { version: 1, lastUpdated: '', count: 1, memories: [{ id: 'm1', type: 'fact', category: 'x', status: 'active' }] };
readJSONFile.mockImplementation((path, def) => {
if (path.includes('index.json')) return Promise.resolve(newIndex);
return Promise.resolve(def);
});
invalidateCaches();
const stats = await getStats();
expect(stats.total).toBe(1);
});
});
// ===========================================================================
// flushBM25Index
// ===========================================================================
describe('flushBM25Index', () => {
it('should delegate to memoryBM25.flush', async () => {
await flushBM25Index();
expect(memoryBM25.flush).toHaveBeenCalled();
});
});
});