fix: forward search params through all paths and clean up LLM interfaces

[nkanu17]

Summary

Forward search_mode, offset, and optimize_query through all search paths (resolve_tool_call, MCP tools, hydrate_memory_prompt). Remove hybrid_alpha and text_scorer from LLM-facing interfaces since these are server-level hyperparameters.

This is Part 2 of 2 PRs split from #251. It builds on #264 (docs). After #264 merges, retarget this PR to main.

Changes

Search param forwarding

• Forward search_mode, offset, optimize_query in _resolve_search_memory
• Add search_mode param to MCP memory_prompt and search_long_term_memory
• Add search_mode and hybrid_alpha to hydrate_memory_prompt (developer API)
• Align max_results default from 5 to 10 in _resolve_search_memory
• Add distance_threshold validation for non-semantic search modes

LLM interface cleanup

• Remove hybrid_alpha and text_scorer from MCP tool signatures
• Remove hybrid_alpha and text_scorer from client tool schemas
• Remove hybrid_alpha and text_scorer from LangChain integration
• Keep these params in developer-facing hydrate_memory_prompt where developers can set them explicitly

Deprecated ref and docstring fixes

• Fix stale function names in tool descriptions (search_memory to search_memory_tool, get_working_memory to get_or_create_working_memory)
• Correct optimize_query docstrings in API and MCP
• Make error message name-agnostic in client

MCP docs

• Update docs/mcp.md to reference keyword and hybrid search modes

Tests

• Add test: search_mode flows through resolve_function_call correctly
• Add test: search_mode flows through LangChain tool correctly
• Both tests verify hybrid_alpha/text_scorer are NOT in tool schemas
• Update MCP parameter passing test assertions

Files Changed (8)

• agent-memory-client/agent_memory_client/client.py (param forwarding, tool schema, deprecated refs)
• agent-memory-client/agent_memory_client/integrations/langchain.py (remove hyperparams)
• agent_memory_server/mcp.py (add search_mode, remove hyperparams, fix docstrings)
• agent_memory_server/api.py (fix optimize_query docstring)
• docs/mcp.md (search mode docs)
• tests/test_client_tool_calls.py (new: search_mode forwarding test)
• tests/test_mcp.py (updated: param passing assertions)
• agent-memory-client/tests/test_langchain_integration.py (new: search_mode forwarding test)

Design Decision

Per discussion on #251:

• @nkanu17: Hyperparameters like alpha, recency, and scorer config should be set at the server/session level, not by the LLM
• @abrookins: MCP interface is intentionally smaller than REST API. LLMs can reason about search mode selection but struggle with arbitrary numeric tuning values
• @tylerhutcherson: Questioned whether LLMs should toggle these params, leading to the decision to expose only search_mode
• @vishal-bala: Cataloged full MCP/REST gaps in Align MCP and LLM-facing client surfaces with core search and memory_prompt capabilities #253; remaining items are out of scope for this PR

Refs: #251 (superseded by #264 and this PR), #253 (tracking issue for remaining MCP/REST gaps)

---

Note

Medium Risk
Medium risk because it changes tool/MCP/LangChain function signatures and default search behavior (e.g., max_results default), which can affect downstream integrations and search results across clients.

Overview
Ensures long-term memory search options are forwarded consistently across client tool-call resolution, LangChain tools, MCP tools, and hydrate_memory_prompt, including search_mode, pagination (offset), and optimize_query.

Simplifies LLM-facing interfaces by removing tuning knobs like hybrid_alpha and text_scorer from tool schemas/MCP/LangChain while keeping hybrid configuration server/developer-side, and tightens validation so distance_threshold is only allowed in semantic mode.

Cleans up tool/docs wording (deprecated get_working_memory, renamed lazy/eager create tool descriptions, updated optimize_query docs) and adds/updates tests to verify search_mode is forwarded and removed params are not exposed.

^{Written by Cursor Bugbot for commit 668691c. This will update automatically on new commits. Configure here.}

[nkanu17]

@codex review

[github-actions]

Code review completed. The PR effectively forwards search parameters through all paths while cleaning up LLM-facing interfaces. The validation logic for distance_threshold has been applied correctly and consistently. No issues found.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 668691c1f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve positional argument order in hydrate_memory_prompt

Inserting search_mode, hybrid_alpha, and text_scorer before limit, offset, and optimize_query changes the positional calling contract of this public client method. Any existing caller using positional args (e.g., passing limit/offset positionally) will now bind those values to search_mode/hybrid_alpha instead, which can produce invalid payloads (such as search_mode="5") and 4xx errors at runtime. To avoid a silent breaking change, keep new optional params after the old ones or make these options keyword-only.

Useful? React with 👍 / 👎.