fix: forward hybrid/keyword search params through all search paths and update docs

[nkanu17]

Ensure search_mode, hybrid_alpha, and text_scorer parameters are forwarded through every search path in the system, and update documentation to accurately reflect hybrid and keyword search capabilities.

Fixes

• Hybrid/keyword search params silently dropped (3 paths)
• client.py _resolve_search_memory: resolve_tool_call() accepted search_mode, hybrid_alpha, text_scorer from LLM tool calls but never passed them to search_memory_tool() - all LLM-initiated searches silently defaulted to semantic.
• mcp.py memory_prompt: Missing all three params in function signature and SearchRequest construction - MCP prompt hydration was locked to semantic search.
• client.py hydrate_memory_prompt: Missing all three params - convenience method couldn't use keyword or hybrid search.
• Fixed tuple unpacking order: memory, created → created, memory to match tuple[bool, WorkingMemory] return type.
• Removed dead MemoryNotFoundError catch from get_or_create_working_memory example (method creates instead of raising).
• _resolve_search_memory defaulted max_results to 5 but the tool schema and search_memory_tool signature both use 10 - changed to 10

Documentation & Description Fixes

• Updated all SDK docs (Python, TypeScript, Java, JS) to reference keyword and hybrid search.
• Changed "exact term matching" → "full-text matching" in 4 files (keyword search uses BM25, not exact matching).
• Changed "vector search" → search-mode-agnostic language in tool schema descriptions and docstrings.
• Updated deprecated tool/function references (get_working_memory → get_or_create_working_memory, add_memory_to_working_memory → lazily_create_long_term_memory).
• Clarified feature bullet: "Flexible search: semantic (vector embeddings), keyword (full-text), and hybrid (combined)".
• LangChain search_mode parameter changed from str to Literal["semantic", "keyword", "hybrid"] for better LLM schema generation.

Tool schema updates (shown to LLMs):

• agent-memory-client/agent_memory_client/client.py: search_memory tool description
• agent-memory-client/agent_memory_client/integrations/langchain.py: LangChain tool description

Path	Status
MCP search_long_term_memory	Already forwards all 3 params
REST API search_long_term_memory	Already forwards via SearchRequest model
REST API memory_prompt	Already forwards via SearchRequest model
Client search_long_term_memory	Already forwards all 3 params
Client search_memory_tool	Already forwards all 3 params
Client memory_prompt	Dict passthrough - params flow if included
long_term_memory.py core search	Already accepts and uses all 3 params

---

Note

Medium Risk
Behavior changes in long-term memory retrieval: LLM tool calls and MCP memory_prompt now honor search_mode/hybrid_alpha/text_scorer, which can change returned context and ranking; otherwise changes are mostly documentation and schema wording.

Overview
Fixes several paths where keyword/hybrid search parameters were accepted but silently dropped, ensuring search_mode, hybrid_alpha, text_scorer, pagination, and optimize_query are forwarded consistently through the Python client tool resolver (_resolve_search_memory), the client convenience prompt hydrator (hydrate_memory_prompt), and the MCP memory_prompt tool.

Updates tool schemas/docstrings and SDK docs to describe semantic/keyword/hybrid search and clarify optimize_query applies only to semantic search; also refreshes examples to use get_or_create_working_memory semantics and aligns defaults (e.g., max_results to 10) with the published tool schema.

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

[github-actions]

Review completed. No suggestions at this time.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[Copilot]

Pull request overview

Updates repo documentation and LLM-facing tool descriptions so “search” is described consistently as supporting semantic, keyword, and hybrid modes (instead of only semantic), aligning docs/SDK examples with the server’s supported search_mode behavior.

Changes:

