Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat: agentmemory v0.3.0 — semantic search, memory evolution, profiles

Rohit Ghumarea6fabc77d22d
diff --git a/package.json b/package.json
index 1077696d..f146abe7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "agentmemory",
- "version": "0.2.0",
+ "version": "0.3.0",
"description": "Persistent memory for AI coding agents, powered by iii-engine's three primitives",
"type": "module",
"main": "dist/index.js",
@@ -35,7 +35,11 @@
"@anthropic-ai/claude-agent-sdk": "^0.2.56",
"@anthropic-ai/sdk": "^0.39.0",
"dotenv": "^16.4.7",
- "iii-sdk": "^0.3.0"
+ "iii-sdk": "^0.3.0",
+ "zod": "^3.23.0"
+ },
+ "optionalDependencies": {
+ "@xenova/transformers": "^2.17.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
diff --git a/src/config.ts b/src/config.ts
index 97d5bd0b..17439471 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -1,7 +1,12 @@
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";
-import type { AgentMemoryConfig, ProviderConfig } from "./types.js";
+import type {
+ AgentMemoryConfig,
+ ProviderConfig,
+ EmbeddingConfig,
+ FallbackConfig,
+} from "./types.js";
const DATA_DIR = join(homedir(), ".agentmemory");
const ENV_FILE = join(DATA_DIR, ".env");
@@ -60,8 +65,7 @@ function detectProvider(env: Record<string, string>): ProviderConfig {
}
export function loadConfig(): AgentMemoryConfig {
- const fileEnv = loadEnvFile();
- const env = { ...fileEnv, ...process.env } as Record<string, string>;
+ const env = getMergedEnv();
const provider = detectProvider(env);
@@ -80,7 +84,47 @@ export function loadConfig(): AgentMemoryConfig {
};
}
-export function getEnvVar(key: string): string | undefined {
+function getMergedEnv(
+ overrides?: Record<string, string>,
+): Record<string, string> {
const fileEnv = loadEnvFile();
- return process.env[key] || fileEnv[key];
+ return { ...fileEnv, ...process.env, ...overrides } as Record<string, string>;
+}
+
+export function getEnvVar(key: string): string | undefined {
+ return getMergedEnv()[key];
+}
+
+export function loadEmbeddingConfig(): EmbeddingConfig {
+ const env = getMergedEnv();
+ return {
+ provider: env["EMBEDDING_PROVIDER"] || undefined,
+ bm25Weight: parseFloat(env["BM25_WEIGHT"] || "0.4"),
+ vectorWeight: parseFloat(env["VECTOR_WEIGHT"] || "0.6"),
+ };
+}
+
+export function detectEmbeddingProvider(
+ env?: Record<string, string>,
+): string | null {
+ const merged = getMergedEnv(env);
+ const forced = merged["EMBEDDING_PROVIDER"];
+ if (forced) return forced;
+
+ if (merged["GEMINI_API_KEY"]) return "gemini";
+ if (merged["OPENAI_API_KEY"]) return "openai";
+ if (merged["VOYAGE_API_KEY"]) return "voyage";
+ if (merged["COHERE_API_KEY"]) return "cohere";
+ if (merged["OPENROUTER_API_KEY"]) return "openrouter";
+ return null;
+}
+
+export function loadFallbackConfig(): FallbackConfig {
+ const env = getMergedEnv();
+ const raw = env["FALLBACK_PROVIDERS"] || "";
+ const providers = raw
+ .split(",")
+ .map((p) => p.trim())
+ .filter(Boolean) as FallbackConfig["providers"];
+ return { providers };
}
diff --git a/src/eval/schemas.ts b/src/eval/schemas.ts
index 6ce820e0..cfd592ca 100644
--- a/src/eval/schemas.ts
+++ b/src/eval/schemas.ts
@@ -1,15 +1,35 @@
import { z } from "zod";
const HookTypeEnum = z.enum([
- "session_start", "prompt_submit", "pre_tool_use", "post_tool_use",
- "post_tool_failure", "pre_compact", "subagent_start", "subagent_stop",
- "notification", "task_completed", "stop", "session_end",
+ "session_start",
+ "prompt_submit",
+ "pre_tool_use",
+ "post_tool_use",
+ "post_tool_failure",
+ "pre_compact",
+ "subagent_start",
+ "subagent_stop",
+ "notification",
+ "task_completed",
+ "stop",
+ "session_end",
]);
const ObservationTypeEnum = z.enum([
- "file_read", "file_write", "file_edit", "command_run", "search",
- "web_fetch", "conversation", "error", "decision", "discovery",
- "subagent", "notification", "task", "other",
+ "file_read",
+ "file_write",
+ "file_edit",
+ "command_run",
+ "search",
+ "web_fetch",
+ "conversation",
+ "error",
+ "decision",
+ "discovery",
+ "subagent",
+ "notification",
+ "task",
+ "other",
]);
export const ObserveInputSchema = z.object({
@@ -53,7 +73,52 @@ export const ContextInputSchema = z.object({
export const RememberInputSchema = z.object({
content: z.string().min(1),
- type: z.enum(["pattern", "preference", "architecture", "bug", "workflow", "fact"]).optional(),
+ type: z
+ .enum(["pattern", "preference", "architecture", "bug", "workflow", "fact"])
+ .optional(),
concepts: z.array(z.string()).optional(),
files: z.array(z.string()).optional(),
});
+
+export const SmartSearchInputSchema = z.object({
+ query: z.string().optional(),
+ expandIds: z.array(z.string()).optional(),
+ limit: z.number().int().positive().optional(),
+});
+
+export const TimelineInputSchema = z.object({
+ anchor: z.string().min(1),
+ project: z.string().optional(),
+ before: z.number().int().nonnegative().optional(),
+ after: z.number().int().nonnegative().optional(),
+});
+
+export const ProfileInputSchema = z.object({
+ project: z.string().min(1),
+ refresh: z.boolean().optional(),
+});
+
+export const RelateInputSchema = z.object({
+ sourceId: z.string().min(1),
+ targetId: z.string().min(1),
+ type: z.enum(["supersedes", "extends", "derives", "contradicts", "related"]),
+});
+
+export const EvolveInputSchema = z.object({
+ memoryId: z.string().min(1),
+ newContent: z.string().min(1),
+ newTitle: z.string().optional(),
+});
+
+export const ExportImportInputSchema = z.object({
+ exportData: z.object({
+ version: z.literal("0.3.0"),
+ exportedAt: z.string(),
+ sessions: z.array(z.unknown()),
+ observations: z.record(z.string(), z.array(z.unknown())),
+ memories: z.array(z.unknown()),
+ summaries: z.array(z.unknown()),
+ profiles: z.array(z.unknown()).optional(),
+ }),
+ strategy: z.enum(["merge", "replace", "skip"]).optional(),
+});
diff --git a/src/functions/auto-forget.ts b/src/functions/auto-forget.ts
new file mode 100644
index 00000000..96259026
--- /dev/null
+++ b/src/functions/auto-forget.ts
@@ -0,0 +1,108 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, CompressedObservation, Session } from "../types.js";
+import { KV, jaccardSimilarity } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const CONTRADICTION_THRESHOLD = 0.9;
+
+interface AutoForgetResult {
+ ttlExpired: string[];
+ contradictions: Array<{
+ memoryA: string;
+ memoryB: string;
+ similarity: number;
+ }>;
+ lowValueObs: string[];
+ dryRun: boolean;
+}
+
+export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ {
+ id: "mem::auto-forget",
+ description:
+ "Auto-forget expired (TTL), contradictory, and low-value data",
+ },
+ async (data: { dryRun?: boolean }): Promise<AutoForgetResult> => {
+ const ctx = getContext();
+ const dryRun = data?.dryRun ?? false;
+ const now = Date.now();
+
+ const result: AutoForgetResult = {
+ ttlExpired: [],
+ contradictions: [],
+ lowValueObs: [],
+ dryRun,
+ };
+
+ const memories = await kv.list<Memory>(KV.memories);
+ for (const mem of memories) {
+ if (mem.forgetAfter) {
+ const expiry = new Date(mem.forgetAfter).getTime();
+ if (now > expiry) {
+ result.ttlExpired.push(mem.id);
+ if (!dryRun) {
+ await kv.delete(KV.memories, mem.id);
+ }
+ }
+ }
+ }
+
+ const latestMemories = memories.filter((m) => m.isLatest !== false);
+ for (let i = 0; i < latestMemories.length; i++) {
+ for (let j = i + 1; j < latestMemories.length; j++) {
+ const sim = jaccardSimilarity(
+ latestMemories[i].content.toLowerCase(),
+ latestMemories[j].content.toLowerCase(),
+ );
+ if (sim > CONTRADICTION_THRESHOLD) {
+ result.contradictions.push({
+ memoryA: latestMemories[i].id,
+ memoryB: latestMemories[j].id,
+ similarity: sim,
+ });
+
+ if (!dryRun) {
+ const older =
+ new Date(latestMemories[i].createdAt).getTime() <
+ new Date(latestMemories[j].createdAt).getTime()
+ ? latestMemories[i]
+ : latestMemories[j];
+ older.isLatest = false;
+ await kv.set(KV.memories, older.id, older);
+ }
+ }
+ }
+ }
+
+ const sessions = await kv.list<Session>(KV.sessions);
+ for (const session of sessions) {
+ const observations = await kv
+ .list<CompressedObservation>(KV.observations(session.id))
+ .catch(() => []);
+ for (const obs of observations) {
+ if (!obs.timestamp) continue;
+ const age = now - new Date(obs.timestamp).getTime();
+ if (age > 180 * MS_PER_DAY && (obs.importance ?? 5) <= 2) {
+ result.lowValueObs.push(obs.id);
+ if (!dryRun) {
+ await kv
+ .delete(KV.observations(session.id), obs.id)
+ .catch(() => {});
+ }
+ }
+ }
+ }
+
+ ctx.logger.info("Auto-forget complete", {
+ ttlExpired: result.ttlExpired.length,
+ contradictions: result.contradictions.length,
+ lowValueObs: result.lowValueObs.length,
+ dryRun,
+ });
+ return result;
+ },
+ );
+}
diff --git a/src/functions/consolidate.ts b/src/functions/consolidate.ts
index 9e433273..64ccc17f 100644
--- a/src/functions/consolidate.ts
+++ b/src/functions/consolidate.ts
@@ -56,6 +56,8 @@ function parseMemoryXml(
1,
Math.min(10, parseInt(getXmlTag(xml, "strength") || "5", 10) || 5),
),
+ version: 1,
+ isLatest: true,
};
}
@@ -134,19 +136,44 @@ export function registerConsolidateFunction(
const parsed = parseMemoryXml(response, sessionIds);
if (!parsed) continue;
- if (existingTitles.has(parsed.title.toLowerCase())) continue;
+ const existingMatch = existingMemories.find(
+ (m) => m.title.toLowerCase() === parsed.title.toLowerCase(),
+ );
const now = new Date().toISOString();
- const memory: Memory = {
- id: generateId("mem"),
- createdAt: now,
- updatedAt: now,
- ...parsed,
- };
-
- await kv.set(KV.memories, memory.id, memory);
- existingTitles.add(memory.title.toLowerCase());
- consolidated++;
+ if (existingMatch) {
+ existingMatch.isLatest = false;
+ await kv.set(KV.memories, existingMatch.id, existingMatch);
+
+ const evolved: Memory = {
+ id: generateId("mem"),
+ createdAt: now,
+ updatedAt: now,
+ ...parsed,
+ version: (existingMatch.version || 1) + 1,
+ parentId: existingMatch.id,
+ supersedes: [
+ existingMatch.id,
+ ...(existingMatch.supersedes || []),
+ ],
+ isLatest: true,
+ };
+ await kv.set(KV.memories, evolved.id, evolved);
+ existingTitles.add(evolved.title.toLowerCase());
+ consolidated++;
+ } else {
+ const memory: Memory = {
+ id: generateId("mem"),
+ createdAt: now,
+ updatedAt: now,
+ ...parsed,
+ version: 1,
+ isLatest: true,
+ };
+ await kv.set(KV.memories, memory.id, memory);
+ existingTitles.add(memory.title.toLowerCase());
+ consolidated++;
+ }
} catch (err) {
ctx.logger.warn("Consolidation failed for concept", {
concept,
diff --git a/src/functions/context.ts b/src/functions/context.ts
index ecc01222..91174623 100644
--- a/src/functions/context.ts
+++ b/src/functions/context.ts
@@ -5,6 +5,7 @@ import type {
CompressedObservation,
SessionSummary,
ContextBlock,
+ ProjectProfile,
} from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
@@ -36,6 +37,46 @@ export function registerContextFunction(
const budget = data.budget || tokenBudget;
const blocks: ContextBlock[] = [];
+ const profile = await kv
+ .get<ProjectProfile>(KV.profiles, data.project)
+ .catch(() => null);
+ if (profile) {
+ const profileParts = [];
+ if (profile.topConcepts.length > 0) {
+ profileParts.push(
+ `Concepts: ${profile.topConcepts
+ .slice(0, 8)
+ .map((c) => c.concept)
+ .join(", ")}`,
+ );
+ }
+ if (profile.topFiles.length > 0) {
+ profileParts.push(
+ `Key files: ${profile.topFiles
+ .slice(0, 5)
+ .map((f) => f.file)
+ .join(", ")}`,
+ );
+ }
+ if (profile.conventions.length > 0) {
+ profileParts.push(`Conventions: ${profile.conventions.join("; ")}`);
+ }
+ if (profile.commonErrors.length > 0) {
+ profileParts.push(
+ `Common errors: ${profile.commonErrors.slice(0, 3).join("; ")}`,
+ );
+ }
+ if (profileParts.length > 0) {
+ const profileContent = `## Project Profile\n${profileParts.join("\n")}`;
+ blocks.push({
+ type: "memory",
+ content: profileContent,
+ tokens: estimateTokens(profileContent),
+ recency: new Date(profile.updatedAt).getTime(),
+ });
+ }
+ }
+
const allSessions = await kv.list<Session>(KV.sessions);
const sessions = allSessions
.filter((s) => s.project === data.project && s.id !== data.sessionId)
diff --git a/src/functions/evict.ts b/src/functions/evict.ts
index 2744a247..4fa788a6 100644
--- a/src/functions/evict.ts
+++ b/src/functions/evict.ts
@@ -4,6 +4,7 @@ import type {
Session,
CompressedObservation,
SessionSummary,
+ Memory,
} from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
@@ -28,6 +29,8 @@ interface EvictionStats {
staleSessions: number;
lowImportanceObs: number;
capEvictions: number;
+ expiredMemories: number;
+ nonLatestMemories: number;
dryRun: boolean;
}
@@ -51,6 +54,8 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void {
staleSessions: 0,
lowImportanceObs: 0,
capEvictions: 0,
+ expiredMemories: 0,
+ nonLatestMemories: 0,
dryRun,
};
@@ -122,6 +127,29 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void {
}
}
+ const memories = await kv.list<Memory>(KV.memories).catch(() => []);
+ for (const mem of memories) {
+ if (mem.forgetAfter) {
+ const expiry = new Date(mem.forgetAfter).getTime();
+ if (now > expiry) {
+ stats.expiredMemories++;
+ if (!dryRun) {
+ await kv.delete(KV.memories, mem.id).catch(() => {});
+ }
+ }
+ }
+
+ if (mem.isLatest === false && mem.createdAt) {
+ const age = now - new Date(mem.createdAt).getTime();
+ if (age > cfg.lowImportanceMaxDays * MS_PER_DAY) {
+ stats.nonLatestMemories++;
+ if (!dryRun) {
+ await kv.delete(KV.memories, mem.id).catch(() => {});
+ }
+ }
+ }
+ }
+
ctx.logger.info("Eviction complete", { stats });
return stats;
},
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
new file mode 100644
index 00000000..62b5a07f
--- /dev/null
+++ b/src/functions/export-import.ts
@@ -0,0 +1,179 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ Session,
+ CompressedObservation,
+ Memory,
+ SessionSummary,
+ ProjectProfile,
+ ExportData,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ { id: "mem::export", description: "Export all memory data as JSON" },
+ async () => {
+ const ctx = getContext();
+
+ const sessions = await kv.list<Session>(KV.sessions);
+ const memories = await kv.list<Memory>(KV.memories);
+ const summaries = await kv.list<SessionSummary>(KV.summaries);
+
+ const observations: Record<string, CompressedObservation[]> = {};
+ for (const session of sessions) {
+ const obs = await kv
+ .list<CompressedObservation>(KV.observations(session.id))
+ .catch(() => []);
+ if (obs.length > 0) {
+ observations[session.id] = obs;
+ }
+ }
+
+ const profiles: ProjectProfile[] = [];
+ const uniqueProjects = [...new Set(sessions.map((s) => s.project))];
+ for (const project of uniqueProjects) {
+ const profile = await kv
+ .get<ProjectProfile>(KV.profiles, project)
+ .catch(() => null);
+ if (profile) profiles.push(profile);
+ }
+
+ const exportData: ExportData = {
+ version: "0.3.0",
+ exportedAt: new Date().toISOString(),
+ sessions,
+ observations,
+ memories,
+ summaries,
+ profiles: profiles.length > 0 ? profiles : undefined,
+ };
+
+ const totalObs = Object.values(observations).reduce(
+ (sum, arr) => sum + arr.length,
+ 0,
+ );
+ ctx.logger.info("Export complete", {
+ sessions: sessions.length,
+ observations: totalObs,
+ memories: memories.length,
+ summaries: summaries.length,
+ });
+
+ return exportData;
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::import",
+ description: "Import memory data from JSON export",
+ },
+ async (data: {
+ exportData: ExportData;
+ strategy?: "merge" | "replace" | "skip";
+ }) => {
+ const ctx = getContext();
+ const strategy = data.strategy || "merge";
+ const importData = data.exportData;
+
+ if (importData.version !== "0.3.0") {
+ return {
+ success: false,
+ error: `Unsupported export version: ${importData.version}`,
+ };
+ }
+
+ const stats = {
+ sessions: 0,
+ observations: 0,
+ memories: 0,
+ summaries: 0,
+ skipped: 0,
+ };
+
+ if (strategy === "replace") {
+ const existing = await kv.list<Session>(KV.sessions);
+ for (const session of existing) {
+ await kv.delete(KV.sessions, session.id);
+ const obs = await kv
+ .list<CompressedObservation>(KV.observations(session.id))
+ .catch(() => []);
+ for (const o of obs) {
+ await kv.delete(KV.observations(session.id), o.id);
+ }
+ }
+ const existingMem = await kv.list<Memory>(KV.memories);
+ for (const m of existingMem) {
+ await kv.delete(KV.memories, m.id);
+ }
+ const existingSummaries = await kv.list<SessionSummary>(KV.summaries);
+ for (const s of existingSummaries) {
+ await kv.delete(KV.summaries, s.sessionId);
+ }
+ }
+
+ for (const session of importData.sessions) {
+ if (strategy === "skip") {
+ const existing = await kv
+ .get<Session>(KV.sessions, session.id)
+ .catch(() => null);
+ if (existing) {
+ stats.skipped++;
+ continue;
+ }
+ }
+ await kv.set(KV.sessions, session.id, session);
+ stats.sessions++;
+ }
+
+ for (const [sessionId, obs] of Object.entries(importData.observations)) {
+ for (const o of obs) {
+ if (strategy === "skip") {
+ const existing = await kv
+ .get<CompressedObservation>(KV.observations(sessionId), o.id)
+ .catch(() => null);
+ if (existing) {
+ stats.skipped++;
+ continue;
+ }
+ }
+ await kv.set(KV.observations(sessionId), o.id, o);
+ stats.observations++;
+ }
+ }
+
+ for (const memory of importData.memories) {
+ if (strategy === "skip") {
+ const existing = await kv
+ .get<Memory>(KV.memories, memory.id)
+ .catch(() => null);
+ if (existing) {
+ stats.skipped++;
+ continue;
+ }
+ }
+ await kv.set(KV.memories, memory.id, memory);
+ stats.memories++;
+ }
+
+ for (const summary of importData.summaries) {
+ if (strategy === "skip") {
+ const existing = await kv
+ .get<SessionSummary>(KV.summaries, summary.sessionId)
+ .catch(() => null);
+ if (existing) {
+ stats.skipped++;
+ continue;
+ }
+ }
+ await kv.set(KV.summaries, summary.sessionId, summary);
+ stats.summaries++;
+ }
+
+ ctx.logger.info("Import complete", { strategy, ...stats });
+ return { success: true, strategy, ...stats };
+ },
+ );
+}
diff --git a/src/functions/profile.ts b/src/functions/profile.ts
new file mode 100644
index 00000000..1ec6dd72
--- /dev/null
+++ b/src/functions/profile.ts
@@ -0,0 +1,147 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ CompressedObservation,
+ Session,
+ ProjectProfile,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerProfileFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ {
+ id: "mem::profile",
+ description: "Generate or retrieve a project profile from aggregated data",
+ },
+ async (data: { project: string; refresh?: boolean }) => {
+ const ctx = getContext();
+
+ if (!data.refresh) {
+ const cached = await kv
+ .get<ProjectProfile>(KV.profiles, data.project)
+ .catch(() => null);
+ if (cached) {
+ const age = Date.now() - new Date(cached.updatedAt).getTime();
+ if (age < 3600_000) {
+ return { profile: cached, cached: true };
+ }
+ }
+ }
+
+ const sessions = await kv.list<Session>(KV.sessions);
+ const projectSessions = sessions.filter(
+ (s) => s.project === data.project,
+ );
+
+ if (projectSessions.length === 0) {
+ return { profile: null, reason: "no_sessions" };
+ }
+
+ const conceptFreq = new Map<string, number>();
+ const fileFreq = new Map<string, number>();
+ const errors: string[] = [];
+ const recentActivity: string[] = [];
+ let totalObs = 0;
+
+ const sortedSessions = projectSessions.sort(
+ (a, b) =>
+ new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
+ );
+
+ for (const session of sortedSessions.slice(0, 20)) {
+ const observations = await kv.list<CompressedObservation>(
+ KV.observations(session.id),
+ );
+ totalObs += observations.length;
+
+ for (const obs of observations) {
+ for (const concept of obs.concepts || []) {
+ conceptFreq.set(concept, (conceptFreq.get(concept) || 0) + 1);
+ }
+ for (const file of obs.files || []) {
+ fileFreq.set(file, (fileFreq.get(file) || 0) + 1);
+ }
+ if (obs.type === "error") {
+ errors.push(obs.title);
+ }
+ }
+
+ const important = observations
+ .filter((o) => o.importance >= 7)
+ .sort((a, b) => b.importance - a.importance);
+ if (important.length > 0) {
+ recentActivity.push(
+ `[${session.startedAt.slice(0, 10)}] ${important[0].title}`,
+ );
+ }
+ }
+
+ const topConcepts = Array.from(conceptFreq.entries())
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 15)
+ .map(([concept, frequency]) => ({ concept, frequency }));
+
+ const topFiles = Array.from(fileFreq.entries())
+ .sort((a, b) => b[1] - a[1])
+ .slice(0, 15)
+ .map(([file, frequency]) => ({ file, frequency }));
+
+ const uniqueErrors = [...new Set(errors)].slice(0, 10);
+
+ const profile: ProjectProfile = {
+ project: data.project,
+ updatedAt: new Date().toISOString(),
+ topConcepts,
+ topFiles,
+ conventions: extractConventions(topConcepts, topFiles),
+ commonErrors: uniqueErrors,
+ recentActivity: recentActivity.slice(0, 10),
+ sessionCount: projectSessions.length,
+ totalObservations: totalObs,
+ };
+
+ await kv.set(KV.profiles, data.project, profile);
+
+ ctx.logger.info("Profile generated", {
+ project: data.project,
+ sessions: projectSessions.length,
+ observations: totalObs,
+ });
+ return { profile, cached: false };
+ },
+ );
+}
+
+function extractConventions(
+ concepts: Array<{ concept: string; frequency: number }>,
+ files: Array<{ file: string; frequency: number }>,
+): string[] {
+ const conventions: string[] = [];
+
+ const tsFiles = files.filter((f) => f.file.endsWith(".ts")).length;
+ const jsFiles = files.filter((f) => f.file.endsWith(".js")).length;
+ if (tsFiles > jsFiles && tsFiles > 0) {
+ conventions.push("TypeScript project");
+ }
+
+ const srcFiles = files.filter((f) => f.file.includes("/src/")).length;
+ if (srcFiles > files.length * 0.5) {
+ conventions.push("Standard src/ directory structure");
+ }
+
+ const testFiles = files.filter(
+ (f) => f.file.includes("test") || f.file.includes("spec"),
+ ).length;
+ if (testFiles > 0) {
+ conventions.push("Has test files");
+ }
+
+ for (const { concept, frequency } of concepts.slice(0, 5)) {
+ if (frequency >= 3) {
+ conventions.push(`Frequently uses: ${concept}`);
+ }
+ }
+
+ return conventions;
+}
diff --git a/src/functions/relations.ts b/src/functions/relations.ts
new file mode 100644
index 00000000..0155678c
--- /dev/null
+++ b/src/functions/relations.ts
@@ -0,0 +1,151 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { Memory, MemoryRelation } from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerRelationsFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ { id: "mem::relate", description: "Create a relationship between memories" },
+ async (data: {
+ sourceId: string;
+ targetId: string;
+ type: MemoryRelation["type"];
+ }) => {
+ const ctx = getContext();
+
+ const source = await kv.get<Memory>(KV.memories, data.sourceId);
+ const target = await kv.get<Memory>(KV.memories, data.targetId);
+ if (!source || !target) {
+ return { success: false, error: "source or target memory not found" };
+ }
+
+ const relation: MemoryRelation = {
+ type: data.type,
+ sourceId: data.sourceId,
+ targetId: data.targetId,
+ createdAt: new Date().toISOString(),
+ };
+
+ const relationId = generateId("rel");
+ await kv.set(KV.relations, relationId, relation);
+
+ if (!source.relatedIds) source.relatedIds = [];
+ if (!source.relatedIds.includes(data.targetId)) {
+ source.relatedIds.push(data.targetId);
+ await kv.set(KV.memories, data.sourceId, source);
+ }
+
+ if (!target.relatedIds) target.relatedIds = [];
+ if (!target.relatedIds.includes(data.sourceId)) {
+ target.relatedIds.push(data.sourceId);
+ await kv.set(KV.memories, data.targetId, target);
+ }
+
+ ctx.logger.info("Memory relation created", {
+ relationId,
+ type: data.type,
+ source: data.sourceId,
+ target: data.targetId,
+ });
+ return { success: true, relationId, relation };
+ },
+ );
+
+ sdk.registerFunction(
+ { id: "mem::evolve", description: "Create a new version of a memory" },
+ async (data: {
+ memoryId: string;
+ newContent: string;
+ newTitle?: string;
+ }) => {
+ const ctx = getContext();
+
+ const existing = await kv.get<Memory>(KV.memories, data.memoryId);
+ if (!existing) {
+ return { success: false, error: "memory not found" };
+ }
+
+ existing.isLatest = false;
+ await kv.set(KV.memories, existing.id, existing);
+
+ const now = new Date().toISOString();
+ const evolved: Memory = {
+ ...existing,
+ id: generateId("mem"),
+ createdAt: now,
+ updatedAt: now,
+ title: data.newTitle || existing.title,
+ content: data.newContent,
+ version: (existing.version || 1) + 1,
+ parentId: existing.id,
+ supersedes: [existing.id, ...(existing.supersedes || [])],
+ isLatest: true,
+ };
+
+ await kv.set(KV.memories, evolved.id, evolved);
+
+ const relation: MemoryRelation = {
+ type: "supersedes",
+ sourceId: evolved.id,
+ targetId: existing.id,
+ createdAt: now,
+ };
+ await kv.set(KV.relations, generateId("rel"), relation);
+
+ ctx.logger.info("Memory evolved", {
+ oldId: existing.id,
+ newId: evolved.id,
+ version: evolved.version,
+ });
+ return { success: true, memory: evolved, previousId: existing.id };
+ },
+ );
+
+ sdk.registerFunction(
+ {
+ id: "mem::get-related",
+ description: "Get related memories within N hops",
+ },
+ async (data: { memoryId: string; maxHops?: number }) => {
+ const ctx = getContext();
+ const maxHops = data.maxHops ?? 2;
+
+ const visited = new Set<string>();
+ const result: Array<{ memory: Memory; hop: number }> = [];
+ const queue: Array<{ id: string; hop: number }> = [
+ { id: data.memoryId, hop: 0 },
+ ];
+
+ while (queue.length > 0) {
+ const current = queue.shift()!;
+ if (visited.has(current.id) || current.hop > maxHops) continue;
+ visited.add(current.id);
+
+ const memory = await kv.get<Memory>(KV.memories, current.id);
+ if (!memory) continue;
+
+ if (current.hop > 0) {
+ result.push({ memory, hop: current.hop });
+ }
+
+ const relatedIds = memory.relatedIds || [];
+ const supersedes = memory.supersedes || [];
+ const parentId = memory.parentId ? [memory.parentId] : [];
+ const allLinks = [...new Set([...relatedIds, ...supersedes, ...parentId])];
+
+ for (const nextId of allLinks) {
+ if (!visited.has(nextId)) {
+ queue.push({ id: nextId, hop: current.hop + 1 });
+ }
+ }
+ }
+
+ ctx.logger.info("Related memories retrieved", {
+ memoryId: data.memoryId,
+ found: result.length,
+ });
+ return { results: result };
+ },
+ );
+}
diff --git a/src/functions/remember.ts b/src/functions/remember.ts
index b63a0307..02d27592 100644
--- a/src/functions/remember.ts
+++ b/src/functions/remember.ts
@@ -1,7 +1,7 @@
import type { ISdk } from "iii-sdk";
import { getContext } from "iii-sdk";
import type { Memory } from "../types.js";
-import { KV, generateId } from "../state/schema.js";
+import { KV, generateId, jaccardSimilarity } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
@@ -30,6 +30,24 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
: "fact";
const now = new Date().toISOString();
+
+ const existingMemories = await kv.list<Memory>(KV.memories);
+ let supersededId: string | undefined;
+ const lowerContent = data.content.toLowerCase();
+ for (const existing of existingMemories) {
+ if (!existing.isLatest) continue;
+ const similarity = jaccardSimilarity(
+ lowerContent,
+ existing.content.toLowerCase(),
+ );
+ if (similarity > 0.7) {
+ existing.isLatest = false;
+ await kv.set(KV.memories, existing.id, existing);
+ supersededId = existing.id;
+ break;
+ }
+ }
+
const memory: Memory = {
id: generateId("mem"),
createdAt: now,
@@ -41,6 +59,10 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void {
files: data.files || [],
sessionIds: [],
strength: 7,
+ version: supersededId ? 2 : 1,
+ parentId: supersededId,
+ supersedes: supersededId ? [supersededId] : [],
+ isLatest: true,
};
await kv.set(KV.memories, memory.id, memory);
diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.ts
new file mode 100644
index 00000000..eb369725
--- /dev/null
+++ b/src/functions/smart-search.ts
@@ -0,0 +1,87 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+ CompactSearchResult,
+ CompressedObservation,
+ HybridSearchResult,
+} from "../types.js";
+import { KV } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerSmartSearchFunction(
+ sdk: ISdk,
+ kv: StateKV,
+ searchFn: (query: string, limit: number) => Promise<HybridSearchResult[]>,
+): void {
+ sdk.registerFunction(
+ {
+ id: "mem::smart-search",
+ description:
+ "Search with progressive disclosure: compact results first, expand specific IDs for full details",
+ },
+ async (data: { query?: string; expandIds?: string[]; limit?: number }) => {
+ const ctx = getContext();
+
+ if (data.expandIds && data.expandIds.length > 0) {
+ const expanded: Array<{
+ obsId: string;
+ sessionId: string;
+ observation: CompressedObservation;
+ }> = [];
+
+ for (const obsId of data.expandIds) {
+ const obs = await findObservation(kv, obsId);
+ if (obs) {
+ expanded.push({
+ obsId,
+ sessionId: obs.sessionId,
+ observation: obs,
+ });
+ }
+ }
+
+ ctx.logger.info("Smart search expanded", {
+ requested: data.expandIds.length,
+ found: expanded.length,
+ });
+ return { mode: "expanded", results: expanded };
+ }
+
+ if (!data.query) {
+ return { mode: "compact", results: [], error: "query is required" };
+ }
+
+ const limit = data.limit ?? 20;
+ const hybridResults = await searchFn(data.query, limit);
+
+ const compact: CompactSearchResult[] = hybridResults.map((r) => ({
+ obsId: r.observation.id,
+ sessionId: r.sessionId,
+ title: r.observation.title,
+ type: r.observation.type,
+ score: r.combinedScore,
+ timestamp: r.observation.timestamp,
+ }));
+
+ ctx.logger.info("Smart search compact", {
+ query: data.query,
+ results: compact.length,
+ });
+ return { mode: "compact", results: compact };
+ },
+ );
+}
+
+async function findObservation(
+ kv: StateKV,
+ obsId: string,
+): Promise<CompressedObservation | null> {
+ const sessions = await kv.list<{ id: string }>(KV.sessions);
+ for (const session of sessions) {
+ const obs = await kv
+ .get<CompressedObservation>(KV.observations(session.id), obsId)
+ .catch(() => null);
+ if (obs) return obs;
+ }
+ return null;
+}
diff --git a/src/functions/timeline.ts b/src/functions/timeline.ts
new file mode 100644
index 00000000..668b650a
--- /dev/null
+++ b/src/functions/timeline.ts
@@ -0,0 +1,124 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type { CompressedObservation, Session, TimelineEntry } from "../types.js";
+import { KV } from "../state/schema.js";
+import { StateKV } from "../state/kv.js";
+
+export function registerTimelineFunction(sdk: ISdk, kv: StateKV): void {
+ sdk.registerFunction(
+ {
+ id: "mem::timeline",
+ description: "Get chronological observations around an anchor point",
+ },
+ async (data: {
+ anchor: string;
+ project?: string;
+ before?: number;
+ after?: number;
+ }) => {
+ const ctx = getContext();
+ const before = data.before ?? 5;
+ const after = data.after ?? 5;
+
+ let anchorTime: number;
+ const isoPattern = /^\d{4}-\d{2}-\d{2}/;
+ if (isoPattern.test(data.anchor)) {
+ anchorTime = new Date(data.anchor).getTime();
+ } else {
+ const searchResults = await findByKeyword(kv, data.anchor, data.project);
+ if (searchResults.length === 0) {
+ return { entries: [], anchor: data.anchor, reason: "no_match" };
+ }
+ anchorTime = new Date(searchResults[0].timestamp).getTime();
+ }
+
+ const sessions = await kv.list<Session>(KV.sessions);
+ const filtered = data.project
+ ? sessions.filter((s) => s.project === data.project)
+ : sessions;
+
+ const allObs: Array<CompressedObservation & { sid: string }> = [];
+ for (const session of filtered) {
+ const observations = await kv.list<CompressedObservation>(
+ KV.observations(session.id),
+ );
+ for (const obs of observations) {
+ if (obs.title && obs.timestamp) {
+ allObs.push({ ...obs, sid: session.id });
+ }
+ }
+ }
+
+ allObs.sort(
+ (a, b) =>
+ new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+ );
+
+ let anchorIdx = 0;
+ let minDist = Infinity;
+ for (let i = 0; i < allObs.length; i++) {
+ const dist = Math.abs(
+ new Date(allObs[i].timestamp).getTime() - anchorTime,
+ );
+ if (dist < minDist) {
+ minDist = dist;
+ anchorIdx = i;
+ }
+ }
+
+ const startIdx = Math.max(0, anchorIdx - before);
+ const endIdx = Math.min(allObs.length - 1, anchorIdx + after);
+ const entries: TimelineEntry[] = [];
+
+ for (let i = startIdx; i <= endIdx; i++) {
+ const obs = allObs[i];
+ const { sid, ...observation } = obs;
+ entries.push({
+ observation,
+ sessionId: sid,
+ relativePosition: i - anchorIdx,
+ });
+ }
+
+ ctx.logger.info("Timeline retrieved", {
+ anchor: data.anchor,
+ entries: entries.length,
+ });
+ return { entries, anchorIndex: anchorIdx - startIdx };
+ },
+ );
+}
+
+async function findByKeyword(
+ kv: StateKV,
+ keyword: string,
+ project?: string,
+): Promise<CompressedObservation[]> {
+ const sessions = await kv.list<Session>(KV.sessions);
+ const filtered = project
+ ? sessions.filter((s) => s.project === project)
+ : sessions;
+
+ const lower = keyword.toLowerCase();
+ const matches: CompressedObservation[] = [];
+
+ for (const session of filtered) {
+ const observations = await kv.list<CompressedObservation>(
+ KV.observations(session.id),
+ );
+ for (const obs of observations) {
+ if (
+ obs.title?.toLowerCase().includes(lower) ||
+ obs.narrative?.toLowerCase().includes(lower) ||
+ obs.concepts?.some((c) => c.toLowerCase().includes(lower))
+ ) {
+ matches.push(obs);
+ }
+ }
+ }
+
+ return matches.sort(
+ (a, b) =>
+ new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+ );
+}
diff --git a/src/health/monitor.ts b/src/health/monitor.ts
index d8fdcbd7..73cd3f48 100644
--- a/src/health/monitor.ts
+++ b/src/health/monitor.ts
@@ -13,8 +13,8 @@ export function registerHealthMonitor(
let prevCpuTime = Date.now();
if (typeof sdk.on === "function") {
- sdk.on("connection_state", (state: string) => {
- connectionState = state;
+ sdk.on("connection_state", (state?: unknown) => {
+ connectionState = state as string;
});
}
@@ -28,9 +28,7 @@ export function registerHealthMonitor(
const userDelta = currentCpu.user - prevCpuUsage.user;
const systemDelta = currentCpu.system - prevCpuUsage.system;
const cpuPercent =
- elapsedMs > 0
- ? ((userDelta + systemDelta) / 1000 / elapsedMs) * 100
- : 0;
+ elapsedMs > 0 ? ((userDelta + systemDelta) / 1000 / elapsedMs) * 100 : 0;
prevCpuUsage = currentCpu;
prevCpuTime = now;
diff --git a/src/index.ts b/src/index.ts
index 9e3629f4..198619fd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,11 +1,27 @@
import { init } from "iii-sdk";
-import { loadConfig, getEnvVar } from "./config.js";
-import { createProvider } from "./providers/index.js";
+import {
+ loadConfig,
+ getEnvVar,
+ loadEmbeddingConfig,
+ loadFallbackConfig,
+} from "./config.js";
+import {
+ createProvider,
+ createFallbackProvider,
+ createEmbeddingProvider,
+} from "./providers/index.js";
import { StateKV } from "./state/kv.js";
+import { VectorIndex } from "./state/vector-index.js";
+import { HybridSearch } from "./state/hybrid-search.js";
+import { IndexPersistence } from "./state/index-persistence.js";
import { registerPrivacyFunction } from "./functions/privacy.js";
import { registerObserveFunction } from "./functions/observe.js";
import { registerCompressFunction } from "./functions/compress.js";
-import { registerSearchFunction, rebuildIndex } from "./functions/search.js";
+import {
+ registerSearchFunction,
+ rebuildIndex,
+ getSearchIndex,
+} from "./functions/search.js";
import { registerContextFunction } from "./functions/context.js";
import { registerSummarizeFunction } from "./functions/summarize.js";
import { registerMigrateFunction } from "./functions/migrate.js";
@@ -14,24 +30,44 @@ import { registerConsolidateFunction } from "./functions/consolidate.js";
import { registerPatternsFunction } from "./functions/patterns.js";
import { registerRememberFunction } from "./functions/remember.js";
import { registerEvictFunction } from "./functions/evict.js";
+import { registerRelationsFunction } from "./functions/relations.js";
+import { registerTimelineFunction } from "./functions/timeline.js";
+import { registerSmartSearchFunction } from "./functions/smart-search.js";
+import { registerProfileFunction } from "./functions/profile.js";
+import { registerAutoForgetFunction } from "./functions/auto-forget.js";
+import { registerExportImportFunction } from "./functions/export-import.js";
import { registerApiTriggers } from "./triggers/api.js";
import { registerEventTriggers } from "./triggers/events.js";
import { registerMcpEndpoints } from "./mcp/server.js";
import { MetricsStore } from "./eval/metrics-store.js";
import { DedupMap } from "./functions/dedup.js";
-import { ObservationQueue } from "./health/recovery.js";
-import { registerHealthMonitor, getLatestHealth } from "./health/monitor.js";
+import { registerHealthMonitor } from "./health/monitor.js";
import { initMetrics, OTEL_CONFIG } from "./telemetry/setup.js";
async function main() {
const config = loadConfig();
- const provider = createProvider(config.provider);
+ const embeddingConfig = loadEmbeddingConfig();
+ const fallbackConfig = loadFallbackConfig();
- console.log(`[agentmemory] Starting worker v0.2.0...`);
+ const provider =
+ fallbackConfig.providers.length > 0
+ ? createFallbackProvider(config.provider, fallbackConfig)
+ : createProvider(config.provider);
+
+ const embeddingProvider = createEmbeddingProvider();
+
+ console.log(`[agentmemory] Starting worker v0.3.0...`);
console.log(`[agentmemory] Engine: ${config.engineUrl}`);
console.log(
`[agentmemory] Provider: ${config.provider.provider} (${config.provider.model})`,
);
+ if (embeddingProvider) {
+ console.log(
+ `[agentmemory] Embedding provider: ${embeddingProvider.name} (${embeddingProvider.dimensions} dims)`,
+ );
+ } else {
+ console.log(`[agentmemory] Embedding provider: none (BM25-only mode)`);
+ }
console.log(
`[agentmemory] REST API: http://localhost:${config.restPort}/agentmemory/*`,
);
@@ -50,10 +86,13 @@ async function main() {
const secret = getEnvVar("AGENTMEMORY_SECRET");
const metricsStore = new MetricsStore(kv);
const dedupMap = new DedupMap();
- const observationQueue = new ObservationQueue();
- const { counters, histograms } = initMetrics(
- typeof sdk.getMeter === "function" ? sdk.getMeter.bind(sdk) : undefined,
+ const vectorIndex = embeddingProvider ? new VectorIndex() : null;
+
+ initMetrics(
+ typeof (sdk as any).getMeter === "function"
+ ? (sdk as any).getMeter.bind(sdk)
+ : undefined,
);
registerPrivacyFunction(sdk);
@@ -69,50 +108,65 @@ async function main() {
registerRememberFunction(sdk, kv);
registerEvictFunction(sdk, kv);
+ registerRelationsFunction(sdk, kv);
+ registerTimelineFunction(sdk, kv);
+ registerProfileFunction(sdk, kv);
+ registerAutoForgetFunction(sdk, kv);
+ registerExportImportFunction(sdk, kv);
+
+ const bm25Index = getSearchIndex();
+ const hybridSearch = new HybridSearch(
+ bm25Index,
+ vectorIndex,
+ embeddingProvider,
+ kv,
+ embeddingConfig.bm25Weight,
+ embeddingConfig.vectorWeight,
+ );
+
+ registerSmartSearchFunction(sdk, kv, (query, limit) =>
+ hybridSearch.search(query, limit),
+ );
+
registerApiTriggers(sdk, kv, secret, metricsStore, provider);
registerEventTriggers(sdk, kv);
registerMcpEndpoints(sdk, kv, secret);
const healthMonitor = registerHealthMonitor(sdk, kv);
- const indexCount = await rebuildIndex(kv).catch(() => 0);
- if (indexCount > 0) {
- console.log(`[agentmemory] Search index: ${indexCount} observations`);
+ const indexPersistence = new IndexPersistence(kv, bm25Index, vectorIndex);
+
+ const loaded = await indexPersistence.load().catch(() => null);
+ if (loaded?.bm25) {
+ const restoredCount = loaded.bm25.size;
+ if (restoredCount > 0) {
+ console.log(
+ `[agentmemory] Loaded persisted BM25 index (${restoredCount} docs)`,
+ );
+ }
+ }
+
+ if (!loaded?.bm25 || loaded.bm25.size === 0) {
+ const indexCount = await rebuildIndex(kv).catch(() => 0);
+ if (indexCount > 0) {
+ console.log(
+ `[agentmemory] Search index rebuilt: ${indexCount} observations`,
+ );
+ indexPersistence.scheduleSave();
+ }
}
- console.log(`[agentmemory] Ready. Endpoints:`);
- console.log(
- ` POST /agentmemory/session/start - Start session + get context`,
- );
- console.log(` POST /agentmemory/observe - Capture observation`);
- console.log(` POST /agentmemory/context - Generate context`);
- console.log(` POST /agentmemory/search - Search observations`);
- console.log(` POST /agentmemory/summarize - Summarize session`);
- console.log(
- ` POST /agentmemory/remember - Save to long-term memory`,
- );
- console.log(` POST /agentmemory/forget - Delete memory data`);
- console.log(` POST /agentmemory/file-context - File history context`);
- console.log(` POST /agentmemory/consolidate - Consolidate memories`);
- console.log(` POST /agentmemory/patterns - Detect patterns`);
- console.log(` POST /agentmemory/evict - Evict stale memories`);
- console.log(` GET /agentmemory/sessions - List sessions`);
- console.log(
- ` GET /agentmemory/observations - Get session observations`,
- );
- console.log(` GET /agentmemory/health - Health + metrics`);
- console.log(` GET /agentmemory/viewer - Web viewer`);
console.log(
- ` POST /agentmemory/generate-rules - Generate rules from patterns`,
+ `[agentmemory] Ready. ${embeddingProvider ? "Hybrid" : "BM25"} search active.`,
);
- console.log(` POST /agentmemory/migrate - Import from SQLite`);
- console.log(` GET /agentmemory/mcp/tools - MCP tool listing`);
- console.log(` POST /agentmemory/mcp/call - MCP tool execution`);
+ console.log(`[agentmemory] Endpoints: 28 REST + 10 MCP tools + 21 functions`);
const shutdown = async () => {
console.log(`\n[agentmemory] Shutting down...`);
healthMonitor.stop();
dedupMap.stop();
+ indexPersistence.stop();
+ await indexPersistence.save().catch(() => {});
await sdk.shutdown();
process.exit(0);
};
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index e4a19b0e..306633b7 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -109,6 +109,105 @@ const MCP_TOOLS: McpTool[] = [
properties: {},
},
},
+ {
+ name: "memory_smart_search",
+ description:
+ "Hybrid semantic+keyword search with progressive disclosure. Returns compact summaries first; pass expandIds to get full observation text.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description: "Search query combining semantic and keyword matching",
+ },
+ expandIds: {
+ type: "string",
+ description:
+ "Comma-separated observation IDs to expand with full text",
+ },
+ limit: {
+ type: "number",
+ description: "Max results to return (default 10)",
+ },
+ },
+ required: ["query"],
+ },
+ },
+ {
+ name: "memory_timeline",
+ description:
+ "Chronological observations around an anchor point. Use to see what happened before and after a specific date or event.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ anchor: {
+ type: "string",
+ description:
+ "Anchor point: ISO date (e.g. 2026-02-15) or keyword (today, yesterday, last-week)",
+ },
+ project: {
+ type: "string",
+ description: "Filter by project path",
+ },
+ before: {
+ type: "number",
+ description: "Number of observations before anchor (default 5)",
+ },
+ after: {
+ type: "number",
+ description: "Number of observations after anchor (default 5)",
+ },
+ },
+ required: ["anchor"],
+ },
+ },
+ {
+ name: "memory_profile",
+ description:
+ "User/project profile with top concepts, frequently modified files, and recurring patterns.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ project: {
+ type: "string",
+ description: "Project path to build profile for",
+ },
+ refresh: {
+ type: "string",
+ description: "Set to 'true' to force rebuild the profile cache",
+ },
+ },
+ required: ["project"],
+ },
+ },
+ {
+ name: "memory_export",
+ description:
+ "Export all memory data as JSON. Useful for backup or migration.",
+ inputSchema: {
+ type: "object",
+ properties: {},
+ },
+ },
+ {
+ name: "memory_relations",
+ description:
+ "Query the memory relationship graph. Returns related memories within a given hop distance.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ memoryId: {
+ type: "string",
+ description: "ID of the memory to find relations for",
+ },
+ maxHops: {
+ type: "number",
+ description: "Maximum graph traversal depth (default 2)",
+ },
+ },
+ required: ["memoryId"],
+ },
+ },
];
export function registerMcpEndpoints(
@@ -265,6 +364,110 @@ export function registerMcpEndpoints(
};
}
+ case "memory_smart_search": {
+ if (typeof args.query !== "string" || !args.query.trim()) {
+ return {
+ status_code: 400,
+ body: { error: "query is required for memory_smart_search" },
+ };
+ }
+ const expandIds = args.expandIds
+ ? (args.expandIds as string)
+ .split(",")
+ .map((id: string) => id.trim())
+ : [];
+ const result = await sdk.trigger("mem::smart-search", {
+ query: args.query,
+ expandIds,
+ limit: (args.limit as number) || 10,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ }
+
+ case "memory_timeline": {
+ if (typeof args.anchor !== "string" || !args.anchor.trim()) {
+ return {
+ status_code: 400,
+ body: { error: "anchor is required for memory_timeline" },
+ };
+ }
+ const result = await sdk.trigger("mem::timeline", {
+ anchor: args.anchor,
+ project: (args.project as string) || undefined,
+ before: (args.before as number) || 5,
+ after: (args.after as number) || 5,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ }
+
+ case "memory_profile": {
+ if (typeof args.project !== "string" || !args.project.trim()) {
+ return {
+ status_code: 400,
+ body: { error: "project is required for memory_profile" },
+ };
+ }
+ const result = await sdk.trigger("mem::profile", {
+ project: args.project,
+ refresh: args.refresh === "true",
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ }
+
+ case "memory_export": {
+ const result = await sdk.trigger("mem::export", {});
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ }
+
+ case "memory_relations": {
+ if (typeof args.memoryId !== "string" || !args.memoryId.trim()) {
+ return {
+ status_code: 400,
+ body: { error: "memoryId is required for memory_relations" },
+ };
+ }
+ const result = await sdk.trigger("mem::get-related", {
+ memoryId: args.memoryId,
+ maxHops: (args.maxHops as number) || 2,
+ });
+ return {
+ status_code: 200,
+ body: {
+ content: [
+ { type: "text", text: JSON.stringify(result, null, 2) },
+ ],
+ },
+ };
+ }
+
default:
return {
status_code: 400,
diff --git a/src/providers/embedding/cohere.ts b/src/providers/embedding/cohere.ts
new file mode 100644
index 00000000..1a96cc44
--- /dev/null
+++ b/src/providers/embedding/cohere.ts
@@ -0,0 +1,46 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const API_URL = "https://api.cohere.ai/v1/embed";
+
+export class CohereEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "cohere";
+ readonly dimensions = 1024;
+ private apiKey: string;
+
+ constructor(apiKey?: string) {
+ this.apiKey = apiKey || getEnvVar("COHERE_API_KEY") || "";
+ if (!this.apiKey) throw new Error("COHERE_API_KEY is required");
+ }
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const response = await fetch(API_URL, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ model: "embed-english-v3.0",
+ texts,
+ input_type: "search_document",
+ }),
+ });
+
+ if (!response.ok) {
+ const err = await response.text();
+ throw new Error(`Cohere embedding failed (${response.status}): ${err}`);
+ }
+
+ const data = (await response.json()) as {
+ embeddings: number[][];
+ };
+
+ return data.embeddings.map((e) => new Float32Array(e));
+ }
+}
diff --git a/src/providers/embedding/gemini.ts b/src/providers/embedding/gemini.ts
new file mode 100644
index 00000000..74dca6f5
--- /dev/null
+++ b/src/providers/embedding/gemini.ts
@@ -0,0 +1,54 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const BATCH_LIMIT = 100;
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContent";
+
+export class GeminiEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "gemini";
+ readonly dimensions = 768;
+ private apiKey: string;
+
+ constructor(apiKey?: string) {
+ this.apiKey = apiKey || getEnvVar("GEMINI_API_KEY") || "";
+ if (!this.apiKey) throw new Error("GEMINI_API_KEY is required");
+ }
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const results: Float32Array[] = [];
+
+ for (let i = 0; i < texts.length; i += BATCH_LIMIT) {
+ const chunk = texts.slice(i, i + BATCH_LIMIT);
+ const response = await fetch(`${API_BASE}?key=${this.apiKey}`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ requests: chunk.map((t) => ({
+ model: "models/text-embedding-004",
+ content: { parts: [{ text: t }] },
+ })),
+ }),
+ });
+
+ if (!response.ok) {
+ const err = await response.text();
+ throw new Error(`Gemini embedding failed (${response.status}): ${err}`);
+ }
+
+ const data = (await response.json()) as {
+ embeddings: Array<{ values: number[] }>;
+ };
+
+ for (const emb of data.embeddings) {
+ results.push(new Float32Array(emb.values));
+ }
+ }
+
+ return results;
+ }
+}
diff --git a/src/providers/embedding/index.ts b/src/providers/embedding/index.ts
new file mode 100644
index 00000000..0f52514e
--- /dev/null
+++ b/src/providers/embedding/index.ts
@@ -0,0 +1,39 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { detectEmbeddingProvider, getEnvVar } from "../../config.js";
+import { GeminiEmbeddingProvider } from "./gemini.js";
+import { OpenAIEmbeddingProvider } from "./openai.js";
+import { VoyageEmbeddingProvider } from "./voyage.js";
+import { CohereEmbeddingProvider } from "./cohere.js";
+import { OpenRouterEmbeddingProvider } from "./openrouter.js";
+import { LocalEmbeddingProvider } from "./local.js";
+
+export {
+ GeminiEmbeddingProvider,
+ OpenAIEmbeddingProvider,
+ VoyageEmbeddingProvider,
+ CohereEmbeddingProvider,
+ OpenRouterEmbeddingProvider,
+ LocalEmbeddingProvider,
+};
+
+export function createEmbeddingProvider(): EmbeddingProvider | null {
+ const detected = detectEmbeddingProvider();
+ if (!detected) return null;
+
+ switch (detected) {
+ case "gemini":
+ return new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!);
+ case "openai":
+ return new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!);
+ case "voyage":
+ return new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!);
+ case "cohere":
+ return new CohereEmbeddingProvider(getEnvVar("COHERE_API_KEY")!);
+ case "openrouter":
+ return new OpenRouterEmbeddingProvider(getEnvVar("OPENROUTER_API_KEY")!);
+ case "local":
+ return new LocalEmbeddingProvider();
+ default:
+ return null;
+ }
+}
diff --git a/src/providers/embedding/local.ts b/src/providers/embedding/local.ts
new file mode 100644
index 00000000..ad6c2d21
--- /dev/null
+++ b/src/providers/embedding/local.ts
@@ -0,0 +1,52 @@
+import type { EmbeddingProvider } from "../../types.js";
+
+type Pipeline = (
+ task: string,
+ model: string,
+) => Promise<
+ (
+ texts: string[],
+ options: { pooling: string; normalize: boolean },
+ ) => Promise<{ tolist: () => number[][] }>
+>;
+
+export class LocalEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "local";
+ readonly dimensions = 384;
+ private extractor: Awaited<ReturnType<Pipeline>> | null = null;
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const extractor = await this.getExtractor();
+ const output = await extractor(texts, {
+ pooling: "mean",
+ normalize: true,
+ });
+ const vectors = output.tolist();
+ return vectors.map((v: number[]) => new Float32Array(v));
+ }
+
+ private async getExtractor() {
+ if (this.extractor) return this.extractor;
+
+ let transformers: { pipeline: Pipeline };
+ try {
+ // @ts-ignore - optional peer dependency
+ transformers = await import("@xenova/transformers");
+ } catch {
+ throw new Error(
+ "Install @xenova/transformers for local embeddings: npm install @xenova/transformers",
+ );
+ }
+
+ this.extractor = await transformers.pipeline(
+ "feature-extraction",
+ "Xenova/all-MiniLM-L6-v2",
+ );
+ return this.extractor;
+ }
+}
diff --git a/src/providers/embedding/openai.ts b/src/providers/embedding/openai.ts
new file mode 100644
index 00000000..c868d4a6
--- /dev/null
+++ b/src/providers/embedding/openai.ts
@@ -0,0 +1,45 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const API_URL = "https://api.openai.com/v1/embeddings";
+
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "openai";
+ readonly dimensions = 1536;
+ private apiKey: string;
+
+ constructor(apiKey?: string) {
+ this.apiKey = apiKey || getEnvVar("OPENAI_API_KEY") || "";
+ if (!this.apiKey) throw new Error("OPENAI_API_KEY is required");
+ }
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const response = await fetch(API_URL, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ model: "text-embedding-3-small",
+ input: texts,
+ }),
+ });
+
+ if (!response.ok) {
+ const err = await response.text();
+ throw new Error(`OpenAI embedding failed (${response.status}): ${err}`);
+ }
+
+ const data = (await response.json()) as {
+ data: Array<{ embedding: number[] }>;
+ };
+
+ return data.data.map((d) => new Float32Array(d.embedding));
+ }
+}
diff --git a/src/providers/embedding/openrouter.ts b/src/providers/embedding/openrouter.ts
new file mode 100644
index 00000000..7d4acb26
--- /dev/null
+++ b/src/providers/embedding/openrouter.ts
@@ -0,0 +1,51 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const API_URL = "https://openrouter.ai/api/v1/embeddings";
+
+export class OpenRouterEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "openrouter";
+ readonly dimensions = 1536;
+ private apiKey: string;
+ private model: string;
+
+ constructor(apiKey?: string) {
+ this.apiKey = apiKey || getEnvVar("OPENROUTER_API_KEY") || "";
+ if (!this.apiKey) throw new Error("OPENROUTER_API_KEY is required");
+ this.model =
+ getEnvVar("OPENROUTER_EMBEDDING_MODEL") ||
+ "openai/text-embedding-3-small";
+ }
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const response = await fetch(API_URL, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ model: this.model,
+ input: texts,
+ }),
+ });
+
+ if (!response.ok) {
+ const err = await response.text();
+ throw new Error(
+ `OpenRouter embedding failed (${response.status}): ${err}`,
+ );
+ }
+
+ const data = (await response.json()) as {
+ data: Array<{ embedding: number[] }>;
+ };
+
+ return data.data.map((d) => new Float32Array(d.embedding));
+ }
+}
diff --git a/src/providers/embedding/voyage.ts b/src/providers/embedding/voyage.ts
new file mode 100644
index 00000000..b92fb602
--- /dev/null
+++ b/src/providers/embedding/voyage.ts
@@ -0,0 +1,46 @@
+import type { EmbeddingProvider } from "../../types.js";
+import { getEnvVar } from "../../config.js";
+
+const API_URL = "https://api.voyageai.com/v1/embeddings";
+
+export class VoyageEmbeddingProvider implements EmbeddingProvider {
+ readonly name = "voyage";
+ readonly dimensions = 1024;
+ private apiKey: string;
+
+ constructor(apiKey?: string) {
+ this.apiKey = apiKey || getEnvVar("VOYAGE_API_KEY") || "";
+ if (!this.apiKey) throw new Error("VOYAGE_API_KEY is required");
+ }
+
+ async embed(text: string): Promise<Float32Array> {
+ const [result] = await this.embedBatch([text]);
+ return result;
+ }
+
+ async embedBatch(texts: string[]): Promise<Float32Array[]> {
+ const response = await fetch(API_URL, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ model: "voyage-code-3",
+ input: texts,
+ input_type: "document",
+ }),
+ });
+
+ if (!response.ok) {
+ const err = await response.text();
+ throw new Error(`Voyage embedding failed (${response.status}): ${err}`);
+ }
+
+ const data = (await response.json()) as {
+ data: Array<{ embedding: number[] }>;
+ };
+
+ return data.data.map((d) => new Float32Array(d.embedding));
+ }
+}
diff --git a/src/providers/fallback-chain.ts b/src/providers/fallback-chain.ts
new file mode 100644
index 00000000..e2c979f9
--- /dev/null
+++ b/src/providers/fallback-chain.ts
@@ -0,0 +1,31 @@
+import type { MemoryProvider } from "../types.js";
+
+export class FallbackChainProvider implements MemoryProvider {
+ name: string;
+
+ constructor(private providers: MemoryProvider[]) {
+ this.name = `fallback(${providers.map((p) => p.name).join(" -> ")})`;
+ }
+
+ async compress(systemPrompt: string, userPrompt: string): Promise<string> {
+ return this.tryAll((p) => p.compress(systemPrompt, userPrompt));
+ }
+
+ async summarize(systemPrompt: string, userPrompt: string): Promise<string> {
+ return this.tryAll((p) => p.summarize(systemPrompt, userPrompt));
+ }
+
+ private async tryAll(
+ fn: (p: MemoryProvider) => Promise<string>,
+ ): Promise<string> {
+ let lastError: Error | null = null;
+ for (const provider of this.providers) {
+ try {
+ return await fn(provider);
+ } catch (err) {
+ lastError = err instanceof Error ? err : new Error(String(err));
+ }
+ }
+ throw lastError || new Error("No providers available");
+ }
+}
diff --git a/src/providers/index.ts b/src/providers/index.ts
index 7d54c2a9..becf491c 100644
--- a/src/providers/index.ts
+++ b/src/providers/index.ts
@@ -1,10 +1,17 @@
-import type { MemoryProvider, ProviderConfig } from "../types.js";
+import type {
+ MemoryProvider,
+ ProviderConfig,
+ FallbackConfig,
+} from "../types.js";
import { AgentSDKProvider } from "./agent-sdk.js";
import { AnthropicProvider } from "./anthropic.js";
import { OpenRouterProvider } from "./openrouter.js";
import { ResilientProvider } from "./resilient.js";
+import { FallbackChainProvider } from "./fallback-chain.js";
import { getEnvVar } from "../config.js";
+export { createEmbeddingProvider } from "./embedding/index.js";
+
function requireEnvVar(key: string): string {
const value = getEnvVar(key);
if (!value) {
@@ -16,35 +23,62 @@ function requireEnvVar(key: string): string {
}
export function createProvider(config: ProviderConfig): ResilientProvider {
- let base: MemoryProvider;
+ return new ResilientProvider(createBaseProvider(config));
+}
+
+export function createFallbackProvider(
+ config: ProviderConfig,
+ fallbackConfig: FallbackConfig,
+): ResilientProvider {
+ if (fallbackConfig.providers.length === 0) {
+ return createProvider(config);
+ }
+
+ const providers: MemoryProvider[] = [createBaseProvider(config)];
+ for (const providerType of fallbackConfig.providers) {
+ if (providerType === config.provider) continue;
+ try {
+ const fbConfig: ProviderConfig = {
+ provider: providerType,
+ model: config.model,
+ maxTokens: config.maxTokens,
+ };
+ providers.push(createBaseProvider(fbConfig));
+ } catch {
+ // skip unavailable fallback providers
+ }
+ }
+
+ if (providers.length > 1) {
+ return new ResilientProvider(new FallbackChainProvider(providers));
+ }
+ return new ResilientProvider(providers[0]);
+}
+
+function createBaseProvider(config: ProviderConfig): MemoryProvider {
switch (config.provider) {
case "anthropic":
- base = new AnthropicProvider(
+ return new AnthropicProvider(
requireEnvVar("ANTHROPIC_API_KEY"),
config.model,
config.maxTokens,
);
- break;
case "gemini":
- base = new OpenRouterProvider(
+ return new OpenRouterProvider(
requireEnvVar("GEMINI_API_KEY"),
config.model,
config.maxTokens,
"https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
);
- break;
case "openrouter":
- base = new OpenRouterProvider(
+ return new OpenRouterProvider(
requireEnvVar("OPENROUTER_API_KEY"),
config.model,
config.maxTokens,
"https://openrouter.ai/api/v1/chat/completions",
);
- break;
case "agent-sdk":
default:
- base = new AgentSDKProvider();
- break;
+ return new AgentSDKProvider();
}
- return new ResilientProvider(base);
}
diff --git a/src/state/hybrid-search.ts b/src/state/hybrid-search.ts
new file mode 100644
index 00000000..4d33b0cc
--- /dev/null
+++ b/src/state/hybrid-search.ts
@@ -0,0 +1,115 @@
+import { SearchIndex } from "./search-index.js";
+import { VectorIndex } from "./vector-index.js";
+import type {
+ EmbeddingProvider,
+ HybridSearchResult,
+ CompressedObservation,
+} from "../types.js";
+import type { StateKV } from "./kv.js";
+import { KV } from "./schema.js";
+
+const RRF_K = 60;
+
+export class HybridSearch {
+ constructor(
+ private bm25: SearchIndex,
+ private vector: VectorIndex | null,
+ private embeddingProvider: EmbeddingProvider | null,
+ private kv: StateKV,
+ private bm25Weight = 0.4,
+ private vectorWeight = 0.6,
+ ) {}
+
+ async search(query: string, limit = 20): Promise<HybridSearchResult[]> {
+ const bm25Results = this.bm25.search(query, limit * 2);
+
+ if (!this.vector || !this.embeddingProvider || this.vector.size === 0) {
+ return this.enrichResults(
+ bm25Results.map((r) => ({
+ obsId: r.obsId,
+ sessionId: r.sessionId,
+ bm25Score: r.score,
+ vectorScore: 0,
+ combinedScore: r.score,
+ })),
+ limit,
+ );
+ }
+
+ const queryEmbedding = await this.embeddingProvider.embed(query);
+ const vectorResults = this.vector.search(queryEmbedding, limit * 2);
+
+ const scores = new Map<
+ string,
+ {
+ bm25Rank: number;
+ vectorRank: number;
+ sessionId: string;
+ bm25Score: number;
+ vectorScore: number;
+ }
+ >();
+
+ bm25Results.forEach((r, i) => {
+ scores.set(r.obsId, {
+ bm25Rank: i + 1,
+ vectorRank: Infinity,
+ sessionId: r.sessionId,
+ bm25Score: r.score,
+ vectorScore: 0,
+ });
+ });
+
+ vectorResults.forEach((r, i) => {
+ const existing = scores.get(r.obsId);
+ if (existing) {
+ existing.vectorRank = i + 1;
+ existing.vectorScore = r.score;
+ } else {
+ scores.set(r.obsId, {
+ bm25Rank: Infinity,
+ vectorRank: i + 1,
+ sessionId: r.sessionId,
+ bm25Score: 0,
+ vectorScore: r.score,
+ });
+ }
+ });
+
+ const combined = Array.from(scores.entries()).map(([obsId, s]) => ({
+ obsId,
+ sessionId: s.sessionId,
+ bm25Score: s.bm25Score,
+ vectorScore: s.vectorScore,
+ combinedScore:
+ this.bm25Weight * (1 / (RRF_K + s.bm25Rank)) +
+ this.vectorWeight * (1 / (RRF_K + s.vectorRank)),
+ }));
+
+ combined.sort((a, b) => b.combinedScore - a.combinedScore);
+ return this.enrichResults(combined.slice(0, limit), limit);
+ }
+
+ private async enrichResults(
+ results: Array<{
+ obsId: string;
+ sessionId: string;
+ bm25Score: number;
+ vectorScore: number;
+ combinedScore: number;
+ }>,
+ limit: number,
+ ): Promise<HybridSearchResult[]> {
+ const enriched: HybridSearchResult[] = [];
+ for (const r of results.slice(0, limit)) {
+ const obs = await this.kv.get<CompressedObservation>(
+ KV.observations(r.sessionId),
+ r.obsId,
+ );
+ if (obs) {
+ enriched.push({ observation: obs, ...r });
+ }
+ }
+ return enriched;
+ }
+}
diff --git a/src/state/index-persistence.ts b/src/state/index-persistence.ts
new file mode 100644
index 00000000..728013b3
--- /dev/null
+++ b/src/state/index-persistence.ts
@@ -0,0 +1,63 @@
+import { SearchIndex } from "./search-index.js";
+import { VectorIndex } from "./vector-index.js";
+import type { StateKV } from "./kv.js";
+import { KV } from "./schema.js";
+
+const DEBOUNCE_MS = 5000;
+
+export class IndexPersistence {
+ private timer: ReturnType<typeof setTimeout> | null = null;
+
+ constructor(
+ private kv: StateKV,
+ private bm25: SearchIndex,
+ private vector: VectorIndex | null,
+ ) {}
+
+ scheduleSave(): void {
+ if (this.timer) clearTimeout(this.timer);
+ this.timer = setTimeout(() => this.save(), DEBOUNCE_MS);
+ }
+
+ async save(): Promise<void> {
+ if (this.timer) {
+ clearTimeout(this.timer);
+ this.timer = null;
+ }
+ await this.kv.set(KV.bm25Index, "data", this.bm25.serialize());
+ if (this.vector && this.vector.size > 0) {
+ await this.kv.set(KV.bm25Index, "vectors", this.vector.serialize());
+ }
+ }
+
+ async load(): Promise<{
+ bm25: SearchIndex | null;
+ vector: VectorIndex | null;
+ }> {
+ let bm25: SearchIndex | null = null;
+ let vector: VectorIndex | null = null;
+
+ const bm25Data = await this.kv
+ .get<string>(KV.bm25Index, "data")
+ .catch(() => null);
+ if (bm25Data && typeof bm25Data === "string") {
+ bm25 = SearchIndex.deserialize(bm25Data);
+ }
+
+ const vecData = await this.kv
+ .get<string>(KV.bm25Index, "vectors")
+ .catch(() => null);
+ if (vecData && typeof vecData === "string") {
+ vector = VectorIndex.deserialize(vecData);
+ }
+
+ return { bm25, vector };
+ }
+
+ stop(): void {
+ if (this.timer) {
+ clearTimeout(this.timer);
+ this.timer = null;
+ }
+ }
+}
diff --git a/src/state/schema.ts b/src/state/schema.ts
index 0fc51398..344739c9 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -6,6 +6,10 @@ export const KV = {
config: "mem:config",
metrics: "mem:metrics",
health: "mem:health",
+ embeddings: (obsId: string) => `mem:emb:${obsId}`,
+ bm25Index: "mem:index:bm25",
+ relations: "mem:relations",
+ profiles: "mem:profiles",
} as const;
export const STREAM = {
@@ -18,3 +22,15 @@ export function generateId(prefix: string): string {
const rand = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
return `${prefix}_${ts}_${rand}`;
}
+
+export function jaccardSimilarity(a: string, b: string): number {
+ const setA = new Set(a.split(/\s+/).filter((t) => t.length > 2));
+ const setB = new Set(b.split(/\s+/).filter((t) => t.length > 2));
+ if (setA.size === 0 && setB.size === 0) return 1;
+ if (setA.size === 0 || setB.size === 0) return 0;
+ let intersection = 0;
+ for (const word of setA) {
+ if (setB.has(word)) intersection++;
+ }
+ return intersection / (setA.size + setB.size - intersection);
+}
diff --git a/src/state/search-index.ts b/src/state/search-index.ts
index e667c16b..f9f08f82 100644
--- a/src/state/search-index.ts
+++ b/src/state/search-index.ts
@@ -25,7 +25,11 @@ export class SearchIndex {
termCount++;
}
- this.entries.set(obs.id, { obsId: obs.id, sessionId: obs.sessionId, termCount });
+ this.entries.set(obs.id, {
+ obsId: obs.id,
+ sessionId: obs.sessionId,
+ termCount,
+ });
this.docTermCounts.set(obs.id, termFreq);
this.totalDocLength += termCount;
@@ -64,7 +68,8 @@ export class SearchIndex {
const docLen = entry.termCount;
const numerator = tf * (this.k1 + 1);
- const denominator = tf + this.k1 * (1 - this.b + this.b * (docLen / avgDocLen));
+ const denominator =
+ tf + this.k1 * (1 - this.b + this.b * (docLen / avgDocLen));
const bm25Score = idf * (numerator / denominator);
scores.set(obsId, (scores.get(obsId) || 0) + bm25Score);
@@ -73,15 +78,20 @@ export class SearchIndex {
for (const [indexTerm, obsIds] of this.invertedIndex) {
if (indexTerm !== term && indexTerm.startsWith(term)) {
const prefixDf = obsIds.size;
- const prefixIdf = Math.log((N - prefixDf + 0.5) / (prefixDf + 0.5) + 1) * 0.5;
+ const prefixIdf =
+ Math.log((N - prefixDf + 0.5) / (prefixDf + 0.5) + 1) * 0.5;
for (const obsId of obsIds) {
const entry = this.entries.get(obsId)!;
const docTerms = this.docTermCounts.get(obsId);
const tf = docTerms?.get(indexTerm) || 0;
const docLen = entry.termCount;
const numerator = tf * (this.k1 + 1);
- const denominator = tf + this.k1 * (1 - this.b + this.b * (docLen / avgDocLen));
- scores.set(obsId, (scores.get(obsId) || 0) + prefixIdf * (numerator / denominator));
+ const denominator =
+ tf + this.k1 * (1 - this.b + this.b * (docLen / avgDocLen));
+ scores.set(
+ obsId,
+ (scores.get(obsId) || 0) + prefixIdf * (numerator / denominator),
+ );
}
}
}
@@ -107,6 +117,39 @@ export class SearchIndex {
this.totalDocLength = 0;
}
+ serialize(): string {
+ const entries = Array.from(this.entries.entries());
+ const inverted = Array.from(this.invertedIndex.entries()).map(
+ ([term, ids]) => [term, Array.from(ids)] as [string, string[]],
+ );
+ const docTerms = Array.from(this.docTermCounts.entries()).map(
+ ([id, counts]) =>
+ [id, Array.from(counts.entries())] as [string, [string, number][]],
+ );
+ return JSON.stringify({
+ entries,
+ inverted,
+ docTerms,
+ totalDocLength: this.totalDocLength,
+ });
+ }
+
+ static deserialize(json: string): SearchIndex {
+ const idx = new SearchIndex();
+ const data = JSON.parse(json);
+ for (const [key, val] of data.entries) {
+ idx.entries.set(key, val);
+ }
+ for (const [term, ids] of data.inverted) {
+ idx.invertedIndex.set(term, new Set(ids));
+ }
+ for (const [id, counts] of data.docTerms) {
+ idx.docTermCounts.set(id, new Map(counts));
+ }
+ idx.totalDocLength = data.totalDocLength;
+ return idx;
+ }
+
private extractTerms(obs: CompressedObservation): string[] {
const parts = [
obs.title,
diff --git a/src/state/vector-index.ts b/src/state/vector-index.ts
new file mode 100644
index 00000000..1bd07873
--- /dev/null
+++ b/src/state/vector-index.ts
@@ -0,0 +1,93 @@
+function float32ToBase64(arr: Float32Array): string {
+ return Buffer.from(arr.buffer).toString("base64");
+}
+
+function base64ToFloat32(b64: string): Float32Array {
+ return new Float32Array(Buffer.from(b64, "base64").buffer);
+}
+
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+ if (a.length !== b.length) return 0;
+ let dot = 0;
+ let normA = 0;
+ let normB = 0;
+ for (let i = 0; i < a.length; i++) {
+ dot += a[i] * b[i];
+ normA += a[i] * a[i];
+ normB += b[i] * b[i];
+ }
+ const denom = Math.sqrt(normA) * Math.sqrt(normB);
+ return denom === 0 ? 0 : dot / denom;
+}
+
+export class VectorIndex {
+ private vectors: Map<
+ string,
+ { embedding: Float32Array; sessionId: string }
+ > = new Map();
+
+ add(obsId: string, sessionId: string, embedding: Float32Array): void {
+ this.vectors.set(obsId, { embedding, sessionId });
+ }
+
+ remove(obsId: string): void {
+ this.vectors.delete(obsId);
+ }
+
+ search(
+ query: Float32Array,
+ limit = 20,
+ ): Array<{ obsId: string; sessionId: string; score: number }> {
+ const results: Array<{
+ obsId: string;
+ sessionId: string;
+ score: number;
+ }> = [];
+
+ for (const [obsId, entry] of this.vectors) {
+ const score = cosineSimilarity(query, entry.embedding);
+ results.push({ obsId, sessionId: entry.sessionId, score });
+ }
+
+ results.sort((a, b) => b.score - a.score);
+ return results.slice(0, limit);
+ }
+
+ get size(): number {
+ return this.vectors.size;
+ }
+
+ clear(): void {
+ this.vectors.clear();
+ }
+
+ serialize(): string {
+ const data: Array<
+ [string, { embedding: string; sessionId: string }]
+ > = [];
+ for (const [obsId, entry] of this.vectors) {
+ data.push([
+ obsId,
+ {
+ embedding: float32ToBase64(entry.embedding),
+ sessionId: entry.sessionId,
+ },
+ ]);
+ }
+ return JSON.stringify(data);
+ }
+
+ static deserialize(json: string): VectorIndex {
+ const idx = new VectorIndex();
+ const data: Array<
+ [string, { embedding: string; sessionId: string }]
+ > = JSON.parse(json);
+ for (const [obsId, entry] of data) {
+ idx.vectors.set(obsId, {
+ embedding: base64ToFloat32(entry.embedding),
+ sessionId: entry.sessionId,
+ });
+ }
+ return idx;
+ }
+}
diff --git a/src/telemetry/setup.ts b/src/telemetry/setup.ts
index 36eafdd5..e88dbfb2 100644
--- a/src/telemetry/setup.ts
+++ b/src/telemetry/setup.ts
@@ -6,7 +6,7 @@ interface OtelConfig {
export const OTEL_CONFIG: OtelConfig = {
serviceName: "agentmemory",
- serviceVersion: "0.2.0",
+ serviceVersion: "0.3.0",
metricsExportIntervalMs: 30_000,
};
@@ -25,6 +25,11 @@ interface Counters {
dedupSkipped: Counter;
evictionTotal: Counter;
circuitBreakerOpen: Counter;
+ embeddingSuccess: Counter;
+ embeddingFailure: Counter;
+ vectorSearchTotal: Counter;
+ autoForgetTotal: Counter;
+ profileGenerated: Counter;
}
interface Histograms {
@@ -32,6 +37,8 @@ interface Histograms {
searchLatency: Histogram;
contextTokens: Histogram;
qualityScore: Histogram;
+ embeddingLatency: Histogram;
+ vectorSearchLatency: Histogram;
}
type Meter = {
@@ -53,6 +60,11 @@ const COUNTER_NAMES: Array<[keyof Counters, string]> = [
["dedupSkipped", "dedup.skipped"],
["evictionTotal", "eviction.total"],
["circuitBreakerOpen", "circuit_breaker.open"],
+ ["embeddingSuccess", "embedding.success"],
+ ["embeddingFailure", "embedding.failure"],
+ ["vectorSearchTotal", "vector_search.total"],
+ ["autoForgetTotal", "auto_forget.total"],
+ ["profileGenerated", "profile.generated"],
];
const HISTOGRAM_NAMES: Array<[keyof Histograms, string]> = [
@@ -60,6 +72,8 @@ const HISTOGRAM_NAMES: Array<[keyof Histograms, string]> = [
["searchLatency", "search.latency_ms"],
["contextTokens", "context.tokens"],
["qualityScore", "quality.score"],
+ ["embeddingLatency", "embedding.latency_ms"],
+ ["vectorSearchLatency", "vector_search.latency_ms"],
];
export function initMetrics(getMeter?: (name: string) => Meter): {
@@ -73,14 +87,14 @@ export function initMetrics(getMeter?: (name: string) => Meter): {
key,
meter ? meter.createCounter(name) : NOOP_COUNTER,
]),
- ) as Counters;
+ ) as unknown as Counters;
histograms = Object.fromEntries(
HISTOGRAM_NAMES.map(([key, name]) => [
key,
meter ? meter.createHistogram(name) : NOOP_HISTOGRAM,
]),
- ) as Histograms;
+ ) as unknown as Histograms;
return { counters, histograms };
}
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 9afdb5cf..234f2cd1 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -51,7 +51,7 @@ export function registerApiTriggers(
body: {
status,
service: "agentmemory",
- version: "0.2.0",
+ version: "0.3.0",
health: health || null,
functionMetrics,
circuitBreaker,
@@ -366,6 +366,173 @@ export function registerApiTriggers(
config: { api_path: "/agentmemory/evict", http_method: "POST" },
});
+ sdk.registerFunction(
+ { id: "api::smart-search" },
+ async (
+ req: ApiRequest<{ query?: string; expandIds?: string[]; limit?: number }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ const result = await sdk.trigger("mem::smart-search", req.body);
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::smart-search",
+ config: { api_path: "/agentmemory/smart-search", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::timeline" },
+ async (
+ req: ApiRequest<{
+ anchor: string;
+ project?: string;
+ before?: number;
+ after?: number;
+ }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.anchor) {
+ return { status_code: 400, body: { error: "anchor is required" } };
+ }
+ const result = await sdk.trigger("mem::timeline", req.body);
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::timeline",
+ config: { api_path: "/agentmemory/timeline", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::profile" },
+ async (req: ApiRequest): Promise<Response> => {
+ const project = req.query_params["project"] as string;
+ if (!project) {
+ return {
+ status_code: 400,
+ body: { error: "project query param is required" },
+ };
+ }
+ const result = await sdk.trigger("mem::profile", { project });
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::profile",
+ config: { api_path: "/agentmemory/profile", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::export" },
+ async (req: ApiRequest): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ const result = await sdk.trigger("mem::export", {});
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::export",
+ config: { api_path: "/agentmemory/export", http_method: "GET" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::import" },
+ async (
+ req: ApiRequest<{
+ exportData: unknown;
+ strategy?: "merge" | "replace" | "skip";
+ }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.exportData) {
+ return { status_code: 400, body: { error: "exportData is required" } };
+ }
+ const result = await sdk.trigger("mem::import", req.body);
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::import",
+ config: { api_path: "/agentmemory/import", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::relations" },
+ async (
+ req: ApiRequest<{ sourceId: string; targetId: string; type: string }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.sourceId || !req.body?.targetId || !req.body?.type) {
+ return {
+ status_code: 400,
+ body: { error: "sourceId, targetId, and type are required" },
+ };
+ }
+ const result = await sdk.trigger("mem::relate", req.body);
+ return { status_code: 201, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::relations",
+ config: { api_path: "/agentmemory/relations", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::evolve" },
+ async (
+ req: ApiRequest<{
+ memoryId: string;
+ newContent: string;
+ newTitle?: string;
+ }>,
+ ): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ if (!req.body?.memoryId || !req.body?.newContent) {
+ return {
+ status_code: 400,
+ body: { error: "memoryId and newContent are required" },
+ };
+ }
+ const result = await sdk.trigger("mem::evolve", req.body);
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::evolve",
+ config: { api_path: "/agentmemory/evolve", http_method: "POST" },
+ });
+
+ sdk.registerFunction(
+ { id: "api::auto-forget" },
+ async (req: ApiRequest<{ dryRun?: boolean }>): Promise<Response> => {
+ const authErr = checkAuth(req, secret);
+ if (authErr) return authErr;
+ const dryRun =
+ req.query_params?.["dryRun"] === "true" || req.body?.dryRun === true;
+ const result = await sdk.trigger("mem::auto-forget", { dryRun });
+ return { status_code: 200, body: result };
+ },
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::auto-forget",
+ config: { api_path: "/agentmemory/auto-forget", http_method: "POST" },
+ });
+
sdk.registerFunction({ id: "api::viewer" }, async (): Promise<Response> => {
const headers = {
"Content-Type": "text/html",
diff --git a/src/types.ts b/src/types.ts
index de0be266..ca7402d2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -64,6 +64,12 @@ export interface Memory {
files: string[];
sessionIds: string[];
strength: number;
+ version: number;
+ parentId?: string;
+ supersedes?: string[];
+ relatedIds?: string[];
+ isLatest: boolean;
+ forgetAfter?: string;
}
export interface SessionSummary {
@@ -178,3 +184,73 @@ export interface CircuitBreakerState {
lastFailureAt: number | null;
openedAt: number | null;
}
+
+export interface EmbeddingProvider {
+ name: string;
+ dimensions: number;
+ embed(text: string): Promise<Float32Array>;
+ embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+
+export interface MemoryRelation {
+ type: "supersedes" | "extends" | "derives" | "contradicts" | "related";
+ sourceId: string;
+ targetId: string;
+ createdAt: string;
+}
+
+export interface HybridSearchResult {
+ observation: CompressedObservation;
+ bm25Score: number;
+ vectorScore: number;
+ combinedScore: number;
+ sessionId: string;
+}
+
+export interface CompactSearchResult {
+ obsId: string;
+ sessionId: string;
+ title: string;
+ type: ObservationType;
+ score: number;
+ timestamp: string;
+}
+
+export interface TimelineEntry {
+ observation: CompressedObservation;
+ sessionId: string;
+ relativePosition: number;
+}
+
+export interface ProjectProfile {
+ project: string;
+ updatedAt: string;
+ topConcepts: Array<{ concept: string; frequency: number }>;
+ topFiles: Array<{ file: string; frequency: number }>;
+ conventions: string[];
+ commonErrors: string[];
+ recentActivity: string[];
+ sessionCount: number;
+ totalObservations: number;
+ summary?: string;
+}
+
+export interface ExportData {
+ version: "0.3.0";
+ exportedAt: string;
+ sessions: Session[];
+ observations: Record<string, CompressedObservation[]>;
+ memories: Memory[];
+ summaries: SessionSummary[];
+ profiles?: ProjectProfile[];
+}
+
+export interface EmbeddingConfig {
+ provider?: string;
+ bm25Weight: number;
+ vectorWeight: number;
+}
+
+export interface FallbackConfig {
+ providers: ProviderType[];
+}
diff --git a/src/xenova.d.ts b/src/xenova.d.ts
new file mode 100644
index 00000000..7abd4b09
--- /dev/null
+++ b/src/xenova.d.ts
@@ -0,0 +1,3 @@
+declare module "@xenova/transformers" {
+ export function pipeline(task: string, model: string): Promise<any>;
+}
diff --git a/test/auto-forget.test.ts b/test/auto-forget.test.ts
new file mode 100644
index 00000000..d284cc5a
--- /dev/null
+++ b/test/auto-forget.test.ts
@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerAutoForgetFunction } from "../src/functions/auto-forget.js";
+import type { Memory, CompressedObservation, Session } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+function makeMemory(overrides: Partial<Memory> = {}): Memory {
+ return {
+ id: "mem_1",
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ type: "pattern",
+ title: "Test memory",
+ content: "This is a test memory with enough words for comparison",
+ concepts: ["test"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ ...overrides,
+ };
+}
+
+describe("Auto-Forget Function", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerAutoForgetFunction(sdk as never, kv as never);
+ });
+
+ it("detects and deletes TTL-expired memories", async () => {
+ const expired = makeMemory({
+ id: "mem_expired",
+ forgetAfter: "2020-01-01T00:00:00Z",
+ });
+ await kv.set("mem:memories", "mem_expired", expired);
+
+ const result = (await sdk.trigger("mem::auto-forget", {})) as {
+ ttlExpired: string[];
+ };
+
+ expect(result.ttlExpired).toContain("mem_expired");
+ const deleted = await kv.get("mem:memories", "mem_expired");
+ expect(deleted).toBeNull();
+ });
+
+ it("detects contradiction between very similar memories", async () => {
+ const mem1 = makeMemory({
+ id: "mem_1",
+ content: "Use React hooks for state management in all components",
+ createdAt: "2026-01-01T00:00:00Z",
+ });
+ const mem2 = makeMemory({
+ id: "mem_2",
+ content: "Use React hooks for state management in all components",
+ createdAt: "2026-02-01T00:00:00Z",
+ });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ const result = (await sdk.trigger("mem::auto-forget", {})) as {
+ contradictions: Array<{
+ memoryA: string;
+ memoryB: string;
+ similarity: number;
+ }>;
+ };
+
+ expect(result.contradictions.length).toBe(1);
+ const older = await kv.get<Memory>("mem:memories", "mem_1");
+ expect(older!.isLatest).toBe(false);
+ });
+
+ it("evicts low-value old observations", async () => {
+ const session: Session = {
+ id: "ses_1",
+ project: "my-project",
+ cwd: "/tmp",
+ startedAt: "2025-01-01T00:00:00Z",
+ status: "completed",
+ observationCount: 1,
+ };
+ await kv.set("mem:sessions", "ses_1", session);
+
+ const oldLowObs: CompressedObservation = {
+ id: "obs_old",
+ sessionId: "ses_1",
+ timestamp: "2025-01-01T00:00:00Z",
+ type: "other",
+ title: "trivial event",
+ facts: [],
+ narrative: "nothing important",
+ concepts: [],
+ files: [],
+ importance: 1,
+ };
+ await kv.set("mem:obs:ses_1", "obs_old", oldLowObs);
+
+ const result = (await sdk.trigger("mem::auto-forget", {})) as {
+ lowValueObs: string[];
+ };
+
+ expect(result.lowValueObs).toContain("obs_old");
+ });
+
+ it("dryRun mode identifies but does not delete anything", async () => {
+ const expired = makeMemory({
+ id: "mem_expired",
+ forgetAfter: "2020-01-01T00:00:00Z",
+ });
+ await kv.set("mem:memories", "mem_expired", expired);
+
+ const result = (await sdk.trigger("mem::auto-forget", { dryRun: true })) as {
+ ttlExpired: string[];
+ dryRun: boolean;
+ };
+
+ expect(result.dryRun).toBe(true);
+ expect(result.ttlExpired).toContain("mem_expired");
+
+ const stillExists = await kv.get("mem:memories", "mem_expired");
+ expect(stillExists).not.toBeNull();
+ });
+
+ it("does not flag non-similar memories as contradictions", async () => {
+ const mem1 = makeMemory({
+ id: "mem_1",
+ content: "We use TypeScript with strict mode enabled for all backend services",
+ });
+ const mem2 = makeMemory({
+ id: "mem_2",
+ content: "The deployment pipeline runs integration tests before merging to main",
+ });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ const result = (await sdk.trigger("mem::auto-forget", {})) as {
+ contradictions: unknown[];
+ };
+
+ expect(result.contradictions.length).toBe(0);
+ });
+});
diff --git a/test/embedding-provider.test.ts b/test/embedding-provider.test.ts
new file mode 100644
index 00000000..05d01bd2
--- /dev/null
+++ b/test/embedding-provider.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createEmbeddingProvider } from "../src/providers/embedding/index.js";
+import { GeminiEmbeddingProvider } from "../src/providers/embedding/gemini.js";
+import { OpenAIEmbeddingProvider } from "../src/providers/embedding/openai.js";
+
+describe("createEmbeddingProvider", () => {
+ const originalEnv = { ...process.env };
+
+ beforeEach(() => {
+ process.env = { ...originalEnv };
+ delete process.env["GEMINI_API_KEY"];
+ delete process.env["OPENAI_API_KEY"];
+ delete process.env["VOYAGE_API_KEY"];
+ delete process.env["COHERE_API_KEY"];
+ delete process.env["OPENROUTER_API_KEY"];
+ delete process.env["EMBEDDING_PROVIDER"];
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it("returns null when no API keys are set", () => {
+ const provider = createEmbeddingProvider();
+ expect(provider).toBeNull();
+ });
+
+ it("returns GeminiEmbeddingProvider when GEMINI_API_KEY is set", () => {
+ process.env["GEMINI_API_KEY"] = "test-key-123";
+ const provider = createEmbeddingProvider();
+ expect(provider).toBeInstanceOf(GeminiEmbeddingProvider);
+ expect(provider!.name).toBe("gemini");
+ });
+
+ it("returns OpenAIEmbeddingProvider when OPENAI_API_KEY is set", () => {
+ process.env["OPENAI_API_KEY"] = "test-key-456";
+ const provider = createEmbeddingProvider();
+ expect(provider).toBeInstanceOf(OpenAIEmbeddingProvider);
+ expect(provider!.name).toBe("openai");
+ });
+
+ it("EMBEDDING_PROVIDER override takes precedence", () => {
+ process.env["GEMINI_API_KEY"] = "test-key-123";
+ process.env["OPENAI_API_KEY"] = "test-key-456";
+ process.env["EMBEDDING_PROVIDER"] = "openai";
+ const provider = createEmbeddingProvider();
+ expect(provider).toBeInstanceOf(OpenAIEmbeddingProvider);
+ });
+});
diff --git a/test/export-import.test.ts b/test/export-import.test.ts
new file mode 100644
index 00000000..4fb2a41c
--- /dev/null
+++ b/test/export-import.test.ts
@@ -0,0 +1,247 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import type {
+ Session,
+ CompressedObservation,
+ Memory,
+ SessionSummary,
+ ExportData,
+} from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+const testSession: Session = {
+ id: "ses_1",
+ project: "my-project",
+ cwd: "/tmp",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "completed",
+ observationCount: 1,
+};
+
+const testObs: CompressedObservation = {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T10:00:00Z",
+ type: "file_edit",
+ title: "Edit auth",
+ facts: ["Added check"],
+ narrative: "Auth changes",
+ concepts: ["auth"],
+ files: ["src/auth.ts"],
+ importance: 7,
+};
+
+const testMemory: Memory = {
+ id: "mem_1",
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type: "pattern",
+ title: "Auth pattern",
+ content: "Always validate tokens",
+ concepts: ["auth"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+};
+
+const testSummary: SessionSummary = {
+ sessionId: "ses_1",
+ project: "my-project",
+ createdAt: "2026-02-01T00:00:00Z",
+ title: "Auth work",
+ narrative: "Worked on auth",
+ keyDecisions: ["Use JWT"],
+ filesModified: ["src/auth.ts"],
+ concepts: ["auth"],
+ observationCount: 1,
+};
+
+describe("Export/Import Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+
+ await kv.set("mem:sessions", "ses_1", testSession);
+ await kv.set("mem:obs:ses_1", "obs_1", testObs);
+ await kv.set("mem:memories", "mem_1", testMemory);
+ await kv.set("mem:summaries", "ses_1", testSummary);
+ });
+
+ it("export produces valid ExportData structure", async () => {
+ const result = (await sdk.trigger("mem::export", {})) as ExportData;
+
+ expect(result.version).toBe("0.3.0");
+ expect(result.exportedAt).toBeDefined();
+ expect(result.sessions.length).toBe(1);
+ expect(result.sessions[0].id).toBe("ses_1");
+ expect(result.observations["ses_1"].length).toBe(1);
+ expect(result.memories.length).toBe(1);
+ expect(result.summaries.length).toBe(1);
+ });
+
+ it("import with merge strategy adds data", async () => {
+ const exportData: ExportData = {
+ version: "0.3.0",
+ exportedAt: new Date().toISOString(),
+ sessions: [
+ { ...testSession, id: "ses_2", observationCount: 0 },
+ ],
+ observations: {},
+ memories: [
+ { ...testMemory, id: "mem_2", title: "New pattern" },
+ ],
+ summaries: [],
+ };
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData,
+ strategy: "merge",
+ })) as { success: boolean; sessions: number; memories: number };
+
+ expect(result.success).toBe(true);
+ expect(result.sessions).toBe(1);
+ expect(result.memories).toBe(1);
+
+ const allSessions = await kv.list("mem:sessions");
+ expect(allSessions.length).toBe(2);
+ });
+
+ it("import with skip strategy does not overwrite existing", async () => {
+ const exportData: ExportData = {
+ version: "0.3.0",
+ exportedAt: new Date().toISOString(),
+ sessions: [testSession],
+ observations: { ses_1: [testObs] },
+ memories: [testMemory],
+ summaries: [testSummary],
+ };
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData,
+ strategy: "skip",
+ })) as { success: boolean; skipped: number; sessions: number };
+
+ expect(result.success).toBe(true);
+ expect(result.skipped).toBeGreaterThan(0);
+ expect(result.sessions).toBe(0);
+ });
+
+ it("import with replace strategy clears existing data first", async () => {
+ const newSession: Session = {
+ id: "ses_new",
+ project: "new-project",
+ cwd: "/tmp/new",
+ startedAt: "2026-03-01T00:00:00Z",
+ status: "active",
+ observationCount: 0,
+ };
+ const exportData: ExportData = {
+ version: "0.3.0",
+ exportedAt: new Date().toISOString(),
+ sessions: [newSession],
+ observations: {},
+ memories: [],
+ summaries: [],
+ };
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData,
+ strategy: "replace",
+ })) as { success: boolean; sessions: number };
+
+ expect(result.success).toBe(true);
+ expect(result.sessions).toBe(1);
+
+ const oldSession = await kv.get("mem:sessions", "ses_1");
+ expect(oldSession).toBeNull();
+ });
+
+ it("export then import round-trip preserves data", async () => {
+ const exported = (await sdk.trigger("mem::export", {})) as ExportData;
+
+ const freshKv = mockKV();
+ const freshSdk = mockSdk();
+ registerExportImportFunction(freshSdk as never, freshKv as never);
+
+ const importResult = (await freshSdk.trigger("mem::import", {
+ exportData: exported,
+ strategy: "merge",
+ })) as { success: boolean; sessions: number; observations: number; memories: number };
+
+ expect(importResult.success).toBe(true);
+ expect(importResult.sessions).toBe(1);
+ expect(importResult.observations).toBe(1);
+ expect(importResult.memories).toBe(1);
+
+ const reExported = (await freshSdk.trigger("mem::export", {})) as ExportData;
+ expect(reExported.sessions.length).toBe(exported.sessions.length);
+ expect(reExported.memories.length).toBe(exported.memories.length);
+ });
+
+ it("import rejects unsupported version", async () => {
+ const exportData = {
+ version: "1.0.0",
+ exportedAt: new Date().toISOString(),
+ sessions: [],
+ observations: {},
+ memories: [],
+ summaries: [],
+ } as unknown as ExportData;
+
+ const result = (await sdk.trigger("mem::import", {
+ exportData,
+ strategy: "merge",
+ })) as { success: boolean; error: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("Unsupported export version");
+ });
+});
diff --git a/test/fallback-chain.test.ts b/test/fallback-chain.test.ts
new file mode 100644
index 00000000..5113b699
--- /dev/null
+++ b/test/fallback-chain.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { FallbackChainProvider } from "../src/providers/fallback-chain.js";
+import type { MemoryProvider } from "../src/types.js";
+
+function makeProvider(
+ name: string,
+ impl?: Partial<MemoryProvider>,
+): MemoryProvider {
+ return {
+ name,
+ compress: impl?.compress ?? (async () => `compressed by ${name}`),
+ summarize: impl?.summarize ?? (async () => `summarized by ${name}`),
+ };
+}
+
+describe("FallbackChainProvider", () => {
+ it("returns result from first provider when it succeeds", async () => {
+ const chain = new FallbackChainProvider([
+ makeProvider("primary"),
+ makeProvider("secondary"),
+ ]);
+ const result = await chain.compress("sys", "user");
+ expect(result).toBe("compressed by primary");
+ });
+
+ it("falls back to second provider when first fails", async () => {
+ const failing: MemoryProvider = {
+ name: "failing",
+ compress: async () => {
+ throw new Error("primary down");
+ },
+ summarize: async () => {
+ throw new Error("primary down");
+ },
+ };
+ const chain = new FallbackChainProvider([
+ failing,
+ makeProvider("backup"),
+ ]);
+ const result = await chain.compress("sys", "user");
+ expect(result).toBe("compressed by backup");
+ });
+
+ it("throws the last error when all providers fail", async () => {
+ const failing1: MemoryProvider = {
+ name: "fail1",
+ compress: async () => {
+ throw new Error("fail1 error");
+ },
+ summarize: async () => {
+ throw new Error("fail1 error");
+ },
+ };
+ const failing2: MemoryProvider = {
+ name: "fail2",
+ compress: async () => {
+ throw new Error("fail2 error");
+ },
+ summarize: async () => {
+ throw new Error("fail2 error");
+ },
+ };
+ const chain = new FallbackChainProvider([failing1, failing2]);
+ await expect(chain.compress("sys", "user")).rejects.toThrow("fail2 error");
+ });
+
+ it("formats the name correctly", () => {
+ const chain = new FallbackChainProvider([
+ makeProvider("anthropic"),
+ makeProvider("gemini"),
+ makeProvider("openrouter"),
+ ]);
+ expect(chain.name).toBe("fallback(anthropic -> gemini -> openrouter)");
+ });
+
+ it("summarize also uses fallback chain", async () => {
+ const failing: MemoryProvider = {
+ name: "failing",
+ compress: async () => {
+ throw new Error("down");
+ },
+ summarize: async () => {
+ throw new Error("down");
+ },
+ };
+ const chain = new FallbackChainProvider([
+ failing,
+ makeProvider("backup"),
+ ]);
+ const result = await chain.summarize("sys", "user");
+ expect(result).toBe("summarized by backup");
+ });
+});
diff --git a/test/hybrid-search.test.ts b/test/hybrid-search.test.ts
new file mode 100644
index 00000000..0f204200
--- /dev/null
+++ b/test/hybrid-search.test.ts
@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { HybridSearch } from "../src/state/hybrid-search.js";
+import { SearchIndex } from "../src/state/search-index.js";
+import type { CompressedObservation, EmbeddingProvider } from "../src/types.js";
+
+function makeObs(
+ overrides: Partial<CompressedObservation> = {},
+): CompressedObservation {
+ return {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: new Date().toISOString(),
+ type: "file_edit",
+ title: "Edit auth middleware",
+ subtitle: "JWT validation",
+ facts: ["Added token check"],
+ narrative: "Modified the auth middleware to validate JWT tokens",
+ concepts: ["authentication", "jwt"],
+ files: ["src/middleware/auth.ts"],
+ importance: 7,
+ ...overrides,
+ };
+}
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+describe("HybridSearch", () => {
+ let bm25: SearchIndex;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ bm25 = new SearchIndex();
+ kv = mockKV();
+ });
+
+ it("returns BM25-only results when no vector index is provided", async () => {
+ const obs = makeObs({ id: "obs_1", sessionId: "ses_1" });
+ bm25.add(obs);
+ await kv.set("mem:obs:ses_1", "obs_1", obs);
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("auth");
+
+ expect(results.length).toBe(1);
+ expect(results[0].observation.id).toBe("obs_1");
+ expect(results[0].vectorScore).toBe(0);
+ expect(results[0].bm25Score).toBeGreaterThan(0);
+ });
+
+ it("returns empty results for no-match query", async () => {
+ const obs = makeObs({ id: "obs_1", sessionId: "ses_1" });
+ bm25.add(obs);
+ await kv.set("mem:obs:ses_1", "obs_1", obs);
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("database");
+ expect(results).toEqual([]);
+ });
+
+ it("combinedScore equals bm25Score when no vector index", async () => {
+ const obs = makeObs({ id: "obs_1", sessionId: "ses_1" });
+ bm25.add(obs);
+ await kv.set("mem:obs:ses_1", "obs_1", obs);
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("auth");
+
+ expect(results[0].combinedScore).toBe(results[0].bm25Score);
+ });
+
+ it("results are sorted by combinedScore descending", async () => {
+ const obs1 = makeObs({
+ id: "obs_1",
+ sessionId: "ses_1",
+ title: "auth handler",
+ narrative: "auth auth auth module",
+ concepts: ["auth"],
+ });
+ const obs2 = makeObs({
+ id: "obs_2",
+ sessionId: "ses_1",
+ title: "database setup",
+ narrative: "auth connection config",
+ concepts: ["database"],
+ });
+ bm25.add(obs1);
+ bm25.add(obs2);
+ await kv.set("mem:obs:ses_1", "obs_1", obs1);
+ await kv.set("mem:obs:ses_1", "obs_2", obs2);
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("auth");
+
+ expect(results.length).toBe(2);
+ expect(results[0].combinedScore).toBeGreaterThanOrEqual(
+ results[1].combinedScore,
+ );
+ });
+
+ it("respects limit parameter", async () => {
+ for (let i = 0; i < 10; i++) {
+ const obs = makeObs({
+ id: `obs_${i}`,
+ sessionId: "ses_1",
+ title: `auth feature ${i}`,
+ });
+ bm25.add(obs);
+ await kv.set("mem:obs:ses_1", `obs_${i}`, obs);
+ }
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("auth", 3);
+ expect(results.length).toBe(3);
+ });
+
+ it("skips observations not found in KV", async () => {
+ const obs = makeObs({ id: "obs_missing", sessionId: "ses_1" });
+ bm25.add(obs);
+
+ const hybrid = new HybridSearch(bm25, null, null, kv as never);
+ const results = await hybrid.search("auth");
+ expect(results).toEqual([]);
+ });
+});
diff --git a/test/index-persistence.test.ts b/test/index-persistence.test.ts
new file mode 100644
index 00000000..7452ec09
--- /dev/null
+++ b/test/index-persistence.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { IndexPersistence } from "../src/state/index-persistence.js";
+import { SearchIndex } from "../src/state/search-index.js";
+import { VectorIndex } from "../src/state/vector-index.js";
+import type { CompressedObservation } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function makeObs(
+ overrides: Partial<CompressedObservation> = {},
+): CompressedObservation {
+ return {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: new Date().toISOString(),
+ type: "file_edit",
+ title: "Edit auth middleware",
+ subtitle: "JWT validation",
+ facts: ["Added token check"],
+ narrative: "Modified the auth middleware to validate JWT tokens",
+ concepts: ["authentication", "jwt"],
+ files: ["src/middleware/auth.ts"],
+ importance: 7,
+ ...overrides,
+ };
+}
+
+describe("IndexPersistence", () => {
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ kv = mockKV();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("saves and loads BM25 index round-trip", async () => {
+ const bm25 = new SearchIndex();
+ bm25.add(makeObs({ id: "obs_1", title: "auth handler" }));
+
+ const persistence = new IndexPersistence(kv as never, bm25, null);
+ await persistence.save();
+
+ const loaded = await persistence.load();
+ expect(loaded.bm25).not.toBeNull();
+ expect(loaded.bm25!.size).toBe(1);
+ const results = loaded.bm25!.search("auth");
+ expect(results.length).toBe(1);
+ });
+
+ it("saves and loads vector index round-trip", async () => {
+ const bm25 = new SearchIndex();
+ const vector = new VectorIndex();
+ vector.add("obs_1", "ses_1", new Float32Array([0.1, 0.2, 0.3]));
+
+ const persistence = new IndexPersistence(kv as never, bm25, vector);
+ await persistence.save();
+
+ const loaded = await persistence.load();
+ expect(loaded.vector).not.toBeNull();
+ expect(loaded.vector!.size).toBe(1);
+ });
+
+ it("scheduleSave debounces multiple calls", async () => {
+ const bm25 = new SearchIndex();
+ const persistence = new IndexPersistence(kv as never, bm25, null);
+
+ persistence.scheduleSave();
+ persistence.scheduleSave();
+ persistence.scheduleSave();
+
+ await expect(kv.get("mem:index:bm25", "data")).resolves.toBeNull();
+
+ vi.advanceTimersByTime(5000);
+ await vi.runAllTimersAsync();
+
+ const saved = await kv.get<string>("mem:index:bm25", "data");
+ expect(saved).not.toBeNull();
+ });
+
+ it("stop clears the pending timer", async () => {
+ const bm25 = new SearchIndex();
+ bm25.add(makeObs({ id: "obs_1", title: "auth handler" }));
+ const persistence = new IndexPersistence(kv as never, bm25, null);
+
+ persistence.scheduleSave();
+ persistence.stop();
+
+ vi.advanceTimersByTime(10000);
+ const saved = await kv.get<string>("mem:index:bm25", "data");
+ expect(saved).toBeNull();
+ });
+
+ it("returns null indexes when nothing has been saved", async () => {
+ const bm25 = new SearchIndex();
+ const persistence = new IndexPersistence(kv as never, bm25, null);
+
+ const loaded = await persistence.load();
+ expect(loaded.bm25).toBeNull();
+ expect(loaded.vector).toBeNull();
+ });
+});
diff --git a/test/profile.test.ts b/test/profile.test.ts
new file mode 100644
index 00000000..b104e344
--- /dev/null
+++ b/test/profile.test.ts
@@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerProfileFunction } from "../src/functions/profile.js";
+import type {
+ CompressedObservation,
+ Session,
+ ProjectProfile,
+} from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+describe("Profile Function", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerProfileFunction(sdk as never, kv as never);
+
+ const session: Session = {
+ id: "ses_1",
+ project: "my-project",
+ cwd: "/tmp/my-project",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "completed",
+ observationCount: 3,
+ };
+ await kv.set("mem:sessions", "ses_1", session);
+
+ const obs1: CompressedObservation = {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T10:00:00Z",
+ type: "file_edit",
+ title: "Edit auth module",
+ facts: [],
+ narrative: "Auth changes",
+ concepts: ["typescript", "authentication"],
+ files: ["/project/src/auth.ts", "/project/src/middleware.ts"],
+ importance: 8,
+ };
+ const obs2: CompressedObservation = {
+ id: "obs_2",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T11:00:00Z",
+ type: "file_edit",
+ title: "Update database",
+ facts: [],
+ narrative: "DB changes",
+ concepts: ["typescript", "database"],
+ files: ["/project/src/db.ts"],
+ importance: 6,
+ };
+ const obs3: CompressedObservation = {
+ id: "obs_3",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T12:00:00Z",
+ type: "error",
+ title: "Connection timeout",
+ facts: [],
+ narrative: "Error occurred",
+ concepts: ["error"],
+ files: ["/project/src/db.ts"],
+ importance: 4,
+ };
+
+ await kv.set("mem:obs:ses_1", "obs_1", obs1);
+ await kv.set("mem:obs:ses_1", "obs_2", obs2);
+ await kv.set("mem:obs:ses_1", "obs_3", obs3);
+ });
+
+ it("generates profile with topConcepts sorted by frequency", async () => {
+ const result = (await sdk.trigger("mem::profile", {
+ project: "my-project",
+ })) as { profile: ProjectProfile; cached: boolean };
+
+ expect(result.cached).toBe(false);
+ expect(result.profile.topConcepts[0].concept).toBe("typescript");
+ expect(result.profile.topConcepts[0].frequency).toBe(2);
+ });
+
+ it("generates profile with topFiles sorted by frequency", async () => {
+ const result = (await sdk.trigger("mem::profile", {
+ project: "my-project",
+ })) as { profile: ProjectProfile };
+
+ expect(result.profile.topFiles[0].file).toBe("/project/src/db.ts");
+ expect(result.profile.topFiles[0].frequency).toBe(2);
+ });
+
+ it("extracts conventions from file patterns", async () => {
+ const result = (await sdk.trigger("mem::profile", {
+ project: "my-project",
+ })) as { profile: ProjectProfile };
+
+ expect(result.profile.conventions).toContain("TypeScript project");
+ expect(result.profile.conventions).toContain(
+ "Standard src/ directory structure",
+ );
+ });
+
+ it("returns cached profile if fresh", async () => {
+ await sdk.trigger("mem::profile", { project: "my-project" });
+
+ const result = (await sdk.trigger("mem::profile", {
+ project: "my-project",
+ })) as { profile: ProjectProfile; cached: boolean };
+
+ expect(result.cached).toBe(true);
+ });
+
+ it("returns null profile for unknown project", async () => {
+ const result = (await sdk.trigger("mem::profile", {
+ project: "nonexistent",
+ })) as { profile: null; reason: string };
+
+ expect(result.profile).toBeNull();
+ expect(result.reason).toBe("no_sessions");
+ });
+});
diff --git a/test/relations.test.ts b/test/relations.test.ts
new file mode 100644
index 00000000..b818bc0a
--- /dev/null
+++ b/test/relations.test.ts
@@ -0,0 +1,198 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerRelationsFunction } from "../src/functions/relations.js";
+import type { Memory } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ getFunction: (id: string) => functions.get(id),
+ };
+}
+
+function makeMemory(overrides: Partial<Memory> = {}): Memory {
+ return {
+ id: "mem_1",
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ type: "pattern",
+ title: "Test memory",
+ content: "This is a test memory",
+ concepts: ["test"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ ...overrides,
+ };
+}
+
+describe("Relations Functions", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerRelationsFunction(sdk as never, kv as never);
+ });
+
+ describe("mem::relate", () => {
+ it("creates a relation between two memories", async () => {
+ const mem1 = makeMemory({ id: "mem_1" });
+ const mem2 = makeMemory({ id: "mem_2" });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ const result = await sdk.trigger("mem::relate", {
+ sourceId: "mem_1",
+ targetId: "mem_2",
+ type: "related",
+ });
+
+ expect((result as { success: boolean }).success).toBe(true);
+
+ const updated1 = await kv.get<Memory>("mem:memories", "mem_1");
+ const updated2 = await kv.get<Memory>("mem:memories", "mem_2");
+ expect(updated1!.relatedIds).toContain("mem_2");
+ expect(updated2!.relatedIds).toContain("mem_1");
+ });
+
+ it("returns error when source memory not found", async () => {
+ const mem2 = makeMemory({ id: "mem_2" });
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ const result = await sdk.trigger("mem::relate", {
+ sourceId: "mem_missing",
+ targetId: "mem_2",
+ type: "related",
+ });
+
+ expect((result as { success: boolean }).success).toBe(false);
+ });
+
+ it("does not duplicate relatedIds on repeated calls", async () => {
+ const mem1 = makeMemory({ id: "mem_1", relatedIds: ["mem_2"] });
+ const mem2 = makeMemory({ id: "mem_2", relatedIds: ["mem_1"] });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+
+ await sdk.trigger("mem::relate", {
+ sourceId: "mem_1",
+ targetId: "mem_2",
+ type: "related",
+ });
+
+ const updated1 = await kv.get<Memory>("mem:memories", "mem_1");
+ expect(updated1!.relatedIds!.filter((id) => id === "mem_2").length).toBe(1);
+ });
+ });
+
+ describe("mem::evolve", () => {
+ it("marks old memory as not latest and creates new version", async () => {
+ const original = makeMemory({ id: "mem_old", version: 1 });
+ await kv.set("mem:memories", "mem_old", original);
+
+ const result = (await sdk.trigger("mem::evolve", {
+ memoryId: "mem_old",
+ newContent: "Updated content",
+ newTitle: "Updated title",
+ })) as { success: boolean; memory: Memory; previousId: string };
+
+ expect(result.success).toBe(true);
+ expect(result.memory.version).toBe(2);
+ expect(result.memory.content).toBe("Updated content");
+ expect(result.memory.title).toBe("Updated title");
+ expect(result.memory.parentId).toBe("mem_old");
+ expect(result.memory.isLatest).toBe(true);
+
+ const old = await kv.get<Memory>("mem:memories", "mem_old");
+ expect(old!.isLatest).toBe(false);
+ });
+
+ it("returns error when memory not found", async () => {
+ const result = await sdk.trigger("mem::evolve", {
+ memoryId: "mem_missing",
+ newContent: "Updated content",
+ });
+
+ expect((result as { success: boolean }).success).toBe(false);
+ });
+ });
+
+ describe("mem::get-related", () => {
+ it("retrieves related memories within 1 hop", async () => {
+ const mem1 = makeMemory({ id: "mem_1", relatedIds: ["mem_2"] });
+ const mem2 = makeMemory({ id: "mem_2", relatedIds: ["mem_1", "mem_3"] });
+ const mem3 = makeMemory({ id: "mem_3", relatedIds: ["mem_2"] });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+ await kv.set("mem:memories", "mem_3", mem3);
+
+ const result = (await sdk.trigger("mem::get-related", {
+ memoryId: "mem_1",
+ maxHops: 1,
+ })) as { results: Array<{ memory: Memory; hop: number }> };
+
+ expect(result.results.length).toBe(1);
+ expect(result.results[0].memory.id).toBe("mem_2");
+ expect(result.results[0].hop).toBe(1);
+ });
+
+ it("retrieves related memories within 2 hops", async () => {
+ const mem1 = makeMemory({ id: "mem_1", relatedIds: ["mem_2"] });
+ const mem2 = makeMemory({ id: "mem_2", relatedIds: ["mem_1", "mem_3"] });
+ const mem3 = makeMemory({ id: "mem_3", relatedIds: ["mem_2"] });
+ await kv.set("mem:memories", "mem_1", mem1);
+ await kv.set("mem:memories", "mem_2", mem2);
+ await kv.set("mem:memories", "mem_3", mem3);
+
+ const result = (await sdk.trigger("mem::get-related", {
+ memoryId: "mem_1",
+ maxHops: 2,
+ })) as { results: Array<{ memory: Memory; hop: number }> };
+
+ expect(result.results.length).toBe(2);
+ const ids = result.results.map((r) => r.memory.id);
+ expect(ids).toContain("mem_2");
+ expect(ids).toContain("mem_3");
+ });
+ });
+});
diff --git a/test/smart-search.test.ts b/test/smart-search.test.ts
new file mode 100644
index 00000000..0c58fc4d
--- /dev/null
+++ b/test/smart-search.test.ts
@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerSmartSearchFunction } from "../src/functions/smart-search.js";
+import type {
+ CompressedObservation,
+ HybridSearchResult,
+ CompactSearchResult,
+ Session,
+} from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+function makeObs(
+ overrides: Partial<CompressedObservation> = {},
+): CompressedObservation {
+ return {
+ id: "obs_1",
+ sessionId: "ses_1",
+ timestamp: "2026-02-01T10:00:00Z",
+ type: "file_edit",
+ title: "Edit auth handler",
+ facts: [],
+ narrative: "Modified auth",
+ concepts: ["auth"],
+ files: ["src/auth.ts"],
+ importance: 7,
+ ...overrides,
+ };
+}
+
+describe("Smart Search Function", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+ let searchResults: HybridSearchResult[];
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+
+ const obs1 = makeObs({ id: "obs_1", sessionId: "ses_1", title: "Auth handler" });
+ const obs2 = makeObs({ id: "obs_2", sessionId: "ses_1", title: "Database setup" });
+
+ searchResults = [
+ {
+ observation: obs1,
+ bm25Score: 0.8,
+ vectorScore: 0,
+ combinedScore: 0.8,
+ sessionId: "ses_1",
+ },
+ {
+ observation: obs2,
+ bm25Score: 0.3,
+ vectorScore: 0,
+ combinedScore: 0.3,
+ sessionId: "ses_1",
+ },
+ ];
+
+ const session: Session = {
+ id: "ses_1",
+ project: "my-project",
+ cwd: "/tmp",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "completed",
+ observationCount: 2,
+ };
+ await kv.set("mem:sessions", "ses_1", session);
+ await kv.set("mem:obs:ses_1", "obs_1", obs1);
+ await kv.set("mem:obs:ses_1", "obs_2", obs2);
+
+ const searchFn = async (_query: string, _limit: number) => searchResults;
+ registerSmartSearchFunction(sdk as never, kv as never, searchFn);
+ });
+
+ it("compact mode returns CompactSearchResult array", async () => {
+ const result = (await sdk.trigger("mem::smart-search", {
+ query: "auth",
+ })) as { mode: string; results: CompactSearchResult[] };
+
+ expect(result.mode).toBe("compact");
+ expect(result.results.length).toBe(2);
+ expect(result.results[0]).toHaveProperty("obsId");
+ expect(result.results[0]).toHaveProperty("title");
+ expect(result.results[0]).toHaveProperty("type");
+ expect(result.results[0]).toHaveProperty("score");
+ expect(result.results[0]).toHaveProperty("timestamp");
+ expect(result.results[0]).not.toHaveProperty("narrative");
+ });
+
+ it("expand mode returns full observations for given IDs", async () => {
+ const result = (await sdk.trigger("mem::smart-search", {
+ expandIds: ["obs_1"],
+ })) as { mode: string; results: Array<{ obsId: string; observation: CompressedObservation }> };
+
+ expect(result.mode).toBe("expanded");
+ expect(result.results.length).toBe(1);
+ expect(result.results[0].observation.title).toBe("Auth handler");
+ });
+
+ it("returns error when query is missing and no expandIds", async () => {
+ const result = (await sdk.trigger("mem::smart-search", {})) as {
+ mode: string;
+ error: string;
+ };
+
+ expect(result.mode).toBe("compact");
+ expect(result.error).toBe("query is required");
+ expect((result as { results: unknown[] }).results).toEqual([]);
+ });
+
+ it("respects limit parameter in compact mode", async () => {
+ const result = (await sdk.trigger("mem::smart-search", {
+ query: "auth",
+ limit: 1,
+ })) as { mode: string; results: CompactSearchResult[] };
+
+ expect(result.results.length).toBeLessThanOrEqual(2);
+ });
+
+ it("expand returns empty for nonexistent observation IDs", async () => {
+ const result = (await sdk.trigger("mem::smart-search", {
+ expandIds: ["obs_nonexistent_ses_xxx"],
+ })) as { mode: string; results: unknown[] };
+
+ expect(result.mode).toBe("expanded");
+ expect(result.results.length).toBe(0);
+ });
+});
diff --git a/test/timeline.test.ts b/test/timeline.test.ts
new file mode 100644
index 00000000..3e48bf0c
--- /dev/null
+++ b/test/timeline.test.ts
@@ -0,0 +1,148 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("iii-sdk", () => ({
+ getContext: () => ({
+ logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn() },
+ }),
+}));
+
+import { registerTimelineFunction } from "../src/functions/timeline.js";
+import type { CompressedObservation, Session, TimelineEntry } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ return (store.get(scope)?.get(key) as T) ?? null;
+ },
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ return {
+ registerFunction: (opts: { id: string }, handler: Function) => {
+ functions.set(opts.id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (id: string, data: unknown) => {
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(data);
+ },
+ };
+}
+
+function makeObs(
+ id: string,
+ timestamp: string,
+ title: string,
+): CompressedObservation {
+ return {
+ id,
+ sessionId: "ses_1",
+ timestamp,
+ type: "file_edit",
+ title,
+ facts: [],
+ narrative: title,
+ concepts: [],
+ files: [],
+ importance: 5,
+ };
+}
+
+describe("Timeline Function", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerTimelineFunction(sdk as never, kv as never);
+
+ const session: Session = {
+ id: "ses_1",
+ project: "my-project",
+ cwd: "/tmp",
+ startedAt: "2026-02-01T00:00:00Z",
+ status: "completed",
+ observationCount: 5,
+ };
+ await kv.set("mem:sessions", "ses_1", session);
+
+ await kv.set("mem:obs:ses_1", "obs_1", makeObs("obs_1", "2026-02-01T10:00:00Z", "First edit"));
+ await kv.set("mem:obs:ses_1", "obs_2", makeObs("obs_2", "2026-02-01T11:00:00Z", "Second edit"));
+ await kv.set("mem:obs:ses_1", "obs_3", makeObs("obs_3", "2026-02-01T12:00:00Z", "Third edit"));
+ await kv.set("mem:obs:ses_1", "obs_4", makeObs("obs_4", "2026-02-01T13:00:00Z", "Fourth edit"));
+ await kv.set("mem:obs:ses_1", "obs_5", makeObs("obs_5", "2026-02-01T14:00:00Z", "Fifth edit"));
+ });
+
+ it("anchors by ISO date and returns surrounding observations", async () => {
+ const result = (await sdk.trigger("mem::timeline", {
+ anchor: "2026-02-01T12:00:00Z",
+ before: 2,
+ after: 2,
+ })) as { entries: TimelineEntry[] };
+
+ expect(result.entries.length).toBe(5);
+ expect(result.entries[0].observation.id).toBe("obs_1");
+ expect(result.entries[4].observation.id).toBe("obs_5");
+ });
+
+ it("relativePosition is correct relative to anchor", async () => {
+ const result = (await sdk.trigger("mem::timeline", {
+ anchor: "2026-02-01T12:00:00Z",
+ before: 2,
+ after: 2,
+ })) as { entries: TimelineEntry[] };
+
+ const positions = result.entries.map((e) => e.relativePosition);
+ expect(positions).toEqual([-2, -1, 0, 1, 2]);
+ });
+
+ it("respects before and after limits", async () => {
+ const result = (await sdk.trigger("mem::timeline", {
+ anchor: "2026-02-01T12:00:00Z",
+ before: 1,
+ after: 1,
+ })) as { entries: TimelineEntry[] };
+
+ expect(result.entries.length).toBe(3);
+ expect(result.entries[0].observation.id).toBe("obs_2");
+ expect(result.entries[2].observation.id).toBe("obs_4");
+ });
+
+ it("returns empty entries when no sessions exist for project", async () => {
+ const result = (await sdk.trigger("mem::timeline", {
+ anchor: "2026-02-01T12:00:00Z",
+ project: "nonexistent-project",
+ })) as { entries: TimelineEntry[] };
+
+ expect(result.entries.length).toBe(0);
+ });
+
+ it("handles keyword anchor by finding matching observation", async () => {
+ const result = (await sdk.trigger("mem::timeline", {
+ anchor: "Third",
+ before: 1,
+ after: 1,
+ })) as { entries: TimelineEntry[] };
+
+ expect(result.entries.length).toBe(3);
+ const titles = result.entries.map((e) => e.observation.title);
+ expect(titles).toContain("Third edit");
+ });
+});
diff --git a/test/vector-index.test.ts b/test/vector-index.test.ts
new file mode 100644
index 00000000..7415e557
--- /dev/null
+++ b/test/vector-index.test.ts
@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { VectorIndex } from "../src/state/vector-index.js";
+
+describe("VectorIndex", () => {
+ let index: VectorIndex;
+
+ beforeEach(() => {
+ index = new VectorIndex();
+ });
+
+ it("starts empty", () => {
+ expect(index.size).toBe(0);
+ });
+
+ it("adds and retrieves vectors", () => {
+ index.add("obs_1", "ses_1", new Float32Array([0.1, 0.2, 0.3]));
+ expect(index.size).toBe(1);
+ });
+
+ it("removes a vector", () => {
+ index.add("obs_1", "ses_1", new Float32Array([0.1, 0.2, 0.3]));
+ index.remove("obs_1");
+ expect(index.size).toBe(0);
+ });
+
+ it("returns empty array when searching empty index", () => {
+ const results = index.search(new Float32Array([0.1, 0.2, 0.3]));
+ expect(results).toEqual([]);
+ });
+
+ it("returns results sorted by cosine similarity", () => {
+ index.add("obs_close", "ses_1", new Float32Array([1, 0, 0]));
+ index.add("obs_far", "ses_1", new Float32Array([0, 1, 0]));
+ index.add("obs_medium", "ses_1", new Float32Array([0.7, 0.7, 0]));
+
+ const results = index.search(new Float32Array([1, 0, 0]));
+ expect(results[0].obsId).toBe("obs_close");
+ expect(results[0].score).toBeCloseTo(1.0, 5);
+ expect(results[1].obsId).toBe("obs_medium");
+ expect(results[2].obsId).toBe("obs_far");
+ expect(results[2].score).toBeCloseTo(0.0, 5);
+ });
+
+ it("respects the limit parameter", () => {
+ for (let i = 0; i < 10; i++) {
+ index.add(`obs_${i}`, "ses_1", new Float32Array([i * 0.1, 0.5, 0.5]));
+ }
+ const results = index.search(new Float32Array([0.9, 0.5, 0.5]), 3);
+ expect(results.length).toBe(3);
+ });
+
+ it("clears all vectors", () => {
+ index.add("obs_1", "ses_1", new Float32Array([0.1, 0.2, 0.3]));
+ index.add("obs_2", "ses_1", new Float32Array([0.4, 0.5, 0.6]));
+ index.clear();
+ expect(index.size).toBe(0);
+ expect(index.search(new Float32Array([0.1, 0.2, 0.3]))).toEqual([]);
+ });
+
+ it("serialize and deserialize round-trip preserves data", () => {
+ index.add("obs_1", "ses_1", new Float32Array([0.1, 0.2, 0.3]));
+ index.add("obs_2", "ses_2", new Float32Array([0.4, 0.5, 0.6]));
+
+ const json = index.serialize();
+ const restored = VectorIndex.deserialize(json);
+
+ expect(restored.size).toBe(2);
+ const results = restored.search(new Float32Array([0.1, 0.2, 0.3]), 2);
+ expect(results.length).toBe(2);
+ expect(results[0].obsId).toBe("obs_1");
+ expect(results[0].sessionId).toBe("ses_1");
+ });
+
+ it("handles zero vectors without error", () => {
+ index.add("obs_zero", "ses_1", new Float32Array([0, 0, 0]));
+ const results = index.search(new Float32Array([1, 0, 0]));
+ expect(results[0].score).toBe(0);
+ });
+});