Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

9.9 KB
Raw Blame
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { AgentMemory, createAgentMemory, ThreeWsError, MemoryError, PaymentRequiredError } from '../src/index.js';

// A scripted fetch double: each call shifts the next queued response and records
// the request. No network, no real endpoints — we assert on request shaping and
// response parsing, which is all the SDK is responsible for.
function stubFetch(responses) {
	const calls = [];
	const queue = [...responses];
	const fetch = async (url, init) => {
		calls.push({ url: new URL(url), init });
		const next = queue.shift();
		if (!next) throw new Error('stubFetch: no more queued responses');
		const { status = 200, body = {}, headers = {} } = next;
		return {
			ok: status >= 200 && status < 300,
			status,
			headers: { get: (k) => headers[k.toLowerCase()] ?? null },
			text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
		};
	};
	return { fetch, calls };
}

const AGENT = 'agent_THREE_1';
// A decorated memory as the store's decorateMemory() emits it (camelCase, with a
// snake_case agent_id, score/match only on recall hits).
function storedMemory(extra = {}) {
	return {
		id: 'm1',
		agent_id: AGENT,
		type: 'project',
		content: 'User prefers Solana over EVM chains',
		tags: ['preference'],
		context: {},
		salience: 0.5,
		tier: 'recall',
		pinned: false,
		embedder: 'nvidia/nv-embedqa-e5-v5@1024',
		hasEmbedding: true,
		accessCount: 0,
		isPublic: false,
		tokens: 9,
		createdAt: 1700000000000,
		updatedAt: 1700000000000,
		lastAccessedAt: null,
		expiresAt: null,
		...extra,
	};
}

test('remember() posts { agentId, entry } and shapes the stored memory', async () => {
	const { fetch, calls } = stubFetch([{ status: 201, body: { entry: storedMemory() } }]);
	const memory = new AgentMemory({ agentId: AGENT, token: 'tok', fetch });

	const mem = await memory.remember('User prefers Solana over EVM chains', { tags: ['preference'] });

	assert.equal(calls[0].url.pathname, '/api/agent-memory');
	assert.equal(calls[0].init.method, 'POST');
	assert.equal(calls[0].init.headers.authorization, 'Bearer tok');
	const sent = JSON.parse(calls[0].init.body);
	assert.equal(sent.agentId, AGENT);
	assert.equal(sent.entry.content, 'User prefers Solana over EVM chains');
	assert.deepEqual(sent.entry.tags, ['preference']);
	assert.ok(!('pinned' in sent.entry), 'unset pinned is pruned from the entry');
	assert.equal(mem.id, 'm1');
	assert.equal(mem.agentId, AGENT, 'snake_case agent_id is normalized to agentId');
	assert.equal(mem.tier, 'recall');
	assert.ok(mem.raw, 'raw escape hatch present');
});

test('remember() forces tier=working when pinned', async () => {
	const { fetch, calls } = stubFetch([{ status: 201, body: { entry: storedMemory({ pinned: true, tier: 'working' }) } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	await memory.remember('Never risk more than 2% per trade', { tags: ['strategy'], pinned: true });
	const sent = JSON.parse(calls[0].init.body);
	assert.equal(sent.entry.pinned, true);
});

test('recall() posts to /api/memory/search and maps results to camelCase with score/match', async () => {
	const { fetch, calls } = stubFetch([{
		body: { results: [storedMemory({ score: 0.8312, match: 'semantic' })], provider: true, scored: 1 },
	}]);
	const memory = new AgentMemory({ agentId: AGENT, fetch });

	const hits = await memory.recall('which blockchain does the user like?', { topK: 5 });

	assert.equal(calls[0].url.pathname, '/api/memory/search');
	assert.equal(calls[0].init.method, 'POST');
	const sent = JSON.parse(calls[0].init.body);
	assert.equal(sent.agentId, AGENT);
	assert.equal(sent.query, 'which blockchain does the user like?');
	assert.equal(sent.topK, 5);
	assert.equal(hits[0].content, 'User prefers Solana over EVM chains');
	assert.equal(hits[0].score, 0.8312);
	assert.equal(hits[0].match, 'semantic');
});

test('list() puts agentId + filters on the query string', async () => {
	const { fetch, calls } = stubFetch([{ body: { entries: [storedMemory()] } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const out = await memory.list({ type: 'project', limit: 50, since: 1700000000000 });
	assert.equal(calls[0].url.pathname, '/api/agent-memory');
	assert.equal(calls[0].url.searchParams.get('agentId'), AGENT);
	assert.equal(calls[0].url.searchParams.get('type'), 'project');
	assert.equal(calls[0].url.searchParams.get('limit'), '50');
	assert.equal(out.length, 1);
});

test('graph() shapes nodes + edges; entities() ranks by mentions', async () => {
	const { fetch } = stubFetch([{
		body: {
			nodes: [
				{ id: 'e1', kind: 'strategy', label: 'Never risk more than 2%…', mentions: 1, salience: 0.5 },
				{ id: 'e2', kind: 'ticker', label: '$THREE', mentions: 3, salience: 0.6 },
			],
			edges: [{ source: 'e1', target: 'e2', weight: 2 }],
			stats: { entities: 2, edges: 1 },
		},
	}]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const g = await memory.graph();
	assert.equal(g.nodes.length, 2);
	assert.equal(g.edges[0].weight, 2);
	assert.equal(g.stats.entities, 2);

	const { fetch: fetch2 } = stubFetch([{
		body: {
			nodes: [
				{ id: 'e1', kind: 'strategy', label: 'a', mentions: 1 },
				{ id: 'e2', kind: 'ticker', label: '$THREE', mentions: 3 },
			],
			edges: [],
			stats: { entities: 2, edges: 0 },
		},
	}]);
	const memory2 = createAgentMemory({ agentId: AGENT, fetch: fetch2 });
	const ents = await memory2.entities();
	assert.equal(ents[0].label, '$THREE', 'ranked by mention count desc');
});

test('memoriesFor() targets graph?entityId=', async () => {
	const { fetch, calls } = stubFetch([{ body: { memories: [storedMemory()] } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const mems = await memory.memoriesFor('e2');
	assert.equal(calls[0].url.pathname, '/api/memory/graph');
	assert.equal(calls[0].url.searchParams.get('entityId'), 'e2');
	assert.equal(mems[0].id, 'm1');
});

test('context() reads the working set with a token budget', async () => {
	const { fetch, calls } = stubFetch([{
		body: { entries: [storedMemory({ pinned: true, tier: 'working' })], tokens: 41, budget: 2000, overBudget: false, counts: { total: 1, working: 1, recall: 0, archival: 0, embedded: 1 } },
	}]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const ctx = await memory.context();
	assert.equal(calls[0].url.pathname, '/api/memory/context');
	assert.equal(ctx.tokens, 41);
	assert.equal(ctx.budget, 2000);
	assert.equal(ctx.overBudget, false);
	assert.equal(ctx.entries[0].pinned, true);
});

test('curation: pin/retier/setSalience hit /api/memory/curate with the right op', async () => {
	const { fetch, calls } = stubFetch([
		{ body: { entry: storedMemory({ pinned: true, tier: 'working' }) } },
		{ body: { entry: storedMemory({ tier: 'archival' }) } },
		{ body: { entry: storedMemory({ salience: 0.9 }) } },
	]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });

	await memory.pin('m1');
	await memory.retier('m1', 'archival');
	await memory.setSalience('m1', 0.9);

	assert.equal(calls[0].url.pathname, '/api/memory/curate');
	assert.equal(JSON.parse(calls[0].init.body).op, 'pin');
	assert.equal(JSON.parse(calls[1].init.body).op, 'tier');
	assert.equal(JSON.parse(calls[1].init.body).tier, 'archival');
	const s = JSON.parse(calls[2].init.body);
	assert.equal(s.op, 'salience');
	assert.equal(s.salience, 0.9);
});

test('forget() returns { ok, id } from the curate forget op', async () => {
	const { fetch, calls } = stubFetch([{ body: { ok: true, forgot: 'm1' } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const res = await memory.forget('m1');
	assert.equal(JSON.parse(calls[0].init.body).op, 'forget');
	assert.deepEqual(res, { ok: true, id: 'm1' });
});

test('merge() requires >= 2 ids and returns the survivor + count', async () => {
	const { fetch, calls } = stubFetch([{ body: { entry: storedMemory(), merged: 1 } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	const res = await memory.merge(['m1', 'm2']);
	assert.equal(JSON.parse(calls[0].init.body).op, 'merge');
	assert.deepEqual(JSON.parse(calls[0].init.body).memoryIds, ['m1', 'm2']);
	assert.equal(res.merged, 1);
	assert.equal(res.entry.id, 'm1');
});

test('input validation rejects before any network call', async () => {
	const { fetch, calls } = stubFetch([]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	await assert.rejects(() => memory.remember(''), /needs `content`/);
	await assert.rejects(() => memory.remember('x', { tier: 'cold' }), /Invalid tier/);
	await assert.rejects(() => memory.remember('x', { salience: 2 }), /0\.\.1/);
	await assert.rejects(() => memory.recall('   '), /non-empty query/);
	await assert.rejects(() => memory.retier('m1', 'cold'), /Invalid tier/);
	await assert.rejects(() => memory.setSalience('m1', -1), /0\.\.1/);
	await assert.rejects(() => memory.merge(['only-one']), /at least 2/);
	assert.equal(calls.length, 0);
	// A missing agentId is rejected at construction.
	assert.throws(() => createAgentMemory({ fetch }), /agentId/);
});

test('a 401 write surfaces as a typed MemoryError (=== ThreeWsError) with code', async () => {
	const { fetch } = stubFetch([{ status: 401, body: { error: 'unauthorized', message: 'sign in required' } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	await assert.rejects(() => memory.remember('x'), (e) => {
		assert.ok(e instanceof ThreeWsError);
		assert.ok(e instanceof MemoryError);
		assert.equal(e.code, 'unauthorized');
		assert.equal(e.status, 401);
		return true;
	});
});

test('a 402 surfaces as PaymentRequiredError carrying the x402 challenge', async () => {
	const accepts = [{ scheme: 'exact', asset: 'USDC', network: 'eip155:8453', maxAmountRequired: '150000' }];
	const { fetch } = stubFetch([{ status: 402, body: { error: 'payment_required', message: 'pay', accepts } }]);
	const memory = createAgentMemory({ agentId: AGENT, fetch });
	await assert.rejects(() => memory.recall('q'), (e) => {
		assert.ok(e instanceof PaymentRequiredError);
		assert.deepEqual(e.accepts, accepts);
		return true;
	});
});