Skip to content

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

12.6 KB
Raw Blame
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { KV, fingerprintId } from "../state/schema.js";
import type { Lesson } from "../types.js";
import { SearchIndex } from "../state/search-index.js";
import { lessonToObservation } from "../state/memory-utils.js";
import { recordAudit } from "./audit.js";

// Dedicated BM25 index for lessons, with the full records cached
// alongside it. Recall previously listed every lesson from KV and
// substring-matched per query — O(corpus) per call with no term
// weighting. Index and record cache are built lazily from one KV list
// (the same cost a single recall used to pay) and kept current
// incrementally on save/delete/decay. Confidence x recency reranking
// stays exactly as before — the index only replaces the relevance term,
// and the record cache keeps recall at zero KV round-trips.
let lessonIndex: SearchIndex | null = null;
const lessonRecords = new Map<string, Lesson>();
let lessonIndexBuild: Promise<void> | null = null;
let lessonIndexGeneration = 0;

export function resetLessonIndex(): void {
  lessonIndexGeneration++;
  lessonIndex = null;
  lessonRecords.clear();
}

function noteLessonMutation(): void {
  if (!lessonIndex && lessonIndexBuild) resetLessonIndex();
}

async function ensureLessonIndex(kv: StateKV): Promise<SearchIndex> {
  if (lessonIndex) return lessonIndex;
  if (!lessonIndexBuild) {
    const generation = lessonIndexGeneration;
    lessonIndexBuild = (async () => {
      const idx = new SearchIndex();
      const all = await kv.list<Lesson>(KV.lessons);
      if (generation !== lessonIndexGeneration) return;
      for (const l of all) {
        if (!l.deleted) {
          idx.add(lessonToObservation(l), "lesson");
          lessonRecords.set(l.id, l);
        }
      }
      lessonIndex = idx;
    })().finally(() => {
      lessonIndexBuild = null;
    });
  }
  await lessonIndexBuild;
  return lessonIndex ?? ensureLessonIndex(kv);
}

function reinforceLesson(lesson: Lesson): void {
  const now = new Date().toISOString();
  lesson.reinforcements++;
  lesson.confidence = Math.min(
    1.0,
    lesson.confidence + 0.1 * (1 - lesson.confidence),
  );
  lesson.lastReinforcedAt = now;
  lesson.updatedAt = now;
}

export const LESSON_SOURCE_IDS_MAX = 50;
const LESSON_SOURCE_ID_MAX_LENGTH = 200;

export function normalizeLessonSourceIds(value: unknown): string[] | null {
  if (value === undefined || value === null) return [];
  if (!Array.isArray(value) || value.length > LESSON_SOURCE_IDS_MAX) return null;
  const ids: string[] = [];
  for (const raw of value) {
    if (typeof raw !== "string") return null;
    const id = raw.trim();
    if (!id || id.length > LESSON_SOURCE_ID_MAX_LENGTH || /\s/.test(id)) return null;
    if (!ids.includes(id)) ids.push(id);
  }
  return ids;
}

function mergeSourceIds(existing: string[] | undefined, incoming: string[] | undefined): string[] {
  const merged = [...(existing || [])];
  for (const id of incoming || []) {
    if (!merged.includes(id)) merged.push(id);
  }
  return merged.slice(-LESSON_SOURCE_IDS_MAX);
}