• Expanded documentation references from “semantic search” to “semantic, keyword, and hybrid search” across guides and examples.
• Added/updated SDK usage examples (TypeScript/JS, Java, Python client README) to demonstrate keyword and hybrid search modes (including hybridAlpha/hybrid_alpha).
• Updated LLM tool descriptions in the Python client and LangChain integration to mention the additional search modes.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates feature list and architecture text to include keyword/hybrid search.
docs/index.md	Updates high-level marketing/feature bullets to include keyword/hybrid search.
docs/long-term-memory.md	Expands long-term memory overview and adds explicit semantic/keyword/hybrid sections and JSON examples.
docs/mcp.md	Updates MCP tool descriptions for long-term memory search modes.
docs/quick-start.md	Updates narrative/checklist language to include keyword/hybrid search.
docs/use-cases.md	Updates best-practice bullet to reference semantic/keyword/hybrid search + filters.
docs/README.md	Updates feature cross-reference row to call out semantic/keyword/hybrid search.
docs/agent-examples.md	Updates travel agent description to include keyword/hybrid search capabilities.
docs/java-sdk.md	Adds keyword and hybrid search request examples.
docs/typescript-sdk.md	Adds keyword and hybrid search examples using searchMode/hybridAlpha.
examples/README.md	Updates travel agent feature bullet to include keyword/hybrid search.
agent-memory-client/README.md	Adds Python client examples for keyword and hybrid search.
agent-memory-client/agent-memory-client-js/README.md	Adds JS client examples for keyword and hybrid search and clarifies default semantic mode.
agent-memory-client/agent_memory_client/client.py	Updates search_memory tool schema description to mention keyword/hybrid modes.
agent-memory-client/agent_memory_client/integrations/langchain.py	Updates LangChain tool description to mention keyword/hybrid modes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

agent-memory-client/agent_memory_client/client.py:2707

