[upstream PR 223] feat(smart-search): add format parameter (full/narrative/compact) | 添加 format 参数

[wbugitlab1]

Source: Source pull request number: 223 in rohitg00/agentmemory (URL omitted to avoid GitHub cross-reference)
Title: feat(smart-search): add format parameter (full/narrative/compact) | 添加 format 参数
Author: mechanic-Q
State: open
Draft: no
Merged: no
Head: mechanic-Q/agentmemory:feature/smart-search-format @ 26519fa
Base: main @ 1c8713f
Labels: (none)
Changed files: 0
Commits: 0
Created: 2026-05-02T06:49:16Z
Updated: 2026-05-17T09:42:42Z
Closed: (not closed)
Merged at: (not merged)

Original PR body:

Summary | 概述

Add format parameter to mem::smart-search to align with mem::search, which already supports format-aware output (full / compact / narrative).

为 mem::smart-search 添加 format 参数，与已有的 mem::search 格式体系对齐（支持 full / compact / narrative 三种输出模式）。

Motivation | 动机

When using agentmemory with Hermes Agent and other MCP clients in a real-world workflow, we found that memory_smart_search (which calls mem::smart-search) is the primary search tool exposed to LLMs. However it only returned compact results — obsId, title, type, score. For the LLM to actually use the search results, it needs to see the narrative field (the human-readable summary of each observation).

Without this, every smart-search call required a follow-up expandIds round-trip just to read the narratives — doubling latency and token usage. Meanwhile memory_search (mem::search) already had format support. This inconsistency meant integrators had to choose between the smarter hybrid search OR readable results, but couldn't have both.

本补丁来自实际使用 agentmemory + Hermes Agent 的体验：memory_smart_search 是 LLM 使用的主要搜索工具，但只返回 compact 格式（obsId/title/type/score），LLM 无法直接读取记忆的 narrative 内容。每次搜索都需要额外 expandIds 调用来获取正文，导致延迟翻倍。而 memory_search 已有 format 支持。这个不一致让集成分叉——要么用智能搜索，要么用可读结果，无法兼得。

Problem | 问题

mem::search supports a format parameter (full | compact | narrative) that controls the richness of returned results. mem::smart-search was hardcoded to compact-only output, creating an inconsistency between the two search functions.

Changes | 改动

• Added format?: string to the input type (defaults to "compact" for backwards compatibility)
• Three format modes:
  • compact — minimal: obsId, sessionId, title, type, score, timestamp (existing behavior)
  • narrative — adds narrative field for LLM consumption (replaces the expandIds round-trip)
  • full — complete observation object with all fields
• Validates format against allowed values, returns error for invalid input
• Removes unused CompactSearchResult import

Backwards Compatibility | 向后兼容

Default format is "compact", preserving existing behavior. All existing callers work without changes.

Related | 相关

mem::search format implementation: src/functions/search.ts L82-84

Local branch:
Fork PR:
Fork decision:
Verification:
Notes: