Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import { describe, expect, it, vi } from "vitest";
import type { OpenVikingClient } from "../../client.js";
import { memoryOpenVikingConfigSchema } from "../../config.js";
import { createMemoryOpenVikingContextEngine } from "../../context-engine.js";
import { RuntimeQueryConfigStore } from "../../query-config.js";
import { RecallTraceMemoryStore } from "../../recall-trace.js";
const cfg = memoryOpenVikingConfigSchema.parse({
contextManagementMode: "openviking",
mode: "remote",
baseUrl: "http://127.0.0.1:1933",
autoCapture: false,
autoRecall: false,
});
function roughEstimate(messages: unknown[]): number {
return Math.ceil(JSON.stringify(messages).length / 4);
}
function systemPromptTokens(text?: string): number {
return text ? Math.ceil(text.length / 4) : 0;
}
function makeLogger() {
return {
info: vi.fn(),
warn: vi.fn(),
error: vi.fn(),
};
}
function makeStats() {
return {
totalArchives: 0,
includedArchives: 0,
droppedArchives: 0,
failedArchives: 0,
activeTokens: 0,
archiveTokens: 0,
};
}
function makeEngine(
contextResult: unknown,
opts?: {
cfgOverrides?: Record<string, unknown>;
traceRecorder?: RecallTraceMemoryStore;
queryConfigStore?: RuntimeQueryConfigStore;
},
) {
const logger = makeLogger();
const client = {
healthCheck: vi.fn().mockResolvedValue(undefined),
getSessionContext: vi.fn().mockResolvedValue(contextResult),
searchContext: vi.fn().mockResolvedValue({ entries: [], rendered: "", stats: {} }),
find: vi.fn().mockResolvedValue({ memories: [], resources: [], total: 0 }),
read: vi.fn().mockResolvedValue(""),
} as unknown as OpenVikingClient;
const getClient = vi.fn().mockResolvedValue(client);
const resolveAgentId = vi.fn((sessionId: string) => `agent:${sessionId}`);
const localCfg = opts?.cfgOverrides
? memoryOpenVikingConfigSchema.parse({
...cfg,
...opts.cfgOverrides,
})
: cfg;
const engine = createMemoryOpenVikingContextEngine({
id: "openviking",
name: "Context Engine (OpenViking)",
version: "test",
cfg: localCfg,
logger,
getClient,
resolveAgentId,
traceRecorder: opts?.traceRecorder,
queryConfigStore: opts?.queryConfigStore,
});
return {
engine,
client: client as unknown as {
getSessionContext: ReturnType<typeof vi.fn>;
healthCheck: ReturnType<typeof vi.fn>;
searchContext: ReturnType<typeof vi.fn>;
find: ReturnType<typeof vi.fn>;
read: ReturnType<typeof vi.fn>;
},
getClient,
logger,
resolveAgentId,
};
}
describe("context-engine assemble()", () => {
describe("recall from the separately supplied prompt", () => {
const prompt = "what backend language should we use?";
const memory = "User prefers Rust for backend tasks.";
function mockRecall(client: ReturnType<typeof makeEngine>["client"]) {
client.searchContext.mockResolvedValue({
entries: [{ uri: "viking://user/default/memories/rust-pref", category: "preferences", text: memory, score: 0.93 }],
rendered: `<memory>${memory}</memory>`,
stats: { candidates: 1, used_tokens: 18 },
});
}
it.each([false, true])("recalls on a fresh session (missing session: %s) without manufacturing a user turn", async (missing) => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
if (missing) client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
mockRecall(client);
const messages: [] = [];
const result = await engine.assemble({ sessionId: "new-session", messages, prompt, availableTools: new Set() });
expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.objectContaining({ sessionId: "new-session" }));
expect(result.messages).toBe(messages);
expect(result.systemPromptAddition).toContain(memory);
expect(result.systemPromptAddition).not.toContain(prompt);
expect(result.estimatedTokens).toBeGreaterThan(systemPromptTokens(result.systemPromptAddition));
});
it("still recalls under peer_role=sender when the host supplies no sender", async () => {
const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, peer_role: "sender" } });
mockRecall(client);
const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.objectContaining({ actorPeerId: undefined }));
expect(result.systemPromptAddition).toContain(memory);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("no sender identity"));
logger.warn.mockClear();
await engine.assemble({ sessionId: "session", messages: [], prompt, runtimeContext: { senderId: "telegram:12345" } });
expect(client.searchContext).toHaveBeenLastCalledWith(prompt, expect.objectContaining({ actorPeerId: "telegram_12345" }));
expect(logger.warn).not.toHaveBeenCalled();
});
it("recalls another detail from the same memory on a follow-up turn", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
const savedMemory = "Use Rust; deploy in eu-west.";
let messageCount = 2;
let lastServedAt: number | undefined;
client.searchContext.mockImplementation(async (_query, options) => {
const cooled = lastServedAt !== undefined && messageCount - lastServedAt < (options.dedupTurns ?? 0);
if (cooled) return { entries: [], rendered: "", stats: {} };
lastServedAt = messageCount;
return {
entries: [{ uri: "viking://user/default/memories/development", category: "preferences", text: savedMemory, score: 0.95 }],
rendered: `<memory>${savedMemory}</memory>`, stats: {},
};
});
const common = { sessionId: "existing-session", availableTools: new Set<string>() };
const messages = [{ role: "user", content: "Hello" }, { role: "assistant", content: "Hello" }];
const first = await engine.assemble({ ...common, messages, prompt: "What language should I use?" });
expect(first.systemPromptAddition).toContain(savedMemory);
const followupMessages = [...messages,
{ role: "user", content: "What language should I use?" },
{ role: "assistant", content: "Rust." },
];
messageCount = followupMessages.length;
const second = await engine.assemble({ ...common, messages: followupMessages, prompt: "What region should I deploy in?" });
expect(second.systemPromptAddition).toContain("eu-west");
expect(second.messages).toBe(followupMessages);
expect(JSON.stringify(second.messages)).not.toContain("eu-west");
expect(client.searchContext).toHaveBeenLastCalledWith("What region should I deploy in?", expect.objectContaining({ dedupTurns: 0 }));
});
it("keeps archive guidance and recalls the current prompt rather than the history tail", async () => {
const { engine, client } = makeEngine({
latest_archive_overview: "Previously discussed repository setup.",
pre_archive_abstracts: [], messages: [], estimatedTokens: 10, stats: makeStats(),
}, { cfgOverrides: { autoRecall: true } });
mockRecall(client);
const messages = [{ role: "user", content: "an unrelated old question" }];
const result = await engine.assemble({ sessionId: "archived-session", messages, prompt });
expect(client.searchContext).toHaveBeenCalledWith(prompt, expect.anything());
expect(result.systemPromptAddition).toContain("Session Context Guide");
expect(result.systemPromptAddition).toContain(memory);
expect(JSON.stringify(result.messages)).not.toContain(memory);
expect(messages).toEqual([{ role: "user", content: "an unrelated old question" }]);
});
it.each([
{ autoRecall: false, prompt, bypassSessionPatterns: [] },
{ autoRecall: true, prompt: "", bypassSessionPatterns: [] },
{ autoRecall: true, prompt: "hi", bypassSessionPatterns: [] },
{ autoRecall: true, prompt, bypassSessionPatterns: ["agent:*:cron:**"] },
])("respects disabled, empty and bypassed recall: %j", async ({ prompt: currentPrompt, ...cfgOverrides }) => {
const { engine, client } = makeEngine(undefined, { cfgOverrides });
const result = await engine.assemble({ sessionId: "session", sessionKey: "agent:main:cron:task", messages: [], prompt: currentPrompt });
expect(client.searchContext).not.toHaveBeenCalled();
expect(result.systemPromptAddition).toBeUndefined();
});
it.each(["no hits", "search failure", "budget exhausted"])("preserves history on %s", async (scenario) => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
if (scenario === "search failure") client.searchContext.mockRejectedValue(new Error("unavailable"));
if (scenario === "budget exhausted") mockRecall(client);
const messages = [{ role: "assistant", content: "previous answer" }];
const result = await engine.assemble({ sessionId: "session", messages, prompt, tokenBudget: scenario === "budget exhausted" ? 1 : 128_000 });
expect(result.messages).toBe(messages);
expect(result.systemPromptAddition).toBeUndefined();
});
});
describe("user profile injection", () => {
const prompt = "what are my project alias and theme color?";
const userProfileUri = "viking://~/memories/profile.md";
const profile = "# User\n- Project alias: Basalt-x\n- Preferred theme color: marigold";
const memory = "User prefers Rust for backend tasks.";
function mockProfile(client: ReturnType<typeof makeEngine>["client"], profiles: Record<string, string> = { [userProfileUri]: profile }) {
client.read.mockImplementation(async (uri: string) => {
if (uri in profiles) return profiles[uri];
throw new Error("[NOT_FOUND] File not found");
});
}
function mockRecall(client: ReturnType<typeof makeEngine>["client"], text = memory) {
client.searchContext.mockResolvedValue({
entries: [{ uri: "viking://user/default/memories/preferences/rust", category: "preferences", text, score: 0.93 }],
rendered: `<memory>${text}</memory>`,
stats: {},
});
}
it.each([false, true])("injects profile.md when recall finds nothing (missing session: %s)", async (missing) => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
if (missing) client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
mockProfile(client);
const messages: [] = [];
const result = await engine.assemble({ sessionId: "new-session", messages, prompt });
expect(client.read).toHaveBeenCalledWith(userProfileUri, undefined, 3000);
expect(result.messages).toBe(messages);
expect(result.systemPromptAddition).toContain(`<user-profile uri="${userProfileUri}">`);
expect(result.systemPromptAddition).toContain("Basalt-x");
expect(result.estimatedTokens).toBeGreaterThanOrEqual(systemPromptTokens(result.systemPromptAddition));
});
it("places the profile between the archive guide and recalled memories on every main turn", async () => {
const { engine, client } = makeEngine({
latest_archive_overview: "Previously discussed repository setup.",
pre_archive_abstracts: [], messages: [], estimatedTokens: 10, stats: makeStats(),
}, { cfgOverrides: { autoRecall: true } });
mockProfile(client);
mockRecall(client);
for (const turnPrompt of [prompt, "and which backend language?"]) {
const result = await engine.assemble({ sessionId: "archived-session", messages: [], prompt: turnPrompt });
const addition = result.systemPromptAddition ?? "";
const guideAt = addition.indexOf("Session Context Guide");
const profileAt = addition.indexOf("<user-profile");
const recallAt = addition.indexOf(memory);
expect(guideAt).toBeGreaterThanOrEqual(0);
expect(profileAt).toBeGreaterThan(guideAt);
expect(recallAt).toBeGreaterThan(profileAt);
}
});
it("injects the profile for prompts too short to recall", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client);
const result = await engine.assemble({ sessionId: "session", messages: [], prompt: "hi" });
expect(client.searchContext).not.toHaveBeenCalled();
expect(result.systemPromptAddition).toContain("Basalt-x");
});
it("keeps recall when the profile is missing, and the profile when recall fails", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client, {});
mockRecall(client);
const recallOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(recallOnly.systemPromptAddition).toContain(memory);
expect(recallOnly.systemPromptAddition).not.toContain("<user-profile");
mockProfile(client);
client.searchContext.mockRejectedValue(new Error("unavailable"));
const profileOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(profileOnly.systemPromptAddition).toContain("Basalt-x");
expect(profileOnly.systemPromptAddition).not.toContain(memory);
});
it("reads the actor peer's profile too under peer_role=sender", async () => {
const peerProfileUri = "viking://~/peers/telegram_12345/memories/profile.md";
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, peer_role: "sender" } });
mockProfile(client, { [userProfileUri]: profile, [peerProfileUri]: "# Peer\n- Timezone: UTC+8" });
const result = await engine.assemble({
sessionId: "session", messages: [], prompt, runtimeContext: { senderId: "telegram:12345" },
});
expect(client.read).toHaveBeenCalledWith(userProfileUri, "telegram_12345", 3000);
expect(client.read).toHaveBeenCalledWith(peerProfileUri, "telegram_12345", 3000);
expect(result.systemPromptAddition).toContain("Basalt-x");
expect(result.systemPromptAddition).toContain(`<user-profile uri="${peerProfileUri}">`);
expect(result.systemPromptAddition).toContain("Timezone: UTC+8");
});
it("bounds the profile read by the auto-recall timeout", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true, autoRecallTimeoutMs: 1000 } });
mockProfile(client);
await engine.assemble({ sessionId: "session", messages: [], prompt: "hi" });
expect(client.read).toHaveBeenCalledWith(userProfileUri, undefined, 1000);
});
it("warns when the profile read fails for a reason other than a missing file", async () => {
const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockRecall(client);
client.read.mockRejectedValue(new Error("OpenViking request failed [PERMISSION_DENIED]: forbidden"));
const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(result.systemPromptAddition).toContain(memory);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining(`profile read failed (uri=${userProfileUri})`));
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("PERMISSION_DENIED"));
logger.warn.mockClear();
mockProfile(client, {});
await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining("profile read failed"));
});
it("caps a long profile", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client, { [userProfileUri]: `${"x".repeat(9000)}TAIL` });
const result = await engine.assemble({ sessionId: "session", messages: [], prompt });
expect(result.systemPromptAddition).toContain("[profile truncated]");
expect(result.systemPromptAddition).not.toContain("TAIL");
});
it("drops recall before the profile when the budget is tight", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client);
const profileOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
mockRecall(client, "long recalled memory ".repeat(200));
const tight = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: profileOnly.estimatedTokens });
expect(tight.systemPromptAddition).toBe(profileOnly.systemPromptAddition);
const tighter = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: profileOnly.estimatedTokens - 1 });
expect(tighter.systemPromptAddition).toBeUndefined();
});
it("keeps recall when the profile alone does not fit the budget", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client, {});
mockRecall(client);
const recallOnly = await engine.assemble({ sessionId: "session", messages: [], prompt });
mockProfile(client, { [userProfileUri]: "画像".repeat(3950) });
const result = await engine.assemble({ sessionId: "session", messages: [], prompt, tokenBudget: recallOnly.estimatedTokens });
expect(result.systemPromptAddition).toBe(recallOnly.systemPromptAddition);
expect(result.systemPromptAddition).not.toContain("<user-profile");
});
it.each([
{ name: "autoRecall off", cfgOverrides: { autoRecall: false }, sessionKey: undefined },
{ name: "bypassed session", cfgOverrides: { autoRecall: true, bypassSessionPatterns: ["agent:*:cron:**"] }, sessionKey: "agent:main:cron:task" },
])("does not read the profile when $name", async ({ cfgOverrides, sessionKey }) => {
const { engine, client } = makeEngine(undefined, { cfgOverrides });
mockProfile(client);
const result = await engine.assemble({ sessionId: "session", sessionKey, messages: [], prompt });
expect(client.read).not.toHaveBeenCalled();
expect(result.systemPromptAddition).toBeUndefined();
});
it("does not inject the profile during transformContext", async () => {
const { engine, client } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
mockProfile(client);
const result = await engine.assemble({ sessionId: "session", messages: [{ role: "user", content: prompt }] });
expect(client.read.mock.calls.some(([uri]) => uri === userProfileUri)).toBe(false);
expect(JSON.stringify(result)).not.toContain("Basalt-x");
});
it("logs a missing OV session as skipped history, not a skipped assemble", async () => {
const { engine, client, logger } = makeEngine(undefined, { cfgOverrides: { autoRecall: true } });
client.getSessionContext.mockRejectedValue(new Error("[NOT_FOUND] Session not found"));
await engine.assemble({ sessionId: "new-session", messages: [], prompt });
const logged = logger.info.mock.calls.map(([line]) => String(line));
expect(logged.some((line) => line.includes("session history not assembled because OV session does not exist"))).toBe(true);
expect(logged.some((line) => line.includes("assemble skipped"))).toBe(false);
});
});
it("prepends auto-recall to the latest user message during transformContext", async () => {
const { engine, client } = makeEngine(
{
latest_archive_overview: "This OV context must not be rebuilt during transformContext.",
pre_archive_abstracts: [],
messages: [
{
id: "stored-current-user",
role: "user",
created_at: "2026-04-30T00:00:00Z",
parts: [{ type: "text", text: "stale stored prompt" }],
},
],
estimatedTokens: 12,
stats: makeStats(),
},
{
cfgOverrides: {
autoRecall: true,
recallPreferAbstract: true,
},
},
);
client.searchContext.mockResolvedValueOnce({
entries: [{
uri: "viking://user/default/memories/rust-pref",
category: "preferences",
text: "User prefers Rust for backend tasks.",
score: 0.93,
}],
rendered: '<memory uri="viking://user/default/memories/rust-pref">User prefers Rust for backend tasks.</memory>',
stats: { candidates: 1, used_tokens: 18 },
});
const sourceMessages = [
{ role: "user", content: "[Session History Summary]\nOlder archive summary." },
{ role: "assistant", content: [{ type: "text", text: "Previous answer." }] },
{ role: "user", content: "what backend language should we use?" },
];
const result = await engine.assemble({
sessionId: "session-transform",
messages: sourceMessages,
});
expect(client.getSessionContext).not.toHaveBeenCalled();
expect(result.messages).toHaveLength(sourceMessages.length);
expect(result.messages[0]).toBe(sourceMessages[0]);
expect(result.messages[1]).toBe(sourceMessages[1]);
expect(result.messages[2]?.role).toBe("user");
expect(result.messages[2]?.content).toMatch(/^<relevant-memories>/);
expect(result.messages[2]?.content).toContain("Source: openviking-auto-recall");
expect(result.messages[2]?.content).toContain("User prefers Rust for backend tasks.");
expect(result.messages[2]?.content).toContain("what backend language should we use?");
expect(result.systemPromptAddition).toBeUndefined();
});
it("passes session metadata into auto-recall trace recording during transformContext", async () => {
const traces = new RecallTraceMemoryStore(10);
const { engine, client } = makeEngine(
{
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
},
{
traceRecorder: traces,
cfgOverrides: {
autoRecall: true,
recallPreferAbstract: true,
recallTargetTypes: ["user"],
},
},
);
client.searchContext.mockResolvedValueOnce({
entries: [{
uri: "viking://user/default/memories/typescript-pref",
category: "preferences",
text: "Use TypeScript for gateway plugins.",
score: 0.9,
}],
rendered: '<memory uri="viking://user/default/memories/typescript-pref">Use TypeScript for gateway plugins.</memory>',
stats: { candidates: 1, used_tokens: 16 },
});
await engine.assemble({
sessionId: "session-transform-trace",
messages: [{ role: "user", content: "which language should the gateway plugin use?" }],
});
const recorded = traces.query({ turn: "latest", sessionId: "session-transform-trace", limit: 10 }).entries[0]!;
expect(recorded.sessionId).toBe("session-transform-trace");
expect(recorded.ovSessionId).toBe("session-transform-trace");
expect(recorded.agentId).toBe("agent:session-transform-trace");
expect(recorded.trigger.query).toBe("which language should the gateway plugin use?");
expect(recorded.resourceTypes).toEqual(["user"]);
});
it("uses backward-compatible user and agent auto-recall by default during transformContext", async () => {
const traces = new RecallTraceMemoryStore(10);
const { engine, client } = makeEngine(
{
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
},
{
traceRecorder: traces,
cfgOverrides: {
autoRecall: true,
recallPreferAbstract: true,
},
},
);
client.searchContext.mockResolvedValue({
entries: [{
uri: "viking://user/memories/project-docs",
category: "memory",
text: "Memory docs for the gateway plugin.",
score: 0.9,
}],
rendered: '<memory uri="viking://user/memories/project-docs">Memory docs for the gateway plugin.</memory>',
stats: { candidates: 1, used_tokens: 14 },
});
await engine.assemble({
sessionId: "session-transform-resource-default",
messages: [{ role: "user", content: "where are the gateway plugin docs?" }],
});
expect(client.searchContext).toHaveBeenCalledTimes(1);
expect(client.searchContext.mock.calls[0]?.[1]).toMatchObject({
sessionId: "session-transform-resource-default",
contextType: "memory",
queryExpansion: "auto",
dedupTurns: 5,
});
const recorded = traces.query({ turn: "latest", sessionId: "session-transform-resource-default", limit: 10 }).entries[0]!;
expect(recorded.resourceTypes).toEqual(["user", "agent"]);
});
it("applies session effective query config to transformContext auto-recall", async () => {
const localCfg = memoryOpenVikingConfigSchema.parse({
...cfg,
autoRecall: true,
recallPreferAbstract: true,
});
const queryConfigStore = RuntimeQueryConfigStore.createInMemory(localCfg);
await queryConfigStore.set(
"session",
{ agentId: "agent:session-dynamic-query", sessionId: "session-dynamic-query" },
{
recallLimit: 1,
candidateLimit: 3,
scoreThreshold: 0.5,
resourceTypes: ["user"],
maxInjectedChars: 1000,
},
);
const { engine, client } = makeEngine(
{
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
},
{
cfgOverrides: {
autoRecall: true,
recallPreferAbstract: true,
},
queryConfigStore,
},
);
client.searchContext.mockResolvedValueOnce({
entries: [{
uri: "viking://user/default/memories/high",
category: "preferences",
text: "High-confidence dynamic query memory.",
score: 0.9,
}],
rendered: '<memory uri="viking://user/default/memories/high">High-confidence dynamic query memory.</memory>',
stats: { candidates: 1, used_tokens: 12 },
});
const result = await engine.assemble({
sessionId: "session-dynamic-query",
messages: [{ role: "user", content: "which dynamic query memory applies?" }],
});
expect(client.searchContext).toHaveBeenCalledTimes(1);
expect(client.searchContext.mock.calls[0]?.[1]).toMatchObject({
contextType: "memory",
limit: 1,
scoreThreshold: 0.5,
maxTokens: 250,
});
expect(String(result.messages[0]?.content)).toContain("High-confidence dynamic query memory.");
expect(String(result.messages[0]?.content)).not.toContain("Low-confidence memory should be filtered.");
});
it("passes through transformContext messages when the latest message is not user", async () => {
const { engine, getClient } = makeEngine(
{
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
},
{
cfgOverrides: {
autoRecall: true,
},
},
);
const sourceMessages = [
{ role: "user", content: "run the tool" },
{
role: "assistant",
content: [{ type: "toolCall", id: "tool_1", name: "bash", arguments: {} }],
},
];
const result = await engine.assemble({
sessionId: "session-tool-loop",
messages: sourceMessages,
});
expect(getClient).not.toHaveBeenCalled();
expect(result.messages).toBe(sourceMessages);
expect(result.estimatedTokens).toBe(0);
});
it("passes through transformContext latest user messages when auto-recall is disabled", async () => {
const { engine, getClient } = makeEngine({
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
});
const sourceMessages = [
{ role: "assistant", content: [{ type: "text", text: "Previous answer." }] },
{ role: "user", content: "what backend language should we use?" },
];
const result = await engine.assemble({
sessionId: "session-auto-recall-disabled",
messages: sourceMessages,
});
expect(getClient).not.toHaveBeenCalled();
expect(result.messages).toBe(sourceMessages);
expect(result.estimatedTokens).toBe(roughEstimate(sourceMessages));
});
it("treats prompt-less assemble with availableTools as main assemble", async () => {
const { engine, client, resolveAgentId } = makeEngine({
latest_archive_overview: "# Session Summary\nPreviously discussed repository setup.",
pre_archive_abstracts: [
{
archive_id: "archive_001",
abstract: "Previously discussed repository setup.",
},
],
messages: [
{
id: "msg_main_no_prompt",
role: "assistant",
created_at: "2026-03-24T00:00:00Z",
parts: [{ type: "text", text: "Stored answer from OpenViking." }],
},
],
estimatedTokens: 120,
stats: {
...makeStats(),
totalArchives: 1,
includedArchives: 1,
archiveTokens: 40,
activeTokens: 80,
},
});
const liveMessages = [{ role: "user", content: "fallback live message" }];
const result = await engine.assemble({
sessionId: "session-main-no-prompt",
messages: liveMessages,
tokenBudget: 4096,
availableTools: new Set(),
});
expect(client.getSessionContext).toHaveBeenCalledWith(
"session-main-no-prompt",
4096,
);
expect(client.searchContext).not.toHaveBeenCalled();
expect(result.messages[0]).toEqual({
role: "user",
content: "[Session History Summary]\n# Session Summary\nPreviously discussed repository setup.",
});
expect(result.messages[1]).toEqual({
role: "assistant",
content: [{ type: "text", text: "Stored answer from OpenViking." }],
});
expect(result.systemPromptAddition).toContain("Session Context Guide");
});
it("assembles summary archive and completed tool parts into agent messages", async () => {
const { engine, client, resolveAgentId } = makeEngine({
latest_archive_overview: "# Session Summary\nPreviously discussed repository setup.",
pre_archive_abstracts: [
{
archive_id: "archive_001",
abstract: "Previously discussed repository setup.",
},
],
messages: [
{
id: "msg_1",
role: "assistant",
created_at: "2026-03-24T00:00:00Z",
parts: [
{ type: "text", text: "I checked the latest context." },
{ type: "context", abstract: "User prefers concise answers." },
{
type: "tool",
tool_id: "tool_123",
tool_name: "read_file",
tool_input: { path: "src/app.ts" },
tool_output: "export const value = 1;",
tool_status: "completed",
},
],
},
],
estimatedTokens: 321,
stats: {
...makeStats(),
totalArchives: 1,
includedArchives: 1,
archiveTokens: 40,
activeTokens: 281,
},
});
const liveMessages = [{ role: "user", content: "fallback live message" }];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-1",
messages: liveMessages,
tokenBudget: 4096,
});
expect(client.getSessionContext).toHaveBeenCalledWith("session-1", 4096);
expect(result.estimatedTokens).toBe(
roughEstimate(result.messages) + systemPromptTokens(result.systemPromptAddition),
);
expect(result.systemPromptAddition).toContain("Session Context Guide");
expect(result.messages[0]).toEqual({
role: "user",
content: "[Session History Summary]\n# Session Summary\nPreviously discussed repository setup.",
});
expect(result.messages[1]).toEqual({
role: "assistant",
content: [
{ type: "text", text: "I checked the latest context." },
{ type: "text", text: "User prefers concise answers." },
{
type: "toolCall",
id: "tool_123",
name: "read_file",
arguments: { path: "src/app.ts" },
},
],
});
expect(result.messages[2]).toEqual({
role: "toolResult",
toolCallId: "tool_123",
toolName: "read_file",
content: [{ type: "text", text: "export const value = 1;" }],
isError: false,
});
});
it("passes through live messages when the session matches bypassSessionPatterns", async () => {
const { engine, client, getClient } = makeEngine(
{
latest_archive_overview: "unused",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 123,
stats: makeStats(),
},
{
cfgOverrides: {
bypassSessionPatterns: ["agent:*:cron:**"],
},
},
);
const liveMessages = [{ role: "user", content: "fallback live message" }];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "runtime-session",
sessionKey: "agent:main:cron:nightly:run:1",
messages: liveMessages,
tokenBudget: 4096,
});
expect(getClient).not.toHaveBeenCalled();
expect(client.getSessionContext).not.toHaveBeenCalled();
expect(result).toEqual({
messages: liveMessages,
estimatedTokens: roughEstimate(liveMessages),
});
});
it("emits a non-error toolResult for a running tool (not a synthetic error)", async () => {
const { engine } = makeEngine({
latest_archive_overview: "",
pre_archive_abstracts: [],
messages: [
{
id: "msg_2",
role: "assistant",
created_at: "2026-03-24T00:00:00Z",
parts: [
{
type: "tool",
tool_id: "tool_running",
tool_name: "bash",
tool_input: { command: "npm test" },
tool_output: "",
tool_status: "running",
},
],
},
],
estimatedTokens: 88,
stats: {
...makeStats(),
activeTokens: 88,
},
});
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-running",
messages: [],
});
expect(result.systemPromptAddition).toBeUndefined();
expect(result.messages).toHaveLength(2);
expect(result.messages[0]).toEqual({
role: "assistant",
content: [
{
type: "toolCall",
id: "tool_running",
name: "bash",
arguments: { command: "npm test" },
},
],
});
expect(result.messages[1]).toMatchObject({
role: "toolResult",
toolCallId: "tool_running",
toolName: "bash",
isError: false,
});
const text = (result.messages[1] as any).content?.[0]?.text ?? "";
expect(text).toContain("interrupted");
expect((result.messages[1] as { content: Array<{ text: string }> }).content[0]?.text).toContain(
"interrupted",
);
});
it("degrades tool parts without tool_id into assistant text blocks", async () => {
const { engine } = makeEngine({
latest_archive_overview: "",
pre_archive_abstracts: [],
messages: [
{
id: "msg_3",
role: "assistant",
created_at: "2026-03-24T00:00:00Z",
parts: [
{ type: "text", text: "Tool state snapshot:" },
{
type: "tool",
tool_id: "",
tool_name: "grep",
tool_input: { pattern: "TODO" },
tool_output: "src/app.ts:17 TODO refine this",
tool_status: "completed",
},
],
},
],
estimatedTokens: 71,
stats: {
...makeStats(),
activeTokens: 71,
},
});
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-missing-id",
messages: [],
});
expect(result.messages).toEqual([
{
role: "assistant",
content: [
{ type: "text", text: "Tool state snapshot:" },
{
type: "text",
text: "[grep] (completed)\nInput: {\"pattern\":\"TODO\"}\nOutput: src/app.ts:17 TODO refine this",
},
],
},
]);
});
it("falls back to live messages when assembled active messages look truncated", async () => {
const { engine } = makeEngine({
latest_archive_overview: "",
pre_archive_abstracts: [],
messages: [
{
id: "msg_4",
role: "user",
created_at: "2026-03-24T00:00:00Z",
parts: [{ type: "text", text: "Only one stored message" }],
},
],
estimatedTokens: 12,
stats: {
...makeStats(),
activeTokens: 12,
},
});
const liveMessages = [
{ role: "user", content: "message one" },
{ role: "assistant", content: [{ type: "text", text: "message two" }] },
];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-fallback",
messages: liveMessages,
tokenBudget: 1024,
});
expect(result).toEqual({
messages: liveMessages,
estimatedTokens: roughEstimate(liveMessages),
});
});
it("passes through when OV has no archives and no active messages (new user)", async () => {
const { engine } = makeEngine({
latest_archive_overview: "",
latest_archive_id: "",
pre_archive_abstracts: [],
messages: [],
estimatedTokens: 0,
stats: makeStats(),
});
const liveMessages = [
{ role: "user", content: "hello, first message" },
];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-new-user",
messages: liveMessages,
});
expect(result.messages).toBe(liveMessages);
expect(result.estimatedTokens).toBe(roughEstimate(liveMessages));
expect(result.systemPromptAddition).toBeUndefined();
});
it("still produces non-empty output when OV messages have empty parts (overview fills it)", async () => {
const { engine } = makeEngine({
latest_archive_overview: "Some overview of previous sessions",
latest_archive_id: "archive_001",
pre_archive_abstracts: [],
messages: [
{
id: "msg_empty",
role: "assistant",
created_at: "2026-03-29T00:00:00Z",
parts: [],
},
],
estimatedTokens: 10,
stats: {
...makeStats(),
totalArchives: 1,
includedArchives: 1,
},
});
const liveMessages = [
{ role: "user", content: "what was that thing?" },
];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-empty-parts",
messages: liveMessages,
});
// Even with empty parts, the overview and archive index still produce messages
// so sanitized.length > 0 and we get the assembled result (not fallback)
expect(result.messages.length).toBeGreaterThanOrEqual(2);
expect(result.messages[0]).toMatchObject({
role: "user",
content: expect.stringContaining("Session History Summary"),
});
expect(result.systemPromptAddition).toContain("Session Context Guide");
});
it("keeps assembled output within the requested token budget", async () => {
const longText = "A".repeat(2500);
const { engine } = makeEngine({
latest_archive_overview: "# Session Summary\nA short overview",
pre_archive_abstracts: [],
messages: [
{
id: "msg_long_1",
role: "user",
created_at: "2026-03-24T00:00:00Z",
parts: [{ type: "text", text: longText }],
},
{
id: "msg_long_2",
role: "assistant",
created_at: "2026-03-24T00:00:01Z",
parts: [{ type: "text", text: longText }],
},
],
estimatedTokens: 2000,
stats: {
...makeStats(),
totalArchives: 1,
includedArchives: 1,
activeTokens: 2000,
archiveTokens: 10,
},
});
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-budgeted",
messages: [],
tokenBudget: 1024,
});
expect(result.estimatedTokens).toBeLessThanOrEqual(1024);
expect(result.messages.length).toBeGreaterThan(0);
expect(result.systemPromptAddition).toContain("Session Context Guide");
});
it("falls back to original messages when getClient throws", async () => {
const logger = makeLogger();
const getClient = vi.fn().mockRejectedValue(new Error("OV connection refused"));
const resolveAgentId = vi.fn((_s: string) => "agent");
const engine = createMemoryOpenVikingContextEngine({
id: "openviking",
name: "Test",
version: "test",
cfg,
logger,
getClient,
resolveAgentId,
});
const liveMessages = [
{ role: "user", content: "hello" },
];
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-error",
messages: liveMessages,
});
expect(result.messages).toBe(liveMessages);
expect(result.estimatedTokens).toBe(roughEstimate(liveMessages));
expect(result.systemPromptAddition).toBeUndefined();
});
it("drops tool-only user messages instead of emitting empty content (issue #1485)", async () => {
const { engine } = makeEngine({
latest_archive_overview: "",
pre_archive_abstracts: [],
messages: [
{
id: "msg_tool_only_user",
role: "user",
created_at: "2026-04-17T00:00:00Z",
parts: [
{
type: "tool",
tool_id: "tool_abc",
tool_name: "bash",
tool_input: { command: "ls" },
tool_output: "file.txt",
tool_status: "completed",
},
],
},
],
estimatedTokens: 50,
stats: { ...makeStats(), activeTokens: 50 },
});
const result = await engine.assemble({
prompt: "current user prompt",
sessionId: "session-tool-only",
messages: [],
});
const emptyContentMsg = result.messages.find(
(m) => typeof m.content === "string" && m.content === "",
);
expect(emptyContentMsg).toBeUndefined();
});
});
describe("cloud recall digest injection", () => {
it.each([false, true])("honors server no_relevant=%s", async (noRelevant) => {
const { engine, client } = makeEngine({}, { cfgOverrides: { autoRecall: true, recallCompress: "server" } });
client.searchContext.mockResolvedValueOnce({
entries: [], rendered: "RAW SHOULD NOT APPEAR", digest: "Prefer Rust for backend tasks.",
stats: { rewrite: noRelevant ? "no_relevant" : "rewritten" },
});
const result = await engine.assemble({ sessionId: "cloud-digest", messages: [{ role: "user", content: "what backend language should we use?" }] });
expect(client.searchContext).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ recallCompress: "server" }));
expect(JSON.stringify(result.messages)).not.toContain("RAW SHOULD NOT APPEAR");
expect(JSON.stringify(result.messages).includes("Prefer Rust")).toBe(!noRelevant);
});
});
it("native mode preserves host history and recall without reading OV history", async () => {
const { engine, client } = makeEngine({ latest_archive_overview: "obsolete OV summary" }, { cfgOverrides: { contextManagementMode: "native", autoRecall: true } });
client.searchContext.mockResolvedValue({ entries: [], rendered: "Remember Rust.", stats: {} });
const messages = [{ role: "user", content: "earlier host constraint" }, { role: "assistant", content: "native summary" }];
const result = await engine.assemble({ sessionId: "native", messages, prompt: "next question" });
expect(result.messages).toBe(messages);
expect(result.systemPromptAddition).toContain("Remember Rust.");
expect(client.getSessionContext).not.toHaveBeenCalled();
expect(client.searchContext).toHaveBeenCalledOnce();
});
it("keeps native history when a completed archive has no summary", async () => {
const { engine, logger } = makeEngine({
latest_archive_overview: "", pre_archive_abstracts: [],
messages: [{ role: "assistant", parts: [{ type: "text", text: "retained tail" }] }],
stats: { ...makeStats(), totalArchives: 1 },
});
const messages = [{ role: "user", content: "earlier constraint" }];
const result = await engine.assemble({ sessionId: "no-wm", messages, prompt: "Continue" });
expect(result.messages).toBe(messages);
expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("no summary"));
});