feat: return excerpts from memory.list / memory.search, full text via memory.get #28

Merged
jknapp merged 1 commits from feat/memory-snippets-in-search-list into main 2026-11-14 19:07:11 +00:00
Owner

Why

memory_search and memory_list returned every memory's full body. That's fine with a handful of short memories, but one search across a few dozen long ones could pour thousands of words into a session's context. Suggested by the claude.ai agent after #27. The memory_get description already said list/search "return summaries"; this makes it true.

What changes

Each memory.list / memory.search item now has these fields instead of content:

field meaning
excerpt ~200 chars, whitespace collapsed, cut on word boundaries. Search: the passage matching the most query terms (stopwords ignored). List, or a meaning-only search hit with no query word in the text: the memory's opening.
contentLength full body length, so the caller can tell a short note from a long document
truncated false means the excerpt is the whole memory, so no memory_get is needed
  • full: true on either tool returns the whole content instead.
  • Ids, tags, scope, project, version, timestamps and search ranks are unchanged.
  • memory.get is unchanged.
  • The web UI calls searchMemories directly, so it's unaffected.
  • The field is named excerpt rather than snippet so it isn't confused with the snippet.* tools.
  • Tool descriptions now point callers to memory.get for full bodies.

Example excerpt from a real memory, for the query "founding partner program":

…x86 and ARM64 with identical features. Founding Partner Program: first 10 hosts get 90 days free on 1 server. Marketing video pipeline (tested 2026-11-14): ElevenLabs stock voice "David" for…

Compatibility

This changes the response shape: callers that read content from list/search results now get excerpt, unless they pass full: true. Agents get their instructions from the updated tool descriptions, which point to memory.get.

Tests

  • lib/memory-excerpt.test.ts: 8 unit tests for the excerpt helper (short content, whitespace collapsing, word boundaries, query-centred window, best multi-term window, stopwords and case, no-match fallback, match near the end).
  • tools.integration.test.ts: 5 new tests. List and search return excerpt, contentLength and truncated with no content; the long body isn't in the text block; search excerpts the matched passage; full: true returns the whole body on both tools; memory.get still returns the full text.
  • Full suite: 88 passing. Typecheck and lint are clean.

🤖 Generated with Claude Code

## Why `memory_search` and `memory_list` returned every memory's full body. That's fine with a handful of short memories, but one search across a few dozen long ones could pour thousands of words into a session's context. Suggested by the claude.ai agent after #27. The `memory_get` description already said list/search "return summaries"; this makes it true. ## What changes Each `memory.list` / `memory.search` item now has these fields instead of `content`: | field | meaning | |---|---| | `excerpt` | ~200 chars, whitespace collapsed, cut on word boundaries. **Search:** the passage matching the most query terms (stopwords ignored). **List**, or a meaning-only search hit with no query word in the text: the memory's opening. | | `contentLength` | full body length, so the caller can tell a short note from a long document | | `truncated` | `false` means the excerpt *is* the whole memory, so no `memory_get` is needed | - `full: true` on either tool returns the whole `content` instead. - Ids, tags, scope, project, version, timestamps and search ranks are unchanged. - `memory.get` is unchanged. - The web UI calls `searchMemories` directly, so it's unaffected. - The field is named `excerpt` rather than `snippet` so it isn't confused with the `snippet.*` tools. - Tool descriptions now point callers to `memory.get` for full bodies. Example excerpt from a real memory, for the query "founding partner program": > …x86 and ARM64 with identical features. Founding Partner Program: first 10 hosts get 90 days free on 1 server. Marketing video pipeline (tested 2026-11-14): ElevenLabs stock voice "David" for… ## Compatibility This changes the response shape: callers that read `content` from list/search results now get `excerpt`, unless they pass `full: true`. Agents get their instructions from the updated tool descriptions, which point to `memory.get`. ## Tests - `lib/memory-excerpt.test.ts`: 8 unit tests for the excerpt helper (short content, whitespace collapsing, word boundaries, query-centred window, best multi-term window, stopwords and case, no-match fallback, match near the end). - `tools.integration.test.ts`: 5 new tests. List and search return excerpt, `contentLength` and `truncated` with no `content`; the long body isn't in the text block; search excerpts the matched passage; `full: true` returns the whole body on both tools; `memory.get` still returns the full text. - Full suite: 88 passing. Typecheck and lint are clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
jknapp added 1 commit 2026-11-14 19:03:45 +00:00
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>
jknapp merged commit b032a0b721 into main 2026-11-14 19:07:11 +00:00
jknapp deleted branch feat/memory-snippets-in-search-list 2026-11-14 19:07:11 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: cybercove-labs/shared-memory#28