Skip to content

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

21.6 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';
import memoryRoutes from './memory.js';

// Mock the memory backend service
vi.mock('../services/memoryBackend.js', () => ({
  ensureBackend: vi.fn(),
  getMemories: vi.fn(),
  getStats: vi.fn(),
  getCategories: vi.fn(),
  getTags: vi.fn(),
  getTimeline: vi.fn(),
  getGraphData: vi.fn(),
  getMemory: vi.fn(),
  getMemoryVersion: vi.fn(),
  getMemoryVersions: vi.fn(),
  getRelatedMemories: vi.fn(),
  createMemory: vi.fn(),
  updateMemory: vi.fn(),
  updateMemoryEmbedding: vi.fn(),
  archiveMemory: vi.fn(),
  purgeMemory: vi.fn(),
  searchMemories: vi.fn(),
  consolidateMemories: vi.fn(),
  linkMemories: vi.fn(),
  applyDecay: vi.fn(),
  clearExpired: vi.fn(),
  approveMemory: vi.fn(),
  rejectMemory: vi.fn()
}));

// Mock the db health check
vi.mock('../lib/db.js', () => ({
  checkHealth: vi.fn()
}));

// Mock the embedding service
vi.mock('../services/memoryEmbeddings.js', () => ({
  generateQueryEmbedding: vi.fn(),
  generateMemoryEmbedding: vi.fn(),
  checkAvailability: vi.fn()
}));

vi.mock('../services/memoryRunUsage.js', () => ({
  findRecentRunsUsingMemory: vi.fn()
}));

// Mock the sync service
vi.mock('../services/memorySync.js', () => ({
  getChangesSince: vi.fn(),
  applyRemoteChanges: vi.fn()
}));

// The real peer-pull gate runs; only the peer registry and settings it reads
// are stubbed, as in routes/dataSync.test.js.
const peers = [];
vi.mock('../services/instances.js', async () => ({
  ...(await vi.importActual('../services/instances.js')),
  getPeers: async () => peers,
}));
let settings = {};
vi.mock('../services/settings.js', async () => ({
  ...(await vi.importActual('../services/settings.js')),
  getSettings: async () => settings,
}));

import { PEER_INSTANCE_ID_HEADER } from '../services/sharing/peerPullAuthorization.js';
import { ensureBackend, getMemories, getTimeline, archiveMemory, purgeMemory, applyDecay, linkMemories } from '../services/memoryBackend.js';
import { checkHealth } from '../lib/db.js';
import * as memorySync from '../services/memorySync.js';
import { findRecentRunsUsingMemory } from '../services/memoryRunUsage.js';

