@agentmemory/agentmemory 0.7.0

package/src/functions/sketches.ts

@@ -0,0 +1,274 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV, generateId } from "../state/schema.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
+import type { Action, ActionEdge, Sketch } from "../types.js";
+
+export function registerSketchesFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::sketch-create" },
+    async (data: {
+      title: string;
+      description?: string;
+      expiresInMs?: number;
+      project?: string;
+    }) => {
+      if (!data.title || typeof data.title !== "string") {
+        return { success: false, error: "title is required" };
+      }
+
+      const now = new Date();
+      const expiresInMs = data.expiresInMs || 3600000;
+      const sketch: Sketch = {
+        id: generateId("sk"),
+        title: data.title.trim(),
+        description: (data.description || "").trim(),
+        status: "active",
+        actionIds: [],
+        project: data.project,
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + expiresInMs).toISOString(),
+      };
+
+      await kv.set(KV.sketches, sketch.id, sketch);
+      return { success: true, sketch };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sketch-add" },
+    async (data: {
+      sketchId: string;
+      title: string;
+      description?: string;
+      priority?: number;
+      dependsOn?: string[];
+    }) => {
+      if (!data.sketchId) {
+        return { success: false, error: "sketchId is required" };
+      }
+      if (!data.title || typeof data.title !== "string") {
+        return { success: false, error: "title is required" };
+      }
+
+      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
+        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
+        if (!sketch) {
+          return { success: false, error: "sketch not found" };
+        }
+        if (sketch.status !== "active") {
+          return { success: false, error: "sketch is not active" };
+        }
+
+        const now = new Date().toISOString();
+        const action: Action = {
+          id: generateId("act"),
+          title: data.title.trim(),
+          description: (data.description || "").trim(),
+          status: "pending",
+          priority: Math.max(1, Math.min(10, data.priority || 5)),
+          createdAt: now,
+          updatedAt: now,
+          createdBy: "sketch",
+          project: sketch.project,
+          tags: [],
+          sourceObservationIds: [],
+          sourceMemoryIds: [],
+          sketchId: data.sketchId,
+        };
+
+        if (data.dependsOn && data.dependsOn.length > 0) {
+          const sketchActionSet = new Set(sketch.actionIds);
+          for (const depId of data.dependsOn) {
+            if (!sketchActionSet.has(depId)) {
+              return {
+                success: false,
+                error: `dependency ${depId} not found in this sketch`,
+              };
+            }
+          }
+        }
+
+        await kv.set(KV.actions, action.id, action);
+
+        const createdEdges: ActionEdge[] = [];
+        if (data.dependsOn && data.dependsOn.length > 0) {
+          for (const depId of data.dependsOn) {
+            const edge: ActionEdge = {
+              id: generateId("ae"),
+              type: "requires",
+              sourceActionId: action.id,
+              targetActionId: depId,
+              createdAt: now,
+            };
+            await kv.set(KV.actionEdges, edge.id, edge);
+            createdEdges.push(edge);
+          }
+        }
+
+        sketch.actionIds.push(action.id);
+        await kv.set(KV.sketches, sketch.id, sketch);
+
+        return { success: true, action, edges: createdEdges };
+      });
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sketch-promote" },
+    async (data: { sketchId: string; project?: string }) => {
+      if (!data.sketchId) {
+        return { success: false, error: "sketchId is required" };
+      }
+
+      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
+        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
+        if (!sketch) {
+          return { success: false, error: "sketch not found" };
+        }
+        if (sketch.status !== "active") {
+          return { success: false, error: "sketch is not active" };
+        }
+
+        const promotedIds: string[] = [];
+        for (const actionId of sketch.actionIds) {
+          const action = await kv.get<Action>(KV.actions, actionId);
+          if (action) {
+            delete action.sketchId;
+            if (data.project) {
+              action.project = data.project;
+            }
+            action.updatedAt = new Date().toISOString();
+            await kv.set(KV.actions, action.id, action);
+            promotedIds.push(action.id);
+          }
+        }
+
+        sketch.status = "promoted";
+        sketch.promotedAt = new Date().toISOString();
+        await kv.set(KV.sketches, sketch.id, sketch);
+
+        return { success: true, promotedIds };
+      });
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sketch-discard" },
+    async (data: { sketchId: string }) => {
+      if (!data.sketchId) {
+        return { success: false, error: "sketchId is required" };
+      }
+
+      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
+        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
+        if (!sketch) {
+          return { success: false, error: "sketch not found" };
+        }
+        if (sketch.status !== "active") {
+          return { success: false, error: "sketch is not active" };
+        }
+
+        const actionIdSet = new Set(sketch.actionIds);
+
+        const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
+        for (const edge of allEdges) {
+          if (
+            actionIdSet.has(edge.sourceActionId) ||
+            actionIdSet.has(edge.targetActionId)
+          ) {
+            await kv.delete(KV.actionEdges, edge.id);
+          }
+        }
+
+        for (const actionId of sketch.actionIds) {
+          await kv.delete(KV.actions, actionId);
+        }
+
+        sketch.status = "discarded";
+        sketch.discardedAt = new Date().toISOString();
+        await kv.set(KV.sketches, sketch.id, sketch);
+
+        return { success: true, discardedCount: sketch.actionIds.length };
+      });
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sketch-list" },
+    async (data: { status?: string; project?: string }) => {
+      let sketches = await kv.list<Sketch>(KV.sketches);
+
+      if (data.status) {
+        sketches = sketches.filter((s) => s.status === data.status);
+      }
+      if (data.project) {
+        sketches = sketches.filter((s) => s.project === data.project);
+      }
+
+      sketches.sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+
+      const results = sketches.map((s) => ({
+        ...s,
+        actionCount: s.actionIds.length,
+      }));
+
+      return { success: true, sketches: results };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sketch-gc" },
+    async () => {
+      const sketches = await kv.list<Sketch>(KV.sketches);
+      const now = Date.now();
+      let collected = 0;
+
+      for (const sketch of sketches) {
+        if (
+          sketch.status !== "active" ||
+          new Date(sketch.expiresAt).getTime() > now
+        ) {
+          continue;
+        }
+
+        await withKeyedLock(`mem:sketch:${sketch.id}`, async () => {
+          const current = await kv.get<Sketch>(KV.sketches, sketch.id);
+          if (
+            !current ||
+            current.status !== "active" ||
+            new Date(current.expiresAt).getTime() > now
+          ) {
+            return;
+          }
+
+          const actionIdSet = new Set(current.actionIds);
+
+          const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
+          for (const edge of allEdges) {
+            if (
+              actionIdSet.has(edge.sourceActionId) ||
+              actionIdSet.has(edge.targetActionId)
+            ) {
+              await kv.delete(KV.actionEdges, edge.id);
+            }
+          }
+
+          for (const actionId of current.actionIds) {
+            await kv.delete(KV.actions, actionId);
+          }
+
+          current.status = "discarded";
+          current.discardedAt = new Date().toISOString();
+          await kv.set(KV.sketches, current.id, current);
+          collected++;
+        });
+      }
+
+      return { success: true, collected };
+    },
+  );
+}

