#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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([]);+ });+});