describe('Memory Routes', () => {
  it('GET /:id/runs lists recent runs that used the memory (#10495)', async () => {
    const app = express();
    app.use('/api/memory', memoryRoutes);
    findRecentRunsUsingMemory.mockResolvedValue([{ runId: 'r1', agentId: 'a1' }]);
    const res = await request(app).get('/api/memory/mem-1/runs');
    expect(res.status).toBe(200);
    expect(res.body.runs).toEqual([{ runId: 'r1', agentId: 'a1' }]);
    expect(findRecentRunsUsingMemory).toHaveBeenCalledWith('mem-1');
  });

  let app;

  beforeEach(() => {
    app = express();
    app.use(express.json());
    app.use('/api/memory', memoryRoutes);
    vi.clearAllMocks();
    settings = {};
    peers.length = 0;
  });

  describe('DELETE /api/memory/:id', () => {
    it.each([
      ['../outside', 404],
      ['%2Ftmp', 400],
      ['nested%2Fmemory', 400],
    ])('rejects unsafe memory id %j', async (id, status) => {
      const response = await request(app).delete(`/api/memory/${id}`);

      expect(response.status).toBe(status);
      expect(archiveMemory).not.toHaveBeenCalled();
      expect(purgeMemory).not.toHaveBeenCalled();
    });

    it('does not route an empty memory id to deletion', async () => {
      const response = await request(app).delete('/api/memory/');

      expect(response.status).toBe(404);
      expect(archiveMemory).not.toHaveBeenCalled();
      expect(purgeMemory).not.toHaveBeenCalled();
    });

    it('purges a valid memory id when hard=true', async () => {
      purgeMemory.mockResolvedValue({ success: true });

      const response = await request(app).delete('/api/memory/mem-42?hard=true');

      expect(response.status).toBe(200);
      expect(purgeMemory).toHaveBeenCalledWith('mem-42');
      expect(archiveMemory).not.toHaveBeenCalled();
    });

    it('archives a valid memory id by default', async () => {
      archiveMemory.mockResolvedValue({ success: true });

      const response = await request(app).delete('/api/memory/mem-42');

      expect(response.status).toBe(200);
      expect(archiveMemory).toHaveBeenCalledWith('mem-42', {});
      expect(purgeMemory).not.toHaveBeenCalled();
    });
  });

  // ===========================================================================
  // BACKEND STATUS
  // ===========================================================================

  describe('GET /api/memory/backend/status', () => {
    it('should return backend name and health info', async () => {
      ensureBackend.mockResolvedValue('postgres');
      checkHealth.mockResolvedValue({ connected: true, hasSchema: true });

      const response = await request(app).get('/api/memory/backend/status');

      expect(response.status).toBe(200);
      expect(response.body.backend).toBe('postgres');
      expect(response.body.db.connected).toBe(true);
    });

    it('should return file backend when postgres is unavailable', async () => {
      ensureBackend.mockResolvedValue('file');
      checkHealth.mockResolvedValue({ connected: false, error: 'connection refused' });

      const response = await request(app).get('/api/memory/backend/status');

      expect(response.status).toBe(200);
      expect(response.body.backend).toBe('file');
      expect(response.body.db.connected).toBe(false);
    });
  });

  // ===========================================================================
  // SYNC - GET
  // ===========================================================================

  describe('GET /api/memory/sync', () => {
    it('should return 400 when backend is not postgres', async () => {
      ensureBackend.mockResolvedValue('file');

      const response = await request(app).get('/api/memory/sync');

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/PostgreSQL/);
    });

    it('should return changes since sequence when backend is postgres', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.getChangesSince.mockResolvedValue({
        memories: [{ id: 'mem-001' }],
        maxSequence: '42'
      });

      const response = await request(app).get('/api/memory/sync?since=10&limit=50');

      expect(response.status).toBe(200);
      expect(response.body.maxSequence).toBe('42');
      expect(memorySync.getChangesSince).toHaveBeenCalledWith('10', 50);
    });

    it('should default since to 0 and limit to 100', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.getChangesSince.mockResolvedValue({ memories: [], maxSequence: '0' });

      await request(app).get('/api/memory/sync');

      expect(memorySync.getChangesSince).toHaveBeenCalledWith('0', 100);
    });

    it('should cap limit at 1000', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.getChangesSince.mockResolvedValue({ memories: [], maxSequence: '0' });

      await request(app).get('/api/memory/sync?limit=5000');

      expect(memorySync.getChangesSince).toHaveBeenCalledWith('0', 1000);
    });

    it('forwards the sender schema version', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.getChangesSince.mockResolvedValue({ memories: [], maxSequence: '0' });

      const response = await request(app).get('/api/memory/sync?since=10&limit=50&schemaVersion=3');

      expect(response.status).toBe(200);
      expect(memorySync.getChangesSince).toHaveBeenCalledWith('10', 50, 3);
    });

    it('strict mode refuses a peer the user does not share memory with', async () => {
      ensureBackend.mockResolvedValue('postgres');
      settings = { federation: { strictPullAuthorization: true } };
      peers.splice(0, peers.length, {
        instanceId: 'peer-a-instance-id', enabled: true, syncEnabled: true,
        directions: ['outbound', 'inbound'], syncCategories: { brain: true, memory: false },
      });

      const response = await request(app).get('/api/memory/sync').set(PEER_INSTANCE_ID_HEADER, 'peer-a-instance-id');

      expect(response.status).toBe(403);
      expect(memorySync.getChangesSince).not.toHaveBeenCalled();
    });

    it('passes a schema-version conflict through at the HTTP boundary', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.getChangesSince.mockRejectedValue(Object.assign(new Error('schema version is ahead'), { status: 409 }));

      const response = await request(app).get('/api/memory/sync?schemaVersion=99');

      expect(response.status).toBe(409);
      expect(response.body.error).toMatch(/schema version is ahead/);
    });
  });

  // ===========================================================================
  // SYNC - POST
  // ===========================================================================

  describe('POST /api/memory/sync', () => {
    it('should return 400 when backend is not postgres', async () => {
      ensureBackend.mockResolvedValue('file');

      const response = await request(app)
        .post('/api/memory/sync')
        .send({ memories: [] });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/PostgreSQL/);
    });

    it('should return 400 when body is not an array', async () => {
      ensureBackend.mockResolvedValue('postgres');

      const response = await request(app)
        .post('/api/memory/sync')
        .send({ memories: 'not-an-array' });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/Validation failed/);
    });

    it('should return 400 when memories key is missing', async () => {
      ensureBackend.mockResolvedValue('postgres');

      const response = await request(app)
        .post('/api/memory/sync')
        .send({});

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/Validation failed/);
    });

    it('should return 400 when memory item has invalid id', async () => {
      ensureBackend.mockResolvedValue('postgres');

      const response = await request(app)
        .post('/api/memory/sync')
        .send({ memories: [{ id: 'not-a-uuid', type: 'fact', content: 'test', createdAt: '2024-01-01T00:00:00.000Z', updatedAt: '2024-01-01T00:00:00.000Z' }] });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/Validation failed/);
    });

    it('should apply remote changes when body is valid', async () => {
      ensureBackend.mockResolvedValue('postgres');
      const remoteMems = [{
        id: '00000000-0000-0000-0000-000000000001',
        type: 'fact',
        content: 'synced memory',
        createdAt: '2024-01-01T00:00:00.000Z',
        updatedAt: '2024-01-01T00:00:00.000Z'
      }];
      memorySync.applyRemoteChanges.mockResolvedValue({ inserted: 1, updated: 0, skipped: 0 });

      const response = await request(app)
        .post('/api/memory/sync')
        .send({ memories: remoteMems });

      expect(response.status).toBe(200);
      expect(response.body.inserted).toBe(1);
      expect(memorySync.applyRemoteChanges).toHaveBeenCalledWith(
        expect.arrayContaining([expect.objectContaining({ id: '00000000-0000-0000-0000-000000000001', type: 'fact', content: 'synced memory' })])
      );
    });

    it('forwards the sender schema version with remote changes', async () => {
      ensureBackend.mockResolvedValue('postgres');
      memorySync.applyRemoteChanges.mockResolvedValue({ inserted: 0, updated: 0, skipped: 0 });

      const response = await request(app)
        .post('/api/memory/sync')
        .send({ memories: [], schemaVersion: 3 });

      expect(response.status).toBe(200);
      expect(memorySync.applyRemoteChanges).toHaveBeenCalledWith([], 3);
    });
  });

  // ===========================================================================
  // LIST
  // ===========================================================================

  describe('GET /api/memory', () => {
    it('should pass schema defaults through when no filters are given', async () => {
      getMemories.mockResolvedValue({ memories: [], total: 0 });

      const response = await request(app).get('/api/memory');

      expect(response.status).toBe(200);
      expect(getMemories).toHaveBeenCalledWith({
        status: 'active',
        limit: 50,
        offset: 0,
        sortBy: 'createdAt',
        sortOrder: 'desc'
      });
    });

    it('should split csv filters and coerce numeric params', async () => {
      getMemories.mockResolvedValue({ memories: [], total: 0 });

      const response = await request(app)
        .get('/api/memory?types=fact,learning&categories=codebase&tags=a,b&status=archived&appId=brain&limit=10&offset=5&sortBy=importance&sortOrder=asc');

      expect(response.status).toBe(200);
      expect(getMemories).toHaveBeenCalledWith({
        types: ['fact', 'learning'],
        categories: ['codebase'],
        tags: ['a', 'b'],
        status: 'archived',
        appId: 'brain',
        limit: 10,
        offset: 5,
        sortBy: 'importance',
        sortOrder: 'asc'
      });
    });

    it('should reject a limit above the 500 ceiling', async () => {
      const response = await request(app).get('/api/memory?limit=501');

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/Validation failed/);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject an unknown memory type', async () => {
      const response = await request(app).get('/api/memory?types=fact,nonsense');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject a non-numeric limit instead of silently defaulting', async () => {
      const response = await request(app).get('/api/memory?limit=abc');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject an unknown sortBy', async () => {
      const response = await request(app).get('/api/memory?sortBy=unknown');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject an unknown sortOrder', async () => {
      const response = await request(app).get('/api/memory?sortOrder=up');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject a negative offset', async () => {
      const response = await request(app).get('/api/memory?offset=-1');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });

    it('should reject an unknown status', async () => {
      const response = await request(app).get('/api/memory?status=deleted');

      expect(response.status).toBe(400);
      expect(getMemories).not.toHaveBeenCalled();
    });
  });

  // ===========================================================================
  // TIMELINE
  // ===========================================================================

  describe('GET /api/memory/timeline', () => {
    it('should pass the default limit through', async () => {
      getTimeline.mockResolvedValue({});

      const response = await request(app).get('/api/memory/timeline');

      expect(response.status).toBe(200);
      expect(getTimeline).toHaveBeenCalledWith({ limit: 100 });
    });

    it('should pass validated date range, types and limit', async () => {
      getTimeline.mockResolvedValue({});

      const response = await request(app)
        .get('/api/memory/timeline?startDate=2026-01-01T00:00:00.000Z&endDate=2026-01-31&types=fact&limit=5');

      expect(response.status).toBe(200);
      expect(getTimeline).toHaveBeenCalledWith({
        startDate: '2026-01-01T00:00:00.000Z',
        endDate: '2026-01-31',
        types: ['fact'],
        limit: 5
      });
    });

    it('should reject a malformed date boundary', async () => {
      const response = await request(app).get('/api/memory/timeline?startDate=yesterday');

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/Validation failed/);
      expect(getTimeline).not.toHaveBeenCalled();
    });

    it('should reject a limit above the 500 ceiling', async () => {
      const response = await request(app).get('/api/memory/timeline?limit=501');

      expect(response.status).toBe(400);
      expect(getTimeline).not.toHaveBeenCalled();
    });

    it('should forward the appId filter to the backend', async () => {
      getTimeline.mockResolvedValue({});

      const response = await request(app).get('/api/memory/timeline?appId=__not_brain');

      expect(response.status).toBe(200);
      expect(getTimeline).toHaveBeenCalledWith({ appId: '__not_brain', limit: 100 });
    });

    it('should reject a date that matches the shape but is not a real day', async () => {
      const response = await request(app).get('/api/memory/timeline?startDate=2026-02-30');

      expect(response.status).toBe(400);
      expect(getTimeline).not.toHaveBeenCalled();
    });
  });

  describe('POST /api/memory/decay', () => {
    it.each([[{ decayRate: 5 }], [{ decayRate: -1 }], [{ decayRate: 'abc' }], [{ decayRate: 0 }], [{ decayRate: null }]])(
      'rejects %j without applying decay', async (body) => {
        const response = await request(app).post('/api/memory/decay').send(body);
        expect(response.status).toBe(400);
        expect(response.body.code).toBe('VALIDATION_ERROR');
        expect(applyDecay).not.toHaveBeenCalled();
      });

    it('applies the default rate for an empty object or no body', async () => {
      applyDecay.mockResolvedValue({});
      expect((await request(app).post('/api/memory/decay').send({})).status).toBe(200);
      expect((await request(app).post('/api/memory/decay')).status).toBe(200);
      expect(applyDecay).toHaveBeenCalledTimes(2);
      expect(applyDecay).toHaveBeenNthCalledWith(1, 0.01);
      expect(applyDecay).toHaveBeenNthCalledWith(2, 0.01);
    });

    it('accepts the maximum rate', async () => {
      applyDecay.mockResolvedValue({});
      const response = await request(app).post('/api/memory/decay').send({ decayRate: 0.02 });
      expect(response.status).toBe(200);
      expect(applyDecay).toHaveBeenCalledWith(0.02);
    });
  });

  describe('POST /api/memory/link', () => {
    const sourceId = '550e8400-e29b-41d4-a716-446655440000';
    const targetId = '550e8400-e29b-41d4-a716-446655440001';

    it('passes a typed link and its note through to the backend', async () => {
      linkMemories.mockResolvedValue({ success: true, sourceId, targetId, linkType: 'supersedes', linkId: 'id-1' });

      const response = await request(app).post('/api/memory/link')
        .send({ sourceId, targetId, linkType: 'supersedes', note: 'newer decision' });

      expect(response.status).toBe(200);
      expect(response.body.linkType).toBe('supersedes');
      expect(linkMemories).toHaveBeenCalledWith(sourceId, targetId, { linkType: 'supersedes', note: 'newer decision', createdBy: undefined });
    });

    it('keeps an untyped legacy call valid (backend defaults it to related)', async () => {
      linkMemories.mockResolvedValue({ success: true, sourceId, targetId, linkType: 'related', linkId: 'id-2' });

      const response = await request(app).post('/api/memory/link').send({ sourceId, targetId });

      expect(response.status).toBe(200);
      expect(linkMemories).toHaveBeenCalledWith(sourceId, targetId, { linkType: undefined, note: undefined, createdBy: undefined });
    });

    it('rejects an unknown link type and a directed self-link with 400', async () => {
      const unknown = await request(app).post('/api/memory/link').send({ sourceId, targetId, linkType: 'befriends' });
      const self = await request(app).post('/api/memory/link').send({ sourceId, targetId: sourceId, linkType: 'supersedes' });

      expect(unknown.status).toBe(400);
      expect(self.status).toBe(400);
      expect(linkMemories).not.toHaveBeenCalled();
    });
  });
});

