feat: Add content preview mode to reduce search context usage (v0.7.0) (#83)

* feat: Add content preview mode to reduce search context usage (v0.7.0)

**Problem:**
- Search results returned full memory content, causing context overload
- 10 results with 2000 chars each = 20,000+ chars consumed immediately
- Inconsistent behavior between STM (full content) and LTM (truncated to 500)

**Solution:**
- Add `preview_length` parameter to search_memory and search_unified
- Default to 300 characters (90% reduction in context usage)
- Configurable via CORTEXGRAPH_SEARCH_PREVIEW_LENGTH env var
- Full content available by passing `preview_length=0`

**Changes:**
- config.py: Add `search_default_preview_length` config (default: 300)
- search.py: Add `preview_length` parameter and `_truncate_content()` helper
- search_unified.py: Add `preview_length` parameter with consistent truncation
- Both tools now apply preview consistently across STM and LTM results

**Benefits:**
- 90% reduction in context usage for typical searches
- Consistent truncation behavior across all search types
- User can opt-in to full content when needed
- Backward compatible (just changes default behavior)

**Testing:**
- Standalone tests verify truncation logic (6 test cases)
- Config validation ensures preview_length in valid range (0-5000)
- Type checking passes (mypy)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* test: Fix mocked config in embedding tests for preview_length

Three tests in test_tools_search.py were failing in CI because they mock
get_config() but didn't include the new search_default_preview_length
property added in the content preview feature.

Fixed tests:
- test_search_with_embeddings (line 310)
- test_search_embeddings_disabled (line 336)
- test_search_embedding_import_error (line 354)

Each now includes:
mock_config.return_value.search_default_preview_length = 300

This resolves all 9 CI failures (3 OSes × 3 Python versions).

---------

Co-authored-by: Prefrontal Systems <prefrontalsys@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

src/cortexgraph/config.py

@@ -276,6 +276,12 @@ class Config(BaseModel):
         description="Weight for LTM results in unified search",
         ge=0,
     )
+    search_default_preview_length: int = Field(
+        default=300,
+        description="Default number of characters to return in search results (0 = full content)",
+        ge=0,
+        le=5000,
+    )
 
     # Legacy Integration (deprecated) — removed
     basic_memory_path: Path | None | None = None
@@ -439,6 +445,8 @@ def from_env(cls) -> "Config":
             config_dict["search_stm_weight"] = float(search_stm_weight)
         if search_ltm_weight := os.getenv("SEARCH_LTM_WEIGHT"):
             config_dict["search_ltm_weight"] = float(search_ltm_weight)
+        if search_preview_length := os.getenv("CORTEXGRAPH_SEARCH_PREVIEW_LENGTH"):
+            config_dict["search_default_preview_length"] = int(search_preview_length)
 
         # Legacy Integration (ignored)
 

src/cortexgraph/tools/search.py

@@ -72,6 +72,23 @@ def _generate_query_embedding(query: str) -> list[float] | None:
         return None
 
 
