#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
feat: agentmemory v0.3.0 — semantic search, memory evolution, profiles
Rohit Ghumarea6fabc77d22d
diff --git a/package.json b/package.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});