From a1cdfae0bdf491dad7b5ffb7103771ce0680b2e1 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Sat, 14 Nov 2026 11:03:33 -0800 Subject: [PATCH] feat: return excerpts from memory.list / memory.search, full text via memory.get Both tools returned every memory's full body, so one search across a few dozen long memories could pour thousands of words into the caller's context. The memory.get description already promised that list/search "return summaries"; this makes it true. Each list/search item now carries, instead of `content`: - `excerpt`: ~200 chars, whitespace collapsed, cut on word boundaries. For search it is the window matching the most distinct query terms (stopwords ignored); for list, or a meaning-only hit with no term in the text, it is the memory's opening. - `contentLength` and `truncated`, so the caller can tell a short note (excerpt is the whole thing) from a long document worth a memory.get. `full: true` on either tool restores the whole `content`. Ids, tags, scope, project, version, timestamps and search ranks are unchanged. memory.get is unchanged. The web UI calls searchMemories directly and is unaffected. Named `excerpt`, not `snippet`, to avoid confusion with the snippet.* tools. Tool descriptions now point callers at memory.get for full bodies. Co-Authored-By: Claude Opus 5.5 --- apps/web/lib/mcp/tools.integration.test.ts | 86 ++++++++++++++++++- apps/web/lib/mcp/tools.ts | 39 +++++++-- apps/web/lib/memory-excerpt.test.ts | 56 ++++++++++++ apps/web/lib/memory-excerpt.ts | 99 ++++++++++++++++++++++ packages/schemas/src/index.ts | 12 +++ 5 files changed, 283 insertions(+), 9 deletions(-) create mode 100644 apps/web/lib/memory-excerpt.test.ts create mode 100644 apps/web/lib/memory-excerpt.ts diff --git a/apps/web/lib/mcp/tools.integration.test.ts b/apps/web/lib/mcp/tools.integration.test.ts index 13beab7..cbdc935 100644 --- a/apps/web/lib/mcp/tools.integration.test.ts +++ b/apps/web/lib/mcp/tools.integration.test.ts @@ -115,7 +115,7 @@ describe("memory.get response shape (P1)", () => { expect(fields).not.toContain("contentTsv"); }); - test("returns exactly the same 9 fields as memory.list", async () => { + test("returns exactly the 9 memory fields, including the full content", async () => { const res = await toolMap["memory.get"]!.handler({ id: memoryId }, ctx); const fields = Object.keys(res.structuredContent as object).sort(); @@ -269,14 +269,14 @@ describe("tool results carry their payload in the text content (claude.ai)", () const firstText = (res: ToolResultLike) => res.content[0]!.text; type ToolResultLike = { content: Array<{ text: string }>; isError?: boolean }; - test("memory.list text includes each memory's id and content", async () => { + test("memory.list text includes each memory's id and an excerpt", async () => { const res = await toolMap["memory.list"]!.handler({ project: "test-project" }, ctx); expect(res.isError).toBeUndefined(); expect(firstText(res)).toContain(memoryId); expect(firstText(res)).toContain("## RECENTLY SHIPPED"); }); - test("memory.search text includes the hit's id, content and rank", async () => { + test("memory.search text includes the hit's id, an excerpt and rank", async () => { const res = await toolMap["memory.search"]!.handler( { query: "roadmap patch primitive", project: "test-project" }, ctx, @@ -319,3 +319,83 @@ describe("tool results carry their payload in the text content (claude.ai)", () ); }); }); + +/** + * memory.list / memory.search return an excerpt instead of the full body, + * so a search across dozens of long memories doesn't flood the caller's + * context. memory.get (or `full: true`) returns the whole text. + */ +describe("memory.list / memory.search return excerpts, not full bodies", () => { + const LONG = + "Opening summary line. " + + "filler ".repeat(400) + + "The kumquat marmalade decision was made here. " + + "filler ".repeat(400); + + type Item = { + id: string; + excerpt: string; + contentLength: number; + truncated: boolean; + content?: string; + tags: string[]; + }; + const itemsOf = (res: { structuredContent?: unknown }) => + (res.structuredContent as { items: Item[] }).items; + + test("memory.list returns excerpt + contentLength + truncated, and no content", async () => { + const longId = await seedMemory(LONG); + const res = await toolMap["memory.list"]!.handler({ project: "test-project" }, ctx); + const item = itemsOf(res).find((i) => i.id === longId)!; + + expect(item.content).toBeUndefined(); + expect(item.contentLength).toBe(LONG.length); + expect(item.truncated).toBe(true); + expect(item.excerpt.startsWith("Opening summary line.")).toBe(true); + expect(item.excerpt.length).toBeLessThanOrEqual(202); + expect(item.tags).toEqual(["roadmap"]); + // The text block the client renders doesn't carry the body either. + expect(res.content[0]!.text).not.toContain("filler ".repeat(50)); + }); + + test("a short memory's excerpt is the whole thing and not truncated", async () => { + const res = await toolMap["memory.list"]!.handler({ project: "test-project" }, ctx); + const item = itemsOf(res).find((i) => i.id === memoryId)!; + expect(item.truncated).toBe(false); + expect(item.excerpt).toBe(ORIGINAL.replace(/\s+/g, " ").trim()); + }); + + test("memory.search excerpts the passage that matched the query", async () => { + const longId = await seedMemory(LONG); + const res = await toolMap["memory.search"]!.handler( + { query: "kumquat marmalade", project: "test-project" }, + ctx, + ); + const item = itemsOf(res).find((i) => i.id === longId)!; + + expect(item.content).toBeUndefined(); + expect(item.truncated).toBe(true); + expect(item.contentLength).toBe(LONG.length); + expect(item.excerpt).toContain("kumquat marmalade decision"); + expect((item as unknown as { _rank: { rrfScore: number } })._rank.rrfScore).toBeGreaterThan(0); + }); + + test("full: true returns the whole content on both tools", async () => { + const longId = await seedMemory(LONG); + + const list = await toolMap["memory.list"]!.handler({ project: "test-project", full: true }, ctx); + expect(itemsOf(list).find((i) => i.id === longId)!.content).toBe(LONG); + + const search = await toolMap["memory.search"]!.handler( + { query: "kumquat marmalade", project: "test-project", full: true }, + ctx, + ); + expect(itemsOf(search).find((i) => i.id === longId)!.content).toBe(LONG); + }); + + test("memory.get still returns the full content", async () => { + const longId = await seedMemory(LONG); + const res = await toolMap["memory.get"]!.handler({ id: longId }, ctx); + expect((res.structuredContent as { content: string }).content).toBe(LONG); + }); +}); diff --git a/apps/web/lib/mcp/tools.ts b/apps/web/lib/mcp/tools.ts index 30c33a7..046ada1 100644 --- a/apps/web/lib/mcp/tools.ts +++ b/apps/web/lib/mcp/tools.ts @@ -22,6 +22,7 @@ import { SnippetDeleteInput, } from "@shared-memory/schemas"; import { searchMemories } from "@/lib/memories"; +import { makeExcerpt } from "@/lib/memory-excerpt"; import { createMemory, patchMemory, @@ -82,6 +83,19 @@ function ok(structured: unknown, summary: string): ToolResult { }; } +/** + * Shape a memory row for memory.list / memory.search. By default the full + * `content` is replaced with a short `excerpt` (the passage matching + * `query` when there is one, else the opening), plus `contentLength` and + * `truncated` so the caller can tell whether memory.get is worth calling. + * `full` keeps the whole `content` instead. + */ +function withExcerpt(row: T, full: boolean, query?: string) { + const { content, ...rest } = row; + if (full) return { ...rest, content, contentLength: content.length }; + return { ...rest, ...makeExcerpt(content, query), contentLength: content.length }; +} + function err(message: string): ToolResult { return { content: [{ type: "text", text: `error: ${message}` }], @@ -428,7 +442,7 @@ const memoryWrite: ToolDef = { const memoryList: ToolDef = { name: "memory.list", description: - "Browse memories chronologically — useful at session start to load all relevant project context when there's no specific search query. Prefer memory.search when you have a specific question to answer; use list when you just want recent context. Filter by project, scope, or tags. Limit defaults to 50.", + "Browse memories chronologically — useful at session start to load all relevant project context when there's no specific search query. Prefer memory.search when you have a specific question to answer; use list when you just want recent context. Filter by project, scope, or tags. Limit defaults to 50. Each item carries a ~200-char `excerpt` (the opening of the memory), `contentLength`, and `truncated` — NOT the full body. Call memory.get with the id for the full text of anything that looks relevant (or pass `full: true` to get every body, which can be very large).", inputSchema: { type: "object", properties: { @@ -440,6 +454,12 @@ const memoryList: ToolDef = { description: "Require all of these tags.", }, limit: { type: "integer", minimum: 1, maximum: 200, default: 50 }, + full: { + type: "boolean", + default: false, + description: + "Return each memory's full `content` instead of a ~200-char `excerpt`. Leave off unless you need every body — prefer memory.get on the hits you care about.", + }, }, }, async handler(args, ctx) { @@ -491,14 +511,15 @@ const memoryList: ToolDef = { .orderBy(desc(memories.createdAt)) .limit(parsed.data.limit); - return ok({ items: rows, next_cursor: null }, `${rows.length} result(s)`); + const items = rows.map((r) => withExcerpt(r, parsed.data.full)); + return ok({ items, next_cursor: null }, `${items.length} result(s)`); }, }; const memoryGet: ToolDef = { name: "memory.get", description: - "Fetch the full content of a single memory by its UUID. Use after memory.search or memory.list when you need the full body — list/search return summaries.", + "Fetch the full content of a single memory by its UUID. Use after memory.search or memory.list when you need the full body — those return only a short `excerpt` per memory (check `truncated` / `contentLength` to see how much was left out).", inputSchema: { type: "object", properties: { id: { type: "string", format: "uuid" } }, @@ -661,7 +682,7 @@ const memoryPatch: ToolDef = { const memorySearch: ToolDef = { name: "memory.search", description: - "Search this user's stored memories BEFORE answering any question that might depend on something they told you in a past conversation — their preferences, infrastructure choices, project decisions, references, ongoing initiatives. Also call at the start of work on a known project to load semantic context. The query should be the topic you're looking up in natural language — don't pre-keyword it. Combines vector similarity, Postgres full-text, and tag overlap via RRF; each result carries per-source rank so you can tell whether the hit is a strong semantic match or a weak vector-only one. Cheap; lean toward calling it.", + "Search this user's stored memories BEFORE answering any question that might depend on something they told you in a past conversation — their preferences, infrastructure choices, project decisions, references, ongoing initiatives. Also call at the start of work on a known project to load semantic context. The query should be the topic you're looking up in natural language — don't pre-keyword it. Combines vector similarity, Postgres full-text, and tag overlap via RRF; each result carries per-source rank so you can tell whether the hit is a strong semantic match or a weak vector-only one. Each result carries a ~200-char `excerpt` — the passage that best matches your query, or the memory's opening for a meaning-only match — plus `contentLength` and `truncated`, NOT the full body. Call memory.get with the id for the full text of the hits you need (or pass `full: true` to get every body). Cheap; lean toward calling it.", inputSchema: { type: "object", properties: { @@ -677,6 +698,12 @@ const memorySearch: ToolDef = { description: "Optional minimum Reciprocal Rank Fusion score for a hit to be returned. Default unset = no extra filter (every fused result returned). Set ~0.025 to require at least two rankers (vector + FTS, or +tag) to fire at rank 1, filtering out weak vector-only matches. The per-source ranks in each result are still the primary way to judge confidence.", }, + full: { + type: "boolean", + default: false, + description: + "Return each memory's full `content` instead of a ~200-char `excerpt`. Leave off unless you need every body — prefer memory.get on the hits you care about.", + }, }, required: ["query"], }, @@ -684,7 +711,7 @@ const memorySearch: ToolDef = { const parsed = MemorySearchInput.safeParse(withDefaultProject(args, ctx)); if (!parsed.success) return err(parsed.error.message); - const { query, scope, tags, limit, minScore } = parsed.data; + const { query, scope, tags, limit, minScore, full } = parsed.data; const requestedKey = projectKeyOrDefault(ctx, parsed.data.project); const projectId = requestedKey ? await resolveProjectId(ctx, requestedKey) : null; if (requestedKey && !projectId) { @@ -727,7 +754,7 @@ const memorySearch: ToolDef = { if (!row) return []; return [ { - ...row, + ...withExcerpt(row, full, query), _rank: hit.rank, }, ]; diff --git a/apps/web/lib/memory-excerpt.test.ts b/apps/web/lib/memory-excerpt.test.ts new file mode 100644 index 0000000..60f2c5f --- /dev/null +++ b/apps/web/lib/memory-excerpt.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, test } from "vitest"; +import { EXCERPT_CHARS, makeExcerpt } from "./memory-excerpt"; + +const words = (n: number, w = "filler") => Array.from({ length: n }, () => w).join(" "); + +describe("makeExcerpt", () => { + test("short content comes back whole, not truncated", () => { + expect(makeExcerpt("a short fact")).toEqual({ excerpt: "a short fact", truncated: false }); + }); + + test("collapses whitespace and newlines so the excerpt reads as one line", () => { + expect(makeExcerpt("# Title\n\n- one\n- two\n").excerpt).toBe("# Title - one - two"); + }); + + test("without a query, long content is cut from the start at a word boundary", () => { + const { excerpt, truncated } = makeExcerpt(`opening line ${words(200)}`); + expect(truncated).toBe(true); + expect(excerpt.startsWith("opening line filler")).toBe(true); + expect(excerpt.endsWith("…")).toBe(true); + expect(excerpt.length).toBeLessThanOrEqual(EXCERPT_CHARS + 2); + // Never splits a word: everything before the ellipsis is whole words. + expect(excerpt.slice(0, -1).trim().split(" ").every((w) => ["opening", "line", "filler"].includes(w))).toBe(true); + }); + + test("with a query, centres on the passage that matches it", () => { + const content = `${words(150)} the kumquat marmalade recipe lives here ${words(150)}`; + const { excerpt, truncated } = makeExcerpt(content, "kumquat marmalade"); + expect(truncated).toBe(true); + expect(excerpt).toContain("kumquat marmalade recipe"); + expect(excerpt.startsWith("…")).toBe(true); + expect(excerpt.endsWith("…")).toBe(true); + }); + + test("prefers the window matching the most distinct query terms", () => { + const content = `alpha ${words(100)} beta ${words(100)} alpha beta gamma together ${words(100)}`; + expect(makeExcerpt(content, "alpha beta gamma").excerpt).toContain("alpha beta gamma together"); + }); + + test("matching is case-insensitive and ignores stopwords", () => { + // "the" would otherwise match at position 0 and win. + const content = `the ${words(100)} WHP Launch plan ${words(100)}`; + expect(makeExcerpt(content, "the whp launch").excerpt).toContain("WHP Launch plan"); + }); + + test("falls back to the start when no query term appears (vector-only hit)", () => { + const content = `opening line ${words(200)}`; + expect(makeExcerpt(content, "zebra").excerpt.startsWith("opening line")).toBe(true); + }); + + test("a match near the end still fills the window instead of returning a stub", () => { + const content = `${words(200)} needle`; + const { excerpt } = makeExcerpt(content, "needle"); + expect(excerpt.endsWith("needle")).toBe(true); + expect(excerpt.length).toBeGreaterThan(EXCERPT_CHARS - 20); + }); +}); diff --git a/apps/web/lib/memory-excerpt.ts b/apps/web/lib/memory-excerpt.ts new file mode 100644 index 0000000..03285b3 --- /dev/null +++ b/apps/web/lib/memory-excerpt.ts @@ -0,0 +1,99 @@ +/** + * Short excerpts for memory.list / memory.search results. + * + * Those tools used to return every memory's full body, so one search over + * a few dozen long memories could pour thousands of words into the + * caller's context. They now return an excerpt plus `contentLength` / + * `truncated`, and the caller fetches the whole body with memory.get when + * the excerpt says it's worth it. + * + * With a query, the excerpt is the window matching the most distinct + * query terms (case-insensitive substring match, so "launch" also finds + * "launched"). Without one — or when no term appears, e.g. a vector-only + * hit — it is the start of the memory, which is usually its summary line. + */ + +export const EXCERPT_CHARS = 200; + +/** Context kept before the first matched term so the passage reads naturally. */ +const LEAD_CHARS = 40; +/** Cap on occurrences examined per term, to keep huge memories cheap. */ +const MAX_OCCURRENCES_PER_TERM = 25; + +const STOPWORDS = new Set([ + "the", "and", "for", "are", "but", "not", "you", "all", "any", "can", + "had", "her", "was", "one", "our", "out", "has", "his", "how", "its", + "who", "did", "get", "may", "use", "she", "him", "too", "via", + "that", "this", "with", "from", "they", "have", "what", "when", "where", + "which", "there", "their", "about", "into", "than", "then", "them", + "does", "should", "would", "could", +]); + +export interface Excerpt { + excerpt: string; + /** True when the excerpt is not the whole (whitespace-collapsed) memory. */ + truncated: boolean; +} + +function queryTerms(query: string): string[] { + const terms = query + .toLowerCase() + .split(/[^\p{L}\p{N}]+/u) + .filter((t) => t.length >= 3 && !STOPWORDS.has(t)); + return [...new Set(terms)]; +} + +/** Start offset of the best-matching window, or 0 when nothing matches. */ +function bestWindowStart(lower: string, terms: string[], max: number): number { + let best = 0; + let bestScore = 0; + for (const term of terms) { + let i = -1; + for (let n = 0; n < MAX_OCCURRENCES_PER_TERM; n++) { + i = lower.indexOf(term, i + 1); + if (i === -1) break; + const start = Math.max(0, i - LEAD_CHARS); + const window = lower.slice(start, start + max); + const score = terms.reduce((s, t) => s + (window.includes(t) ? 1 : 0), 0); + if (score > bestScore || (score === bestScore && start < best)) { + best = start; + bestScore = score; + } + } + } + return best; +} + +export function makeExcerpt( + content: string, + query?: string, + max: number = EXCERPT_CHARS, +): Excerpt { + const text = content.replace(/\s+/g, " ").trim(); + if (text.length <= max) return { excerpt: text, truncated: false }; + + const terms = query ? queryTerms(query) : []; + let start = terms.length > 0 ? bestWindowStart(text.toLowerCase(), terms, max) : 0; + + // A match near the end would leave a stub; slide back to fill the window. + start = Math.min(start, text.length - max); + + // Snap the start forward to a word boundary (never mid-word). + if (start > 0 && text[start - 1] !== " ") { + const space = text.indexOf(" ", start); + if (space !== -1 && space - start < 20) start = space + 1; + } + + let end = Math.min(text.length, start + max); + // Snap the end back to a word boundary. + if (end < text.length && text[end] !== " ") { + const space = text.lastIndexOf(" ", end); + if (space > start + max / 2) end = space; + } + + const body = text.slice(start, end).trim(); + return { + excerpt: `${start > 0 ? "…" : ""}${body}${end < text.length ? "…" : ""}`, + truncated: true, + }; +} diff --git a/packages/schemas/src/index.ts b/packages/schemas/src/index.ts index b0c8638..fdddff8 100644 --- a/packages/schemas/src/index.ts +++ b/packages/schemas/src/index.ts @@ -40,6 +40,12 @@ export const MemoryListInput = z.object({ tags: z.array(z.string()).optional(), limit: z.number().int().min(1).max(200).default(50), cursor: z.string().optional(), + /** + * Return each memory's full `content` instead of a short `excerpt`. + * Off by default so a list/search over many long memories stays small; + * memory.get fetches one full body. + */ + full: z.boolean().default(false), }); export type MemoryListInput = z.infer; @@ -113,6 +119,12 @@ export const MemorySearchInput = z.object({ * unfiltered default. */ minScore: z.number().min(0).max(1).optional(), + /** + * Return each memory's full `content` instead of a short `excerpt`. + * Off by default so a list/search over many long memories stays small; + * memory.get fetches one full body. + */ + full: z.boolean().default(false), }); export type MemorySearchInput = z.infer; -- 2.52.0