feat(mcp-search): add compact mode for search results #299

New issue

Closed

opened 2026-01-25 17:21:09 +00:00 by jack · 0 comments

jack commented

2026-01-25 17:21:09 +00:00

Owner

Problem

Search results can become very large when returning many items, causing output to exceed token limits:

Error: result (114,975 characters) exceeds maximum allowed tokens.

A search with 44 items generated ~115k characters because each item includes all fields:

text (full observation text)
narrative (detailed narrative)
concepts (JSON array)
facts (JSON array)
files_read (JSON array)
files_modified (JSON array)
And many more metadata fields

Proposed Solution

Add a compact or fields parameter to the search endpoint:

Option A: Compact Mode

search({ query: "...", compact: true })

Returns only essential fields:

id
title
subtitle
type
created_at
project

Option B: Field Selection

search({ query: "...", fields: ["id", "title", "type", "created_at"] })

Allows explicit field selection.

Benefits

Faster responses
Lower token usage
Better for overview/list use cases
Full details can still be fetched via get_observations for specific IDs

Implementation Notes

Default behavior should remain unchanged for backwards compatibility
Consider making compact: true the default for large result sets (e.g., >20 items)

## Problem Search results can become very large when returning many items, causing output to exceed token limits: ``` Error: result (114,975 characters) exceeds maximum allowed tokens. ``` A search with 44 items generated ~115k characters because each item includes all fields: - `text` (full observation text) - `narrative` (detailed narrative) - `concepts` (JSON array) - `facts` (JSON array) - `files_read` (JSON array) - `files_modified` (JSON array) - And many more metadata fields ## Proposed Solution Add a `compact` or `fields` parameter to the search endpoint: ### Option A: Compact Mode ```typescript search({ query: "...", compact: true }) ``` Returns only essential fields: - `id` - `title` - `subtitle` - `type` - `created_at` - `project` ### Option B: Field Selection ```typescript search({ query: "...", fields: ["id", "title", "type", "created_at"] }) ``` Allows explicit field selection. ## Benefits - Faster responses - Lower token usage - Better for overview/list use cases - Full details can still be fetched via `get_observations` for specific IDs ## Implementation Notes - Default behavior should remain unchanged for backwards compatibility - Consider making `compact: true` the default for large result sets (e.g., >20 items)