export function registerLessonsFunctions(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::lesson-save", 
    async (data: {
      content: string;
      context?: string;
      confidence?: number;
      project?: string;
      tags?: string[];
      source?: "crystal" | "manual" | "consolidation";
      sourceIds?: string[];
    }) => {
      if (!data.content?.trim()) {
        return { success: false, error: "content is required" };
      }

      const fp = fingerprintId("lsn", data.content.trim().toLowerCase());
      const existing = await kv.get<Lesson>(KV.lessons, fp);

      if (existing && !existing.deleted) {
        reinforceLesson(existing);
        let indexedTextChanged = false;
        if (data.context && !existing.context) {
          existing.context = data.context;
          indexedTextChanged = true;
        }
        if (data.sourceIds && data.sourceIds.length) {
          existing.sourceIds = mergeSourceIds(existing.sourceIds, data.sourceIds);
        }
        await kv.set(KV.lessons, existing.id, existing);
        lessonRecords.set(existing.id, existing);
        if (indexedTextChanged && lessonIndex) {
          lessonIndex.remove(existing.id);
          lessonIndex.add(lessonToObservation(existing), "lesson");
        }
        noteLessonMutation();

        try {
          await recordAudit(kv, "lesson_strengthen", "mem::lesson-save", [
            existing.id,
          ]);
        } catch {}

        return {
          success: true,
          action: "strengthened",
          lesson: existing,
        };
      }

      const confidence =
        typeof data.confidence === "number" &&
        data.confidence >= 0 &&
        data.confidence <= 1
          ? data.confidence
          : 0.5;

      const now = new Date().toISOString();
      const lesson: Lesson = {
        id: fp,
        content: data.content.trim(),
        context: data.context?.trim() || "",
        confidence,
        reinforcements: 0,
        source: data.source || "manual",
        sourceIds: data.sourceIds || [],
        project: data.project,
        tags: data.tags || [],
        createdAt: now,
        updatedAt: now,
        decayRate: 0.05,
      };

      await kv.set(KV.lessons, lesson.id, lesson);
      lessonRecords.set(lesson.id, lesson);
      if (lessonIndex) lessonIndex.add(lessonToObservation(lesson), "lesson");
      noteLessonMutation();

      try {
        await recordAudit(kv, "lesson_save", "mem::lesson-save", [lesson.id]);
      } catch {}

      return { success: true, action: "created", lesson };
    },
  );

  sdk.registerFunction("mem::lesson-recall", 
    async (data: {
      query: string;
      project?: string;
      minConfidence?: number;
      limit?: number;
    }) => {
      if (!data.query?.trim()) {
        return { success: false, error: "query is required" };
      }

      const minConfidence = data.minConfidence ?? 0.1;
      const limit = data.limit ?? 10;

      const idx = await ensureLessonIndex(kv);
      const filtering = !!data.project || minConfidence > 0.1;
      const fetchLimit = filtering
        ? Math.max(limit * 10, 100)
        : Math.max(limit * 5, 50);
      const hits = idx.search(data.query, fetchLimit);
      const maxHit = hits.length > 0 ? hits[0].score : 0;

      const scored: Array<{ lesson: Lesson; score: number }> = [];
      for (let i = 0; i < hits.length; i++) {
        const l = lessonRecords.get(hits[i].obsId);
        if (!l || l.deleted || l.confidence < minConfidence) continue;
        if (data.project && l.project !== data.project) continue;

        const relevance = maxHit > 0 ? hits[i].score / maxHit : 0;
        const daysSinceReinforced = l.lastReinforcedAt
          ? (Date.now() - new Date(l.lastReinforcedAt).getTime()) /
            (1000 * 60 * 60 * 24)
          : (Date.now() - new Date(l.createdAt).getTime()) /
            (1000 * 60 * 60 * 24);
        const recencyBoost = 1 / (1 + daysSinceReinforced * 0.01);
        scored.push({ lesson: l, score: l.confidence * relevance * recencyBoost });
      }

      scored.sort(
        (a, b) =>
          b.score - a.score ||
          (a.lesson.id < b.lesson.id ? -1 : a.lesson.id > b.lesson.id ? 1 : 0),
      );

      try {
        await recordAudit(kv, "lesson_recall", "mem::lesson-recall", [], {
          query: data.query,
          resultCount: scored.length,
        });
      } catch {}

      return {
        success: true,
        lessons: scored.slice(0, limit).map((s) => ({
          ...s.lesson,
          score: Math.round(s.score * 1000) / 1000,
        })),
      };
    },
  );

  sdk.registerFunction("mem::lesson-list", 
    async (data: {
      project?: string;
      source?: string;
      minConfidence?: number;
      limit?: number;
    }) => {
      const limit = data.limit ?? 50;
      const minConfidence = data.minConfidence ?? 0;
      let lessons = await kv.list<Lesson>(KV.lessons);

      lessons = lessons.filter(
        (l) => !l.deleted && l.confidence >= minConfidence,
      );

      if (data.project) {
        lessons = lessons.filter((l) => l.project === data.project);
      }
      if (data.source) {
        lessons = lessons.filter((l) => l.source === data.source);
      }

      lessons.sort((a, b) => b.confidence - a.confidence);

      return { success: true, lessons: lessons.slice(0, limit) };
    },
  );

  sdk.registerFunction("mem::lesson-strengthen", 
    async (data: { lessonId: string }) => {
      if (!data.lessonId) {
        return { success: false, error: "lessonId is required" };
      }

      const lesson = await kv.get<Lesson>(KV.lessons, data.lessonId);
      if (!lesson || lesson.deleted) {
        return { success: false, error: "lesson not found" };
      }

      reinforceLesson(lesson);

      await kv.set(KV.lessons, lesson.id, lesson);
      lessonRecords.set(lesson.id, lesson);
      noteLessonMutation();

      try {
        await recordAudit(kv, "lesson_strengthen", "mem::lesson-strengthen", [
          lesson.id,
        ]);
      } catch {}

      return { success: true, lesson };
    },
  );

  sdk.registerFunction("mem::lesson-delete",
    async (data: { lessonId: string }) => {
      if (!data.lessonId) {
        return { success: false, error: "lessonId is required" };
      }

      const lesson = await kv.get<Lesson>(KV.lessons, data.lessonId);
      if (!lesson || lesson.deleted) {
        return { success: false, error: "lesson not found" };
      }

      lesson.deleted = true;
      lesson.updatedAt = new Date().toISOString();

      await kv.set(KV.lessons, lesson.id, lesson);
      lessonRecords.delete(lesson.id);
      if (lessonIndex) lessonIndex.remove(lesson.id);
      noteLessonMutation();

      try {
        await recordAudit(kv, "lesson_delete", "mem::lesson-delete", [
          lesson.id,
        ]);
      } catch {}

      return { success: true, lesson };
    },
  );

  sdk.registerFunction("mem::lesson-decay-sweep", 
    async () => {
      const lessons = await kv.list<Lesson>(KV.lessons);
      let decayed = 0;
      let softDeleted = 0;
      const now = Date.now();
      const timestamp = new Date().toISOString();
      const dirty: Lesson[] = [];
      const auditEvents: Array<{
        id: string;
        action: "decay" | "soft-delete";
        beforeConfidence: number;
        afterConfidence: number;
        beforeDeleted: boolean;
        afterDeleted: boolean;
      }> = [];

      for (const lesson of lessons) {
        if (lesson.deleted) continue;

        const baseline = lesson.lastDecayedAt || lesson.lastReinforcedAt || lesson.createdAt;
        const weeksSinceBaseline =
          (now - new Date(baseline).getTime()) / (1000 * 60 * 60 * 24 * 7);

        if (weeksSinceBaseline < 1) continue;

        const decay = lesson.decayRate * weeksSinceBaseline;
        const newConfidence = Math.max(0.05, lesson.confidence - decay);

        if (newConfidence !== lesson.confidence) {
          const beforeConfidence = lesson.confidence;
          const beforeDeleted = !!lesson.deleted;
          lesson.confidence = Math.round(newConfidence * 1000) / 1000;
          lesson.lastDecayedAt = timestamp;
          lesson.updatedAt = timestamp;

          if (lesson.confidence <= 0.1 && lesson.reinforcements === 0) {
            lesson.deleted = true;
            softDeleted++;
          } else {
            decayed++;
          }

          dirty.push(lesson);
          auditEvents.push({
            id: lesson.id,
            action: lesson.deleted ? "soft-delete" : "decay",
            beforeConfidence,
            afterConfidence: lesson.confidence,
            beforeDeleted,
            afterDeleted: !!lesson.deleted,
          });
        }
      }

      await Promise.all(dirty.map((l) => kv.set(KV.lessons, l.id, l)));
      for (const l of dirty) {
        if (l.deleted) {
          lessonRecords.delete(l.id);
          if (lessonIndex) lessonIndex.remove(l.id);
        } else {
          lessonRecords.set(l.id, l);
        }
      }
      if (dirty.length > 0) noteLessonMutation();
      await Promise.all(
        auditEvents.map((event) =>
          recordAudit(kv, "lesson_strengthen", "mem::lesson-decay-sweep", [event.id], {
            action: event.action,
            actor: "system",
            reason: "decay-sweep",
            before: {
              confidence: event.beforeConfidence,
              deleted: event.beforeDeleted,
            },
            after: {
              confidence: event.afterConfidence,
              deleted: event.afterDeleted,
            },
          }),
        ),
      );

      return { success: true, decayed, softDeleted, total: lessons.length };
    },
  );
}