• Newly supported tool-call parameters (search_mode, hybrid_alpha, text_scorer) in _resolve_search_memory aren’t covered by existing tool-call resolution tests (e.g., tests/test_client_tool_calls.py only exercises query/max_results). Adding a test that calls resolve_function_call/resolve_tool_call with these fields and asserts they’re passed into search_memory_tool() would prevent regressions (including the silent-dropping issue fixed in this PR).

        search_mode = args.get("search_mode", "semantic")
        hybrid_alpha = args.get("hybrid_alpha")
        text_scorer = args.get("text_scorer")

        return await self.search_memory_tool(
            query=query,
            search_mode=search_mode,
            hybrid_alpha=hybrid_alpha,
            text_scorer=text_scorer,
            topics=topics,
            entities=entities,
            memory_type=memory_type,
            max_results=max_results,

agent-memory-client/agent_memory_client/client.py:2709

• _resolve_search_memory forwards search_mode/hybrid_alpha/text_scorer, but it still ignores the tool-call argument optimize_query even though the tool schema exposes it and search_memory_tool() supports it. This means LLM callers can set optimize_query and it will be silently dropped. Consider parsing optimize_query from args and passing it through to search_memory_tool (or removing it from the schema if intentionally unsupported).

        max_results = args.get("max_results", 5)
        min_relevance = args.get("min_relevance")
        user_id = args.get("user_id")
        search_mode = args.get("search_mode", "semantic")
        hybrid_alpha = args.get("hybrid_alpha")
        text_scorer = args.get("text_scorer")

        return await self.search_memory_tool(
            query=query,
            search_mode=search_mode,
            hybrid_alpha=hybrid_alpha,
            text_scorer=text_scorer,
            topics=topics,
            entities=entities,
            memory_type=memory_type,
            max_results=max_results,
            min_relevance=min_relevance,
            user_id=user_id,

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The resolver explicitly supports the deprecated create_long_term_memory alias, but the error message only references eagerly_create_long_term_memory. This can be confusing when the caller invoked the deprecated name. Consider making the error message function-name-agnostic (e.g., just “memories parameter is required”) or mentioning both names.

[Copilot]

Raising a bare ValueError from an MCP tool often surfaces as an unstructured/internal error to tool clients. If the MCP framework supports structured tool errors, prefer raising the project’s standard “bad request”/tool validation exception type so callers reliably get a 4xx-style, user-actionable response.

[Copilot]

This page now advertises keyword/full-text and hybrid search, but the “Storage” and “Indexing” rows still only mention vector indexing/embeddings. Update these rows to reflect that keyword/hybrid require full-text indexing as well (so the capability description matches the underlying implementation expectations).

[vishal-bala]

This is looking good - there are a couple bot comments that are worth covering.

Comparing this to #253, we could expand this PR to cover the rest of the gaps between the MCP and core AMS - tbd whether that larger scope is what we want right away but we can discuss that later.

Cataloging the items from #253 not covered in this PR here:

• MCP memory_prompt still does not expose full SearchRequest parity:
  • event_date
  • recency_*
  • server_side_recency
• MCP search_long_term_memory still does not expose:
  • event_date
  • recency_*
  • server_side_recency
• Namespace injection still targets hydrate_memory_prompt instead of memory_prompt
• MCP memory_prompt still cannot represent all REST modes:
  • session only
  • long_term_search=True
  • explicit long_term_search payload
• MCP get_working_memory still differs from REST:
  • missing namespace, user_id, model_name, context_window_max
  • returns empty session instead of 404 on not found
• Several REST capabilities still have no MCP equivalent:
  • forgetting
  • list sessions
  • delete working memory
  • summary view CRUD/run/list
  • task status
• Python docs/examples still show stale REST-shaped memory_prompt() usage that does not match the current client API
• Test coverage is still missing for:
  • event_date
  • recency controls
  • server_side_recency
  • memory_prompt mode selection
  • namespace injection for memory_prompt

[tylerhutcherson]

Agree with @vishal-bala comments here and on Monday will want @abrookins and @bsbodden input -- we should go ahead and fix all of these gaps. The larger question - does it even make sense though to expose some of these params to the LLM? Like do we expect them to know how to use or toggle them appropriately? What is typical in the industry?

[jit-ci]

❌ Jit Scanner failed - Our team is investigating

Jit Scanner failed - Our team has been notified and is working to resolve the issue. Please contact support if you have any questions.

---

💡 Need to bypass this check? Comment @sera bypass to override.

[nkanu17]

Agree with @vishal-bala comments here and on Monday will want @abrookins and @bsbodden input -- we should go ahead and fix all of these gaps. The larger question - does it even make sense though to expose some of these params to the LLM? Like do we expect them to know how to use or toggle them appropriately? What is typical in the industry?

@tylerhutcherson
I think a lot of these 'hyperparameters', we should let the devs/user configure them through a service config. They should not be pushed to the LLM.

Example:

If a developer wants hybrid search with BM25 and a 0.7 alpha, the alpha, recency config etc. parameters should be configured that at the server/session level and not hope the LLM picks the right values. Hybrid/Semantic is questionable for me but I can see merit in letting the LLM choose. Or split them into different tools. It even makes sense to make hybrid default for search.

[abrookins]

Agree with @vishal-bala comments here and on Monday will want @abrookins and @bsbodden input -- we should go ahead and fix all of these gaps. The larger question - does it even make sense though to expose some of these params to the LLM? Like do we expect them to know how to use or toggle them appropriately? What is typical in the industry?

The goal of the MCP server is not feature parity with the REST API, so I agree in that sense. The interfaces are intentionally smaller, in part because in practice, LLMs used the larger set of parameters badly. LLMs have the most trouble with anything that requires an arbitrary value, such as tags, namespace, etc. LLMs will make up different values at search time than they did when creating, and other gaffs (but also, this makes sense...).

User ID and namespace are not exposed partly for the reason above, but also because you don't want the LLM to control which user's data it sees. Better to "freeze" that into the tool input, which is how the client-side tools work.

Working memory should come out of the MCP interface completely because in practice, it's not a great fit for LLMs in an interactive session. So I'd recommend not adding to it now. My opinion though!

On the other hand, LLMs are smart enough to use inputs when: A) you give them the valid inputs and B) the valid inputs have established meanings outside of the application. Whether or not to use hybrid search (or "exact lookups" or something) vs. pure vector search is something LLMs can reason about and understand. I haven't tested this as much as the other opinions I have, but I think LLMs would be smart enough to use keyword search if the user is trying to find a specific string. It's generally better to expose separate tools instead of too many parameters on one tool, but at the same time, you're balancing token usage and bloat.

[nkanu17]

Closing this PR in favor of two smaller, stacked PRs for easier review:

• docs: add hybrid and keyword search references across documentation #264 - docs: add hybrid and keyword search references across documentation (docs/READMEs only, no code changes)
• fix: forward search params through all paths and clean up LLM interfaces #265 - fix: forward search params through all paths and clean up LLM interfaces (code, tests, MCP docs)

These two PRs together cover everything in this PR. #265 builds on #264 and should be merged after it.

Remaining MCP/REST gaps (event_date, recency controls, namespace injection, missing MCP equivalents, etc.) are tracked in #253.