Skip to content

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

perf(patterns): bound mem::patterns to recent sessions (#1424)

Rohit Ghumareec887b9a2bd9
diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
index b2a78fe5..fc01a8dd 100644
--- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
+++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
@@ -34,7 +34,7 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
| `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. |
| `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. |
| `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. |
-| `memory_patterns` | | `project`: string | Detect recurring patterns across sessions. |
+| `memory_patterns` | | `project`: string, `limit`: integer | Detect recurring patterns across sessions. |
| `memory_profile` | | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. |
| `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. |
| `memory_reflect` | yes | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. |
diff --git a/src/functions/patterns.ts b/src/functions/patterns.ts
index eef43f30..4ea5819f 100644
--- a/src/functions/patterns.ts
+++ b/src/functions/patterns.ts
@@ -12,15 +12,33 @@ interface Pattern {
sessions: string[];
}
+const DEFAULT_SESSION_LIMIT = 50;
+const MAX_SESSION_LIMIT = 500;
+const MAX_OBSERVATIONS_SCANNED = 5_000;
+
+function resolveSessionLimit(raw: unknown): number {
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n <= 0) return DEFAULT_SESSION_LIMIT;
+ return Math.min(Math.max(Math.floor(n), 1), MAX_SESSION_LIMIT);
+}
+
export function registerPatternsFunction(sdk: IIIClient, kv: StateKV): void {
- sdk.registerFunction("mem::patterns",
- async (data: { project?: string }) => {
+ sdk.registerFunction("mem::patterns",
+ async (data?: { project?: string; limit?: number }) => {
+ const { project, limit } = data ?? {};
const patterns: Pattern[] = [];
+ const sessionLimit = resolveSessionLimit(limit);
const sessions = await kv.list<Session>(KV.sessions);
- const filtered = data.project
- ? sessions.filter((s) => s.project === data.project)
- : sessions;
+ const filtered = (project
+ ? sessions.filter((s) => s.project === project)
+ : sessions
+ )
+ .sort(
+ (a, b) =>
+ new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
+ )
+ .slice(0, sessionLimit);
const fileCoOccurrences = new Map<string, number>();
const fileSessionMap = new Map<string, Set<string>>();
@@ -29,15 +47,33 @@ export function registerPatternsFunction(sdk: IIIClient, kv: StateKV): void {
{ count: number; sessions: Set<string> }
>();
- // Bounded fan-out: load observations for up to 10 sessions in
- // parallel per batch (like consolidate), then fold each session's
- // observations into the shared maps serially so the accumulation
- // stays race-free. Parallelizing the kv.list I/O without exceeding
- // the invocation pool cuts wall time versus the old serial loop.
- for (let batch = 0; batch < filtered.length; batch += 10) {
- const chunk = filtered.slice(batch, batch + 10);
+ let observationsScanned = 0;
+ let sessionsProcessed = 0;
+ const sessionsSkipped: string[] = [];
+ let cursor = 0;
+ while (
+ cursor < filtered.length &&
+ observationsScanned < MAX_OBSERVATIONS_SCANNED
+ ) {
+ const remainingBudget = MAX_OBSERVATIONS_SCANNED - observationsScanned;
+ const eligible: Session[] = [];
+ let plannedObservations = 0;
+ while (cursor < filtered.length && eligible.length < 10) {
+ const session = filtered[cursor];
+ const count = session.observationCount || 0;
+ if (count > remainingBudget) {
+ sessionsSkipped.push(session.id);
+ cursor++;
+ continue;
+ }
+ if (plannedObservations + count > remainingBudget) break;
+ plannedObservations += count;
+ eligible.push(session);
+ cursor++;
+ }
+
const loaded = await Promise.all(
- chunk.map(async (session) => ({
+ eligible.map(async (session) => ({
session,
observations: await kv.list<CompressedObservation>(
KV.observations(session.id),
@@ -46,10 +82,18 @@ export function registerPatternsFunction(sdk: IIIClient, kv: StateKV): void {
);
for (const { session, observations } of loaded) {
+ if (observationsScanned >= MAX_OBSERVATIONS_SCANNED) break;
+ sessionsProcessed++;
if (!observations.length) continue;
+ const remaining = MAX_OBSERVATIONS_SCANNED - observationsScanned;
+ const bounded =
+ observations.length > remaining
+ ? observations.slice(0, remaining)
+ : observations;
+ observationsScanned += bounded.length;
const sessionFiles = new Set<string>();
- for (const obs of observations) {
+ for (const obs of bounded) {
if (!obs.files) continue;
for (const f of obs.files) {
sessionFiles.add(f);
@@ -115,10 +159,21 @@ export function registerPatternsFunction(sdk: IIIClient, kv: StateKV): void {
logger.info("Pattern detection complete", {
patterns: patterns.length,
- sessions: filtered.length,
+ sessionsInScope: filtered.length,
+ sessionsProcessed,
+ sessionsSkipped: sessionsSkipped.length,
+ sessionLimit,
+ observationsScanned,
});
- return { patterns: patterns.slice(0, 20) };
+ return {
+ patterns: patterns.slice(0, 20),
+ sessionsInScope: filtered.length,
+ sessionsProcessed,
+ sessionsSkipped,
+ sessionLimit,
+ observationsScanned,
+ };
},
);
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 75e6ba54..c951b67b 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -247,6 +247,7 @@ export function registerMcpEndpoints(
case "memory_patterns": {
const result = await sdk.trigger({ function_id: "mem::patterns", payload: {
project: args.project as string,
+ limit: args.limit,
} });
return {
status_code: 200,
diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts
index 1225b4ce..17b658de 100644
--- a/src/mcp/tools-registry.ts
+++ b/src/mcp/tools-registry.ts
@@ -115,6 +115,11 @@ export const CORE_TOOLS: McpToolDef[] = [
type: "object",
properties: {
project: { type: "string", description: "Project path to analyze" },
+ limit: {
+ type: "integer",
+ description:
+ "Most recent sessions to scan (default 50, max 500)",
+ },
},
},
},
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 4a1d3519..4cf5431b 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -1209,11 +1209,14 @@ export function registerApiTriggers(
config: { api_path: "/agentmemory/consolidate", http_method: "POST" },
});
- sdk.registerFunction("api::patterns",
- async (req: HttpRequest<{ project?: string }>): Promise<Response> => {
+ sdk.registerFunction("api::patterns",
+ async (req: HttpRequest<{ project?: string; limit?: number }>): Promise<Response> => {
const authErr = checkAuth(req, secret);
if (authErr) return authErr;
- const result = await sdk.trigger({ function_id: "mem::patterns", payload: req.body });
+ const result = await sdk.trigger({
+ function_id: "mem::patterns",
+ payload: { project: req.body?.project, limit: req.body?.limit },
+ });
return { status_code: 200, body: result };
},
);
diff --git a/test/patterns-api-hygiene.test.ts b/test/patterns-api-hygiene.test.ts
new file mode 100644
index 00000000..361aa495
--- /dev/null
+++ b/test/patterns-api-hygiene.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { registerApiTriggers } from "../src/triggers/api.js";
+import type { HttpRequest } from "@iii-dev/helpers/http";
+
+function mockKV() {
+ return {
+ get: async () => null,
+ set: async <T>(_s: string, _k: string, d: T) => d,
+ delete: async () => {},
+ update: async () => {},
+ list: async <T>(): Promise<T[]> => [],
+ };
+}
+
+function mockSdk() {
+ const fns = new Map<string, (payload: unknown) => Promise<unknown>>();
+ return {
+ registerFunction: (id: string, h: (payload: unknown) => Promise<unknown>) =>
+ fns.set(id, h),
+ registerTrigger: () => {},
+ trigger: async (input: { function_id: string; payload?: unknown }) =>
+ fns.get(input.function_id)?.(input.payload),
+ _fns: fns,
+ };
+}
+
+async function callPatterns(
+ sdk: ReturnType<typeof mockSdk>,
+ body?: Record<string, unknown>,
+): Promise<{ status_code: number; body: Record<string, unknown> }> {
+ const handler = sdk._fns.get("api::patterns")!;
+ return handler({
+ headers: {},
+ query_params: {},
+ body,
+ } as HttpRequest<Record<string, unknown>>) as Promise<{
+ status_code: number;
+ body: Record<string, unknown>;
+ }>;
+}
+
+describe("api::patterns request hygiene", () => {
+ it("defaults a bodyless request instead of throwing", async () => {
+ const kv = mockKV();
+ const sdk = mockSdk();
+ let received: unknown;
+ sdk.registerFunction("mem::patterns", async (payload) => {
+ received = payload;
+ return { patterns: [] };
+ });
+ registerApiTriggers(sdk as never, kv as never);
+
+ const res = await callPatterns(sdk);
+
+ expect(res.status_code).toBe(200);
+ expect(received).toEqual({ project: undefined, limit: undefined });
+ });
+
+ it("whitelists the body to project and limit, dropping unexpected fields", async () => {
+ const kv = mockKV();
+ const sdk = mockSdk();
+ let received: unknown;
+ sdk.registerFunction("mem::patterns", async (payload) => {
+ received = payload;
+ return { patterns: [] };
+ });
+ registerApiTriggers(sdk as never, kv as never);
+
+ await callPatterns(sdk, {
+ project: "alpha",
+ limit: 5,
+ extra: "should not pass through",
+ });
+
+ expect(received).toEqual({ project: "alpha", limit: 5 });
+ });
+});
diff --git a/test/patterns-session-bound.test.ts b/test/patterns-session-bound.test.ts
new file mode 100644
index 00000000..af9184d4
--- /dev/null
+++ b/test/patterns-session-bound.test.ts
@@ -0,0 +1,269 @@
+import { describe, it, expect, vi } from "vitest";
+import { mockKV, mockSdk } from "./helpers/mocks.js";
+import { registerPatternsFunction } from "../src/functions/patterns.js";
+import { KV } from "../src/state/schema.js";
+import type { CompressedObservation, Session } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+function session(index: number, project = "proj"): Session {
+ return {
+ id: `ses_${String(index).padStart(4, "0")}`,
+ project,
+ cwd: "/tmp",
+ startedAt: new Date(2026, 0, 1 + index).toISOString(),
+ status: "completed",
+ observationCount: 1,
+ };
+}
+
+function observation(id: string, files: string[]): CompressedObservation {
+ return {
+ id,
+ sessionId: "unused",
+ timestamp: "2026-01-01T00:00:00Z",
+ type: "file_edit",
+ title: "edit",
+ facts: [],
+ narrative: "n",
+ concepts: [],
+ files,
+ importance: 5,
+ };
+}
+
+type PatternsResult = {
+ patterns: Array<{ files: string[]; frequency: number }>;
+ sessionsInScope: number;
+ sessionsProcessed: number;
+ sessionsSkipped: string[];
+ sessionLimit: number;
+ observationsScanned: number;
+};
+
+async function setup() {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerPatternsFunction(sdk as never, kv as never);
+ return { sdk, kv };
+}
+
+async function seedSessions(
+ kv: ReturnType<typeof mockKV>,
+ count: number,
+ observationsPerSession: number,
+) {
+ for (let i = 0; i < count; i++) {
+ const s = session(i);
+ await kv.set(KV.sessions, s.id, s);
+ for (let j = 0; j < observationsPerSession; j++) {
+ await kv.set(
+ KV.observations(s.id),
+ `obs_${s.id}_${j}`,
+ observation(`obs_${s.id}_${j}`, [`fileA_${s.id}.ts`, `fileB_${s.id}.ts`]),
+ );
+ }
+ }
+}
+
+describe("mem::patterns session bound", () => {
+ it("defaults to the 50 most recent sessions when no limit is given", async () => {
+ const { sdk, kv } = await setup();
+ await seedSessions(kv, 60, 1);
+
+ const result = (await sdk.trigger("mem::patterns", {})) as PatternsResult;
+
+ expect(result.sessionLimit).toBe(50);
+ expect(result.sessionsInScope).toBe(50);
+ expect(result.sessionsProcessed).toBe(50);
+ });
+
+ it("honors an explicit limit and scans the most recent sessions, not the oldest", async () => {
+ const { sdk, kv } = await setup();
+ // Sessions 0-2 are the oldest and share a file pair that would form a
+ // co_change pattern (needs 3+ co-occurrences) if they were scanned.
+ // Sessions 3-9 are newer and touch no files, so they never contribute
+ // to that pattern. limit: 3 must select the 3 newest sessions (7, 8,
+ // 9), which have no files, so the shared-old-session pattern must not
+ // appear in the result.
+ for (let i = 0; i < 3; i++) {
+ const s = session(i);
+ await kv.set(KV.sessions, s.id, s);
+ await kv.set(
+ KV.observations(s.id),
+ `obs_${s.id}`,
+ observation(`obs_${s.id}`, ["hot_a.ts", "hot_b.ts"]),
+ );
+ }
+ for (let i = 3; i < 10; i++) {
+ const s = session(i);
+ await kv.set(KV.sessions, s.id, s);
+ await kv.set(
+ KV.observations(s.id),
+ `obs_${s.id}`,
+ observation(`obs_${s.id}`, []),
+ );
+ }
+
+ const result = (await sdk.trigger("mem::patterns", {
+ limit: 3,
+ })) as PatternsResult;
+
+ expect(result.sessionLimit).toBe(3);
+ expect(result.sessionsInScope).toBe(3);
+ expect(result.sessionsProcessed).toBe(3);
+ expect(
+ result.patterns.some((p) => p.files.includes("hot_a.ts")),
+ ).toBe(false);
+ });
+
+ it("clamps an out-of-range limit to 500", async () => {
+ const { sdk, kv } = await setup();
+ await seedSessions(kv, 5, 0);
+
+ const result = (await sdk.trigger("mem::patterns", {
+ limit: 1_000_000,
+ })) as PatternsResult;
+
+ expect(result.sessionLimit).toBe(500);
+ expect(result.sessionsInScope).toBe(5);
+ });
+
+ it("does not floor a positive fractional limit down to zero sessions", async () => {
+ const { sdk, kv } = await setup();
+ await seedSessions(kv, 5, 0);
+
+ const result = (await sdk.trigger("mem::patterns", {
+ limit: 0.5,
+ })) as PatternsResult;
+
+ expect(result.sessionLimit).toBeGreaterThanOrEqual(1);
+ expect(result.sessionsInScope).toBeGreaterThan(0);
+ });
+
+ it("applies the project filter before the recency limit", async () => {
+ const { sdk, kv } = await setup();
+ for (let i = 0; i < 5; i++) {
+ const s = session(i, "alpha");
+ await kv.set(KV.sessions, s.id, s);
+ }
+ for (let i = 5; i < 10; i++) {
+ const s = session(i, "beta");
+ await kv.set(KV.sessions, s.id, s);
+ }
+
+ const result = (await sdk.trigger("mem::patterns", {
+ project: "alpha",
+ limit: 50,
+ })) as PatternsResult;
+
+ expect(result.sessionsInScope).toBe(5);
+ });
+
+ it("stops scanning early once MAX_OBSERVATIONS_SCANNED is crossed, even inside the session limit", async () => {
+ const { sdk, kv } = await setup();
+ const totalSessions = 11;
+ const obsPerSession = 501;
+ await seedSessions(kv, totalSessions, obsPerSession);
+
+ const result = (await sdk.trigger("mem::patterns", {
+ limit: 50,
+ })) as PatternsResult;
+
+ expect(result.sessionsInScope).toBe(totalSessions);
+ expect(result.sessionsProcessed).toBeLessThan(totalSessions);
+ expect(result.observationsScanned).toBeGreaterThanOrEqual(5_000);
+ expect(result.observationsScanned).toBeLessThan(
+ totalSessions * obsPerSession,
+ );
+ });
+
+ it("caps work at the budget when a single session holds more observations than the budget", async () => {
+ const { sdk, kv } = await setup();
+ await seedSessions(kv, 1, 6_000);
+
+ const result = (await sdk.trigger("mem::patterns", {
+ limit: 50,
+ })) as PatternsResult;
+
+ expect(result.sessionsProcessed).toBe(1);
+ expect(result.observationsScanned).toBe(5_000);
+ });
+
+ it("skips a session whose observationCount exceeds the remaining budget instead of listing it", async () => {
+ const { sdk, kv } = await setup();
+
+ const huge = session(0);
+ huge.observationCount = 6_000;
+ await kv.set(KV.sessions, huge.id, huge);
+ await kv.set(
+ KV.observations(huge.id),
+ `obs_${huge.id}_0`,
+ observation(`obs_${huge.id}_0`, ["huge.ts"]),
+ );
+
+ const small = session(1);
+ small.observationCount = 1;
+ await kv.set(KV.sessions, small.id, small);
+ await kv.set(
+ KV.observations(small.id),
+ `obs_${small.id}_0`,
+ observation(`obs_${small.id}_0`, ["small.ts"]),
+ );
+
+ const listSpy = vi.spyOn(kv, "list");
+
+ const result = (await sdk.trigger("mem::patterns", {})) as PatternsResult;
+
+ expect(result.sessionsSkipped).toEqual([huge.id]);
+ expect(result.sessionsProcessed).toBe(1);
+ expect(
+ listSpy.mock.calls.some((c) => c[0] === KV.observations(huge.id)),
+ ).toBe(false);
+ });
+
+ it("fills a batch only while the sessions' combined observationCount fits the remaining budget", async () => {
+ const { sdk, kv } = await setup();
+ const perSession = 3_000;
+ const seeded: Session[] = [];
+ for (let i = 0; i < 3; i++) {
+ const s = session(i);
+ s.observationCount = perSession;
+ await kv.set(KV.sessions, s.id, s);
+ for (let j = 0; j < perSession; j++) {
+ await kv.set(
+ KV.observations(s.id),
+ `obs_${s.id}_${j}`,
+ observation(`obs_${s.id}_${j}`, [`only_${s.id}.ts`]),
+ );
+ }
+ seeded.push(s);
+ }
+ const newest = seeded[2];
+
+ const listSpy = vi.spyOn(kv, "list");
+
+ const result = (await sdk.trigger("mem::patterns", {})) as PatternsResult;
+
+ const observationScopesListed = listSpy.mock.calls
+ .map((c) => c[0])
+ .filter((scope) => scope !== KV.sessions);
+ expect(observationScopesListed).toEqual([KV.observations(newest.id)]);
+ expect(result.observationsScanned).toBe(perSession);
+ expect(result.sessionsProcessed).toBe(1);
+ expect(result.sessionsSkipped).toEqual([seeded[1].id, seeded[0].id]);
+ });
+
+ it("does not throw when mem::patterns is invoked with no payload", async () => {
+ const { sdk, kv } = await setup();
+ await seedSessions(kv, 2, 1);
+
+ const result = (await sdk.trigger("mem::patterns", undefined)) as PatternsResult;
+
+ expect(result.sessionLimit).toBe(50);
+ expect(result.sessionsInScope).toBe(2);
+ expect(result.sessionsSkipped).toEqual([]);
+ });
+});