package/src/functions/sliding-window.ts

@@ -0,0 +1,257 @@
+import type { ISdk } from "iii-sdk";
+import { getContext } from "iii-sdk";
+import type {
+  CompressedObservation,
+  EnrichedChunk,
+  MemoryProvider,
+} from "../types.js";
+import { KV, generateId } from "../state/schema.js";
+import type { StateKV } from "../state/kv.js";
+
+const SLIDING_WINDOW_SYSTEM = `You are a contextual enrichment engine. Given a primary observation and its surrounding context window (previous and next observations from the same session), produce an enriched version.
+
+Your tasks:
+1. ENTITY RESOLUTION: Replace all pronouns, implicit references ("that framework", "the file", "it", "he/she") with the explicit entity names found in the context window.
+2. PREFERENCE MAPPING: Extract any user preferences, constraints, or opinions expressed directly or indirectly.
+3. CONTEXT BRIDGES: Add brief contextual links that make this chunk self-contained without reading adjacent chunks.
+
+Output EXACTLY this XML:
+<enriched>
+  <content>The fully enriched, self-contained text with all references resolved</content>
+  <resolved_entities>
+    <entity original="pronoun or reference" resolved="explicit entity name"/>
+  </resolved_entities>
+  <preferences>
+    <preference>extracted user preference or constraint</preference>
+  </preferences>
+  <context_bridges>
+    <bridge>contextual link to adjacent information</bridge>
+  </context_bridges>
+</enriched>
+
+Rules:
+- The enriched content MUST be understandable in complete isolation
+- Resolve ALL ambiguous references using the context window
+- Do not hallucinate entities not present in the window
+- Preserve factual accuracy while adding clarity`;
+
+function buildWindowPrompt(
+  primary: CompressedObservation,
+  before: CompressedObservation[],
+  after: CompressedObservation[],
+): string {
+  const parts: string[] = [];
+
+  if (before.length > 0) {
+    parts.push("=== PRECEDING CONTEXT ===");
+    for (const obs of before) {
+      parts.push(`[${obs.type}] ${obs.title}: ${obs.narrative}`);
+      if (obs.facts.length > 0) parts.push(`Facts: ${obs.facts.join("; ")}`);
+      if (obs.concepts.length > 0)
+        parts.push(`Concepts: ${obs.concepts.join(", ")}`);
+    }
+  }
+
+  parts.push("\n=== PRIMARY OBSERVATION (enrich this) ===");
+  parts.push(`Type: ${primary.type}`);
+  parts.push(`Title: ${primary.title}`);
+  if (primary.subtitle) parts.push(`Subtitle: ${primary.subtitle}`);
+  parts.push(`Narrative: ${primary.narrative}`);
+  if (primary.facts.length > 0)
+    parts.push(`Facts: ${primary.facts.join("; ")}`);
+  if (primary.concepts.length > 0)
+    parts.push(`Concepts: ${primary.concepts.join(", ")}`);
+  if (primary.files.length > 0)
+    parts.push(`Files: ${primary.files.join(", ")}`);
+
+  if (after.length > 0) {
+    parts.push("\n=== FOLLOWING CONTEXT ===");
+    for (const obs of after) {
+      parts.push(`[${obs.type}] ${obs.title}: ${obs.narrative}`);
+      if (obs.facts.length > 0) parts.push(`Facts: ${obs.facts.join("; ")}`);
+    }
+  }
+
+  return parts.join("\n");
+}
+
+function parseEnrichedXml(xml: string): {
+  content: string;
+  resolvedEntities: Record<string, string>;
+  preferences: string[];
+  contextBridges: string[];
+} | null {
+  const contentMatch = xml.match(/<content>([\s\S]*?)<\/content>/);
+  if (!contentMatch) return null;
+
+  const resolvedEntities: Record<string, string> = {};
+  const entityRegex =
+    /<entity\s+original="([^"]+)"\s+resolved="([^"]+)"\s*\/>/g;
+  let match;
+  while ((match = entityRegex.exec(xml)) !== null) {
+    resolvedEntities[match[1]] = match[2];
+  }
+
+  const preferences: string[] = [];
+  const prefRegex = /<preference>([^<]+)<\/preference>/g;
+  while ((match = prefRegex.exec(xml)) !== null) {
+    preferences.push(match[1]);
+  }
+
+  const contextBridges: string[] = [];
+  const bridgeRegex = /<bridge>([^<]+)<\/bridge>/g;
+  while ((match = bridgeRegex.exec(xml)) !== null) {
+    contextBridges.push(match[1]);
+  }
+
+  return {
+    content: contentMatch[1].trim(),
+    resolvedEntities,
+    preferences,
+    contextBridges,
+  };
+}
+
+export function registerSlidingWindowFunction(
+  sdk: ISdk,
+  kv: StateKV,
+  provider: MemoryProvider,
+): void {
+  sdk.registerFunction(
+    {
+      id: "mem::enrich-window",
+      description:
+        "Enrich observation using sliding window context for self-containment",
+    },
+    async (data: {
+      observationId: string;
+      sessionId: string;
+      lookback?: number;
+      lookahead?: number;
+    }) => {
+      const ctx = getContext();
+      const hprev = data.lookback ?? 3;
+      const hnext = data.lookahead ?? 2;
+
+      const allObs = await kv.list<CompressedObservation>(
+        KV.observations(data.sessionId),
+      );
+      allObs.sort(
+        (a, b) =>
+          new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+      );
+
+      const primaryIdx = allObs.findIndex((o) => o.id === data.observationId);
+      if (primaryIdx === -1) {
+        return { success: false, error: "Observation not found" };
+      }
+
+      const primary = allObs[primaryIdx];
+      const before = allObs.slice(Math.max(0, primaryIdx - hprev), primaryIdx);
+      const after = allObs.slice(primaryIdx + 1, primaryIdx + 1 + hnext);
+
+      if (before.length === 0 && after.length === 0) {
+        return {
+          success: true,
+          enriched: null,
+          reason: "No adjacent context available",
+        };
+      }
+
+      try {
+        const prompt = buildWindowPrompt(primary, before, after);
+        const response = await provider.compress(
+          SLIDING_WINDOW_SYSTEM,
+          prompt,
+        );
+        const parsed = parseEnrichedXml(response);
+
+        if (!parsed) {
+          ctx.logger.warn("Failed to parse enrichment XML", {
+            obsId: data.observationId,
+          });
+          return { success: false, error: "parse_failed" };
+        }
+
+        const enriched: EnrichedChunk = {
+          id: generateId("ec"),
+          originalObsId: data.observationId,
+          sessionId: data.sessionId,
+          content: parsed.content,
+          resolvedEntities: parsed.resolvedEntities,
+          preferences: parsed.preferences,
+          contextBridges: parsed.contextBridges,
+          windowStart: Math.max(0, primaryIdx - hprev),
+          windowEnd: Math.min(allObs.length - 1, primaryIdx + hnext),
+          createdAt: new Date().toISOString(),
+        };
+
+        await kv.set(
+          KV.enrichedChunks(data.sessionId),
+          data.observationId,
+          enriched,
+        );
+
+        ctx.logger.info("Observation enriched via sliding window", {
+          obsId: data.observationId,
+          entitiesResolved: Object.keys(parsed.resolvedEntities).length,
+          preferencesFound: parsed.preferences.length,
+          bridges: parsed.contextBridges.length,
+        });
+
+        return { success: true, enriched };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.logger.error("Sliding window enrichment failed", { error: msg });
+        return { success: false, error: msg };
+      }
+    },
+  );
+
+  sdk.registerFunction(
+    {
+      id: "mem::enrich-session",
+      description: "Enrich all observations in a session using sliding windows",
+    },
+    async (data: {
+      sessionId: string;
+      lookback?: number;
+      lookahead?: number;
+      minImportance?: number;
+    }) => {
+      const ctx = getContext();
+      const allObs = await kv.list<CompressedObservation>(
+        KV.observations(data.sessionId),
+      );
+      const minImp = data.minImportance ?? 4;
+      const toEnrich = allObs.filter((o) => o.importance >= minImp);
+
+      let enriched = 0;
+      let failed = 0;
+
+      for (const obs of toEnrich) {
+        try {
+          const result = (await sdk.trigger("mem::enrich-window", {
+            observationId: obs.id,
+            sessionId: data.sessionId,
+            lookback: data.lookback ?? 3,
+            lookahead: data.lookahead ?? 2,
+          })) as { success?: boolean } | undefined;
+          if (result?.success) enriched++;
+          else failed++;
+        } catch {
+          failed++;
+        }
+      }
+
+      ctx.logger.info("Session enrichment complete", {
+        sessionId: data.sessionId,
+        total: toEnrich.length,
+        enriched,
+        failed,
+      });
+
+      return { success: true, total: toEnrich.length, enriched, failed };
+    },
+  );
+}

package/src/functions/smart-search.ts

@@ -0,0 +1,115 @@
+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?: Array<string | { obsId: string; sessionId: string }>;
+      limit?: number;
+    }) => {
+      const ctx = getContext();
+
+      if (data.expandIds && data.expandIds.length > 0) {
+        const raw = data.expandIds.slice(0, 20);
+        const items = raw.map((entry) => {
+          if (typeof entry === "string") return { obsId: entry, sessionId: undefined as string | undefined };
+          if (entry && typeof entry === "object" && typeof (entry as any).obsId === "string") {
+            return { obsId: (entry as any).obsId, sessionId: (entry as any).sessionId as string | undefined };
+          }
+          return null;
+        }).filter((item): item is NonNullable<typeof item> => item !== null);
+
+        const expanded: Array<{
+          obsId: string;
+          sessionId: string;
+          observation: CompressedObservation;
+        }> = [];
+
+        const results = await Promise.all(
+          items.map(({ obsId, sessionId }) =>
+            findObservation(kv, obsId, sessionId).then((obs) =>
+              obs ? { obsId, sessionId: obs.sessionId, observation: obs } : null,
+            ),
+          ),
+        );
+        for (const r of results) {
+          if (r) expanded.push(r);
+        }
+
+        const truncated = data.expandIds.length > raw.length;
+        ctx.logger.info("Smart search expanded", {
+          requested: data.expandIds.length,
+          attempted: raw.length,
+          returned: expanded.length,
+          truncated,
+        });
+        return { mode: "expanded", results: expanded, truncated };
+      }
+
+      if (!data.query || typeof data.query !== "string" || !data.query.trim()) {
+        return { mode: "compact", results: [], error: "query is required" };
+      }
+
+      const limit = Math.max(1, Math.min(data.limit ?? 20, 100));
+      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,
+  sessionIdHint?: string,
+): Promise<CompressedObservation | null> {
+  if (sessionIdHint) {
+    const obs = await kv
+      .get<CompressedObservation>(KV.observations(sessionIdHint), obsId)
+      .catch(() => null);
+    if (obs) return obs;
+  }
+
+  const sessions = await kv.list<{ id: string }>(KV.sessions);
+  for (let i = 0; i < sessions.length; i += 5) {
+    const batch = sessions.slice(i, i + 5);
+    const results = await Promise.all(
+      batch.map((s) =>
+        kv.get<CompressedObservation>(KV.observations(s.id), obsId).catch(() => null),
+      ),
+    );
+    const found = results.find((r) => r !== null);
+    if (found) return found;
+  }
+  return null;
+}