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 <noreply@anthropic.com>
This commit is contained in:
1 parent
3d43c40609
commit
a1cdfae0bd
5 files changed
+283
-9
No files matched your search
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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<T extends { content: string }>(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,
|
||||
},
|
||||
];
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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,
|
||||
};
|
||||
}
|
||||
@@ -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<typeof MemoryListInput>;
|
||||
|
||||
@@ -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<typeof MemorySearchInput>;
|
||||
|
||||
|
||||
Reference in new issue
Block a user