describe('Memory version API', () => {
  it('validates version reads and propagates stale-write conflicts without embedding work', async () => {
    const backend = await import('../services/memoryBackend.js');
    const embeddings = await import('../services/memoryEmbeddings.js');
    const { errorMiddleware, ServerError } = await import('../lib/errorHandler.js');
    const app = express();
    app.use(express.json());
    app.use('/api/memory', memoryRoutes);
    app.use(errorMiddleware);
    backend.getMemoryVersion.mockResolvedValue({ id: 'mem-1', version: 1, content: 'Original' });
    expect((await request(app).get('/api/memory/mem-1?version=1')).body.content).toBe('Original');
    expect((await request(app).get('/api/memory/mem-1?version=-1')).status).toBe(400);
    backend.getMemoryVersions.mockResolvedValue([{ version: 1 }]);
    expect((await request(app).get('/api/memory/mem-1/versions?limit=1')).body.versions).toEqual([{ version: 1 }]);
    backend.updateMemory.mockRejectedValue(new ServerError('Stale memory', { status: 409 }));
    embeddings.generateMemoryEmbedding.mockClear();
    const response = await request(app).put('/api/memory/mem-1').send({ content: 'Overwrite', expectedVersion: 1 });
    expect(response.status).toBe(409);
    expect(embeddings.generateMemoryEmbedding).not.toHaveBeenCalled();
  });
});

describe('Memory reject API', () => {
  it('treats rejecting an already-deleted memory as success', async () => {
    const memoryService = await import('../services/memoryBackend.js');
    const app = express();
    app.use(express.json());
    app.use('/api/memory', memoryRoutes);
    memoryService.rejectMemory.mockResolvedValue({ success: false, error: 'Memory not found' });
    const response = await request(app).post('/api/memory/gone-1/reject').send({});
    expect(response.status).toBe(200);
    expect(response.body).toMatchObject({ success: true, alreadyResolved: true });
  });
});