+def _truncate_content(content: str, max_length: int | None) -> str:
+    """
+    Truncate content to specified length with ellipsis.
+
+    Args:
+        content: The content to truncate.
+        max_length: Maximum length (None or 0 = no truncation).
+
+    Returns:
+        Truncated content with "..." appended if truncated.
+    """
+    if max_length is None or max_length == 0 or len(content) <= max_length:
+        return content
+
+    return content[:max_length].rstrip() + "..."
+
+
 @mcp.tool()
 @time_operation("search_memory")
 def search_memory(
@@ -84,6 +101,7 @@ def search_memory(
     include_review_candidates: bool = True,
     page: int | None = None,
     page_size: int | None = None,
+    preview_length: int | None = None,
 ) -> dict[str, Any]:
     """
     Search for memories with optional filters and scoring.
@@ -92,6 +110,10 @@ def search_memory(
     for review into results when they're relevant. This creates the "Maslow
     effect" - natural reinforcement through conversation.
 
+    **Content Preview (v0.7.0):** By default, returns first 300 characters of each
+    memory to reduce context usage. Pass `preview_length=0` for full content, or
+    set a custom length (1-5000 characters).
+
     **Pagination:** Results are paginated to help you find specific memories across
     large result sets. Use `page` and `page_size` to navigate through results.
     If a search term isn't found on the first page, increment `page` to see more results.
@@ -106,6 +128,7 @@ def search_memory(
         include_review_candidates: Blend in memories due for review (default True).
         page: Page number to retrieve (1-indexed, default: 1).
         page_size: Number of memories per page (default: 10, max: 100).
+        preview_length: Content preview length in chars (default: 300, 0 = full content).
 
     Returns:
         Dictionary with paginated results including:
@@ -115,14 +138,14 @@ def search_memory(
         Some results may be review candidates that benefit from reinforcement.
 
     Examples:
-        # Get first page (10 results)
+        # Get first page with previews (default 300 chars)
         search_memory(query="authentication", page=1, page_size=10)
 
-        # Get next page
-        search_memory(query="authentication", page=2, page_size=10)
+        # Get full content
+        search_memory(query="authentication", preview_length=0)
 
-        # Larger page size
-        search_memory(query="authentication", page=1, page_size=25)
+        # Custom preview length
+        search_memory(query="authentication", preview_length=500)
 
     Raises:
         ValueError: If any input fails validation.
@@ -148,10 +171,21 @@ def search_memory(
     if min_score is not None:
         min_score = validate_score(min_score, "min_score")
 
+    # Validate preview_length
+    if preview_length is not None:
+        preview_length = validate_positive_int(
+            preview_length, "preview_length", min_value=0, max_value=5000
+        )
+
     # Only validate pagination if explicitly requested
     pagination_requested = page is not None or page_size is not None
 
     config = get_config()
+
+    # Use config default if preview_length not specified
+    if preview_length is None:
+        preview_length = config.search_default_preview_length
+
     now = int(time.time())
 
     memories = db.search_memories(
@@ -263,7 +297,7 @@ def search_memory(
             "results": [
                 {
                     "id": r.memory.id,
-                    "content": r.memory.content,
+                    "content": _truncate_content(r.memory.content, preview_length),
                     "tags": r.memory.meta.tags,
                     "score": round(r.score, 4),
                     "similarity": round(r.similarity, 4) if r.similarity else None,
@@ -286,7 +320,7 @@ def search_memory(
             "results": [
                 {
                     "id": r.memory.id,
-                    "content": r.memory.content,
+                    "content": _truncate_content(r.memory.content, preview_length),
                     "tags": r.memory.meta.tags,
                     "score": round(r.score, 4),
                     "similarity": round(r.similarity, 4) if r.similarity else None,

src/cortexgraph/tools/search_unified.py

@@ -20,6 +20,23 @@
 from ..storage.ltm_index import LTMIndex
 
 
+def _truncate_content(content: str, max_length: int | None) -> str:
+    """
+    Truncate content to specified length with ellipsis.
+
+    Args:
+        content: The content to truncate.
+        max_length: Maximum length (None or 0 = no truncation).
+
+    Returns:
+        Truncated content with "..." appended if truncated.
+    """
+    if max_length is None or max_length == 0 or len(content) <= max_length:
+        return content
+
+    return content[:max_length].rstrip() + "..."
+
+
 class UnifiedSearchResult:
     """Result from unified search across STM and LTM."""
 
@@ -72,10 +89,15 @@ def search_unified(
     min_score: float | None = None,
     page: int | None = None,
     page_size: int | None = None,
+    preview_length: int | None = None,
 ) -> dict[str, Any]:
     """
     Search across both STM and LTM with unified ranking.
 
+    **Content Preview (v0.7.0):** By default, returns first 300 characters of each
+    memory to reduce context usage. Pass `preview_length=0` for full content, or
+    set a custom length (1-5000 characters).
+
     **Pagination:** Results are paginated to help you find specific memories across
     large result sets from both short-term and long-term memory. Use `page` and `page_size`
     to navigate through results. If a search term isn't found on the first page,
@@ -91,18 +113,19 @@ def search_unified(
         min_score: Minimum score threshold for STM memories (0.0-1.0).
         page: Page number to retrieve (1-indexed, default: 1).
         page_size: Number of memories per page (default: 10, max: 100).
+        preview_length: Content preview length in chars (default: 300, 0 = full content).
 
     Returns:
         Dictionary with paginated results including:
         - results: List of matching memories from STM and LTM for current page
         - pagination: Metadata (page, page_size, total_count, total_pages, has_more)
 
     Examples:
-        # Get first page (10 results)
+        # Get first page with previews (default 300 chars)
         search_unified(query="architecture", page=1, page_size=10)
 
-        # Get next page
-        search_unified(query="architecture", page=2, page_size=10)
+        # Get full content
+        search_unified(query="architecture", preview_length=0)
 
     Raises:
         ValueError: If any input fails validation.
@@ -129,10 +152,21 @@ def search_unified(
     if min_score is not None:
         min_score = validate_score(min_score, "min_score")
 
+    # Validate preview_length
+    if preview_length is not None:
+        preview_length = validate_positive_int(
+            preview_length, "preview_length", min_value=0, max_value=5000
+        )
+
     # Only validate pagination if explicitly requested
     pagination_requested = page is not None or page_size is not None
 
     config = get_config()
+
+    # Use config default if preview_length not specified
+    if preview_length is None:
+        preview_length = config.search_default_preview_length
+
     results: list[UnifiedSearchResult] = []
 
     # Search STM
@@ -154,7 +188,7 @@ def search_unified(
 
             results.append(
                 UnifiedSearchResult(
-                    content=memory.content,
+                    content=_truncate_content(memory.content, preview_length),
                     title=f"Memory {memory.id[:8]}",
                     source="stm",
                     score=score * stm_weight,
@@ -203,7 +237,7 @@ def search_unified(
 
                     results.append(
                         UnifiedSearchResult(
-                            content=doc.content[:500],
+                            content=_truncate_content(doc.content, preview_length),
                             title=doc.title,
                             source="ltm",
                             score=relevance_score * ltm_weight,

tests/test_tools_search.py

@@ -307,6 +307,7 @@ def test_search_with_embeddings(self, mock_transformer, mock_config, temp_storag
         # Setup mocks
         mock_config.return_value.enable_embeddings = True
         mock_config.return_value.embed_model = "test-model"
+        mock_config.return_value.search_default_preview_length = 300
         mock_model = MagicMock()
         mock_embedding = MagicMock()
         mock_embedding.tolist.return_value = [0.1, 0.2, 0.3]
@@ -332,6 +333,7 @@ def test_search_with_embeddings(self, mock_transformer, mock_config, temp_storag
     def test_search_embeddings_disabled(self, mock_config, temp_storage):
         """Test that embeddings not used when disabled."""
         mock_config.return_value.enable_embeddings = False
+        mock_config.return_value.search_default_preview_length = 300
 
         mem = Memory(id="mem-1", content="Test", embed=[0.1, 0.2])
         temp_storage.save_memory(mem)
@@ -349,6 +351,7 @@ def test_search_embeddings_disabled(self, mock_config, temp_storage):
     def test_search_embedding_import_error(self, mock_transformer, mock_config, temp_storage):
         """Test graceful handling of embedding import errors."""
         mock_config.return_value.enable_embeddings = True
+        mock_config.return_value.search_default_preview_length = 300
         mock_transformer.side_effect = ImportError("No model")
 
         mem = Memory(id=make_test_uuid("mem-1"), content="Test")