Skip to content

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

fix(context): auto-inject lessons into mem::context payload (#457) (#458)

Rohit Ghumarea557e34f3992
diff --git a/src/functions/context.ts b/src/functions/context.ts
index 319de1ee..1e6102cf 100644
--- a/src/functions/context.ts
+++ b/src/functions/context.ts
@@ -6,6 +6,7 @@ import type {
ContextBlock,
ProjectProfile,
MemorySlot,
+ Lesson,
} from "../types.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
@@ -39,13 +40,14 @@ export function registerContextFunction(
const budget = data.budget || tokenBudget;
const blocks: ContextBlock[] = [];
- const [pinnedSlots, profile] = await Promise.all([
+ const [pinnedSlots, profile, lessons] = await Promise.all([
isSlotsEnabled()
? listPinnedSlots(kv).catch(() => [] as MemorySlot[])
: Promise.resolve([] as MemorySlot[]),
kv
.get<ProjectProfile>(KV.profiles, data.project)
.catch(() => null),
+ kv.list<Lesson>(KV.lessons).catch(() => [] as Lesson[]),
]);
const slotContent = renderPinnedContext(pinnedSlots);
@@ -94,6 +96,42 @@ export function registerContextFunction(
}
}
+ // Lessons — closes the loop opened by mem::lesson-save / mem::reflect.
+ // Without this block, lessons sit in KV and only surface when the agent
+ // thinks to call memory_lesson_recall. Ranking puts project-scoped
+ // lessons ahead of global ones, then weights by confidence; we cap at
+ // 10 to keep the block bounded since the outer token-budget loop
+ // below will drop the whole block if it doesn't fit. #457.
+ const relevantLessons = lessons
+ .filter((l) => !l.deleted && (!l.project || l.project === data.project))
+ .sort((a, b) => {
+ const scoreA = (a.project === data.project ? 1.5 : 1) * a.confidence;
+ const scoreB = (b.project === data.project ? 1.5 : 1) * b.confidence;
+ return scoreB - scoreA;
+ })
+ .slice(0, 10);
+
+ if (relevantLessons.length > 0) {
+ const items = relevantLessons
+ .map(
+ (l) =>
+ `- (${l.confidence.toFixed(2)}) ${l.content}${l.context ? ` — ${l.context}` : ""}`,
+ )
+ .join("\n");
+ const lessonsContent = `## Lessons Learned\n${items}`;
+ const mostRecent = relevantLessons.reduce((acc, l) => {
+ const t = new Date(l.lastReinforcedAt || l.updatedAt).getTime();
+ return t > acc ? t : acc;
+ }, 0);
+ blocks.push({
+ type: "memory",
+ content: lessonsContent,
+ tokens: estimateTokens(lessonsContent),
+ recency: mostRecent,
+ sourceIds: relevantLessons.map((l) => l.id),
+ });
+ }
+
const allSessions = await kv.list<Session>(KV.sessions);
const sessions = allSessions
.filter((s) => s.project === data.project && s.id !== data.sessionId)
diff --git a/test/context-lessons.test.ts b/test/context-lessons.test.ts
new file mode 100644
index 00000000..d915c939
--- /dev/null
+++ b/test/context-lessons.test.ts
@@ -0,0 +1,226 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { registerContextFunction } from "../src/functions/context.js";
+import { KV } from "../src/state/schema.js";
+import type { Lesson } 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[]> => {
+ if (!store.has(scope)) return [];
+ return Array.from(store.get(scope)!.values()) as T[];
+ },
+ };
+}
+
+type ContextHandler = (data: {
+ sessionId: string;
+ project: string;
+ budget?: number;
+}) => Promise<{ context: string; blocks: number; tokens: number }>;
+
+function wireContext(kv: ReturnType<typeof mockKV>, budget = 4000) {
+ let handler: ContextHandler | undefined;
+ const sdk = {
+ registerFunction: vi.fn((id: string, cb: ContextHandler) => {
+ if (id === "mem::context") handler = cb;
+ }),
+ } as unknown as import("iii-sdk").ISdk;
+ registerContextFunction(sdk, kv as never, budget);
+ if (!handler) throw new Error("mem::context not registered");
+ return handler;
+}
+
+function makeLesson(over: Partial<Lesson> = {}): Lesson {
+ const now = new Date().toISOString();
+ return {
+ id: over.id ?? `lesson_${Math.random().toString(36).slice(2)}`,
+ content: over.content ?? "default lesson content",
+ context: over.context ?? "",
+ confidence: over.confidence ?? 0.7,
+ reinforcements: over.reinforcements ?? 1,
+ source: over.source ?? "manual",
+ sourceIds: over.sourceIds ?? [],
+ project: over.project,
+ tags: over.tags ?? [],
+ createdAt: over.createdAt ?? now,
+ updatedAt: over.updatedAt ?? now,
+ lastReinforcedAt: over.lastReinforcedAt,
+ lastDecayedAt: over.lastDecayedAt,
+ decayRate: over.decayRate ?? 0.05,
+ deleted: over.deleted,
+ };
+}
+
+async function seedLesson(
+ kv: ReturnType<typeof mockKV>,
+ partial: Partial<Lesson>,
+) {
+ const lesson = makeLesson(partial);
+ await kv.set(KV.lessons, lesson.id, lesson);
+ return lesson;
+}
+
+describe("mem::context — lessons auto-injection (#457)", () => {
+ let kv: ReturnType<typeof mockKV>;
+ let handler: ContextHandler;
+
+ beforeEach(() => {
+ kv = mockKV();
+ handler = wireContext(kv);
+ });
+
+ it("includes a 'Lessons Learned' block when KV has lessons for the project", async () => {
+ await seedLesson(kv, {
+ id: "lesson_a",
+ content: "always run npm test before commit",
+ project: "/tmp/proj",
+ confidence: 0.85,
+ });
+
+ const result = await handler({
+ sessionId: "ses_a",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).toContain("Lessons Learned");
+ expect(result.context).toContain("always run npm test before commit");
+ expect(result.blocks).toBeGreaterThan(0);
+ });
+
+ it("omits the lessons block entirely when KV has no lessons", async () => {
+ const result = await handler({
+ sessionId: "ses_empty",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).not.toContain("Lessons Learned");
+ });
+
+ it("ranks project-scoped lessons above global lessons", async () => {
+ await seedLesson(kv, {
+ id: "lesson_global",
+ content: "global-lesson-marker",
+ project: undefined,
+ confidence: 0.9,
+ });
+ await seedLesson(kv, {
+ id: "lesson_project",
+ content: "project-lesson-marker",
+ project: "/tmp/proj",
+ confidence: 0.7,
+ });
+
+ const result = await handler({
+ sessionId: "ses_rank",
+ project: "/tmp/proj",
+ });
+
+ const projectIdx = result.context.indexOf("project-lesson-marker");
+ const globalIdx = result.context.indexOf("global-lesson-marker");
+ expect(projectIdx).toBeGreaterThan(-1);
+ expect(globalIdx).toBeGreaterThan(-1);
+ expect(projectIdx).toBeLessThan(globalIdx);
+ });
+
+ it("excludes lessons scoped to a different project", async () => {
+ await seedLesson(kv, {
+ id: "lesson_other",
+ content: "other-project-lesson",
+ project: "/tmp/other-project",
+ confidence: 0.9,
+ });
+
+ const result = await handler({
+ sessionId: "ses_isolate",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).not.toContain("other-project-lesson");
+ });
+
+ it("excludes deleted lessons", async () => {
+ await seedLesson(kv, {
+ id: "lesson_deleted",
+ content: "tombstoned-lesson",
+ project: "/tmp/proj",
+ confidence: 0.9,
+ deleted: true,
+ });
+
+ const result = await handler({
+ sessionId: "ses_deleted",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).not.toContain("tombstoned-lesson");
+ });
+
+ it("caps at the top 10 lessons by confidence", async () => {
+ for (let i = 0; i < 15; i++) {
+ await seedLesson(kv, {
+ id: `lesson_${i}`,
+ content: `lesson-marker-${i}`,
+ project: "/tmp/proj",
+ confidence: i / 100,
+ });
+ }
+
+ const result = await handler({
+ sessionId: "ses_cap",
+ project: "/tmp/proj",
+ });
+
+ const matched = result.context.match(/lesson-marker-/g) ?? [];
+ expect(matched.length).toBe(10);
+ expect(result.context).toContain("lesson-marker-14");
+ expect(result.context).toContain("lesson-marker-5");
+ expect(result.context).not.toContain("lesson-marker-0");
+ });
+
+ it("shows lesson confidence in the rendered line", async () => {
+ await seedLesson(kv, {
+ id: "lesson_conf",
+ content: "test confidence rendering",
+ project: "/tmp/proj",
+ confidence: 0.83,
+ });
+
+ const result = await handler({
+ sessionId: "ses_conf",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).toContain("(0.83)");
+ });
+
+ it("appends optional context string when present", async () => {
+ await seedLesson(kv, {
+ id: "lesson_ctx",
+ content: "use TaskCreate for >5-file work",
+ context: "when working on multi-file refactors",
+ project: "/tmp/proj",
+ confidence: 0.8,
+ });
+
+ const result = await handler({
+ sessionId: "ses_ctx",
+ project: "/tmp/proj",
+ });
+
+ expect(result.context).toContain(
+ "use TaskCreate for >5-file work — when working on multi-file refactors",
+ );
+ });
+});