MCP memory_prompt: support session-only and long_term_search modes

[nkanu17]

Summary

Adds include_long_term_search parameter to the MCP memory_prompt tool so it can express the three modes that the REST API already supports. This addresses the memory_prompt mode gap from #253.

Also fixes a validation bug where distance_threshold was checked unconditionally, causing session-only calls to fail with spurious errors.

Context

The discussion on #251 established that the MCP interface should be intentionally smaller than the REST API. Specifically:

• @abrookins: "The goal of the MCP server is not feature parity with the REST API... The interfaces are intentionally smaller, in part because in practice, LLMs used the larger set of parameters badly."
• @tylerhutcherson: "does it even make sense though to expose some of these params to the LLM?"
• @nkanu17: Hyperparameters should be configured at the server/session level, not by the LLM.

This PR follows that philosophy. It only adds one parameter that LLMs can meaningfully reason about: whether to include long-term search or just use session context.

Admin/operational tools (forget, list sessions, delete working memory, SummaryView CRUD, task polling) are intentionally left as REST-only. These are developer/operator concerns, not decisions an LLM should make.

Problem

The MCP memory_prompt tool always constructed a long-term search payload. It could not express:

• Session-only mode (just retrieve working memory, no long-term search)
• The REST API long_term_search=True shortcut vs explicit search payload

Changes

memory_prompt tool

Added include_long_term_search: bool = True parameter. The tool now supports three modes:

Mode	How to use	When
Session + long-term (default)	Provide session_id, leave include_long_term_search=True	Most common: enrich with both sources
Session-only	Provide session_id, set include_long_term_search=False	Continue a conversation without searching long-term memory
Long-term only	Omit session_id, leave include_long_term_search=True	Search memories without a session

Validation ensures at least one of session_id or include_long_term_search=True is active.

Session ID is intentionally excluded from the long-term search to avoid scoping long-term results to a single session (matching REST behavior).

Validation fix

Moved distance_threshold vs search_mode validation inside the if include_long_term_search: block so it only triggers when the search is actually performed. Previously, session-only calls with unused search params would raise a spurious ValueError.

MCP tool surface changes (from parent PR #265)

This branch builds on #265, which added the following to both search_long_term_memory and memory_prompt:

• Added: event_date, recency_boost, recency_semantic_weight, recency_recency_weight, recency_freshness_weight, recency_novelty_weight, recency_half_life_last_access_days, recency_half_life_created_days, server_side_recency
• Removed from LLM exposure: hybrid_alpha, text_scorer (server-level hyperparameters that LLMs cannot reason about)

These are intentional: search_mode (semantic/keyword/hybrid) has established meanings an LLM can reason about, while hybrid_alpha and text_scorer are tuning knobs best configured at the server level.

What this PR does NOT do

Per the MCP design philosophy discussed in #251:

• Does not add admin/operational tools (forget, sessions, summary views, tasks)
• Does not expand get_working_memory with model/token params
• Does not add namespace injection for tools that were not changed

Testing

• 835 tests passed, 108 skipped
• All 22 MCP tests passed (3 new tests for mode selection)
• Pre-commit clean
• No example updates needed

New tests added

• test_memory_prompt_session_only_mode: Verifies session-only mode omits long_term_search
• test_memory_prompt_session_only_ignores_search_params: Verifies session-only mode does not validate unused search params
• test_memory_prompt_no_session_no_search_raises: Verifies error when neither session nor search is active

Related

• Partially addresses Align MCP and LLM-facing client surfaces with core search and memory_prompt capabilities #253 (memory_prompt mode gap)
• Builds on fix: forward search params through all paths and clean up LLM interfaces #265 (search param forwarding)
• Supersedes Add missing MCP tools for full REST API parity #267 (closed: scope was too broad)

---

Note

Medium Risk
Changes MCP tool behavior for memory_prompt and long-term search parameter handling, which can affect agent retrieval results and prompt construction. Risk is moderated by added/updated tests and mostly additive, backwards-compatible parameters.

Overview
MCP memory_prompt now supports session-only vs long-term-search modes. Adds include_long_term_search (default True) to allow session+LTM (default), session-only, or LTM-only hydration, and fixes validation so search-only constraints (e.g., distance_threshold) are enforced only when long-term search runs.

Search/tooling updates to reflect multi-mode retrieval. Client tool resolution now forwards search_mode/pagination/optimize_query for search_memory, updates defaults (e.g., max_results), and documentation/SDK examples are refreshed to highlight semantic/keyword/hybrid search and get_or_create_working_memory, with tests added to verify parameter forwarding and new MCP modes.

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

[github-actions]

Code review completed. Found one potential bug related to validation order in the memory_prompt function.

---

🤖 Automated review complete. Please react with 👍 or 👎 on the individual review comments to provide feedback on their usefulness.

[github-actions]

Bug: Validation runs unconditionally before checking include_long_term_search

The validation for distance_threshold compatibility with search_mode occurs at lines 779-782, but this happens before checking whether include_long_term_search=True (line 808). This means if a user calls memory_prompt with:

memory_prompt(
    query="test",
    session_id={"eq": "session123"},
    include_long_term_search=False,
    distance_threshold=0.8,
    search_mode="keyword"
)

They will get an error "distance_threshold is only supported for semantic search mode" even though distance_threshold won't be used since long-term search is disabled.

Suggested fix:

Move the validation inside the if include_long_term_search: block (after line 808) so it only validates when the parameters will actually be used:

if include_long_term_search:
    # Validate distance_threshold only when doing long-term search
    if distance_threshold is not None and search_mode != SearchModeEnum.SEMANTIC:
        raise ValueError(
            "distance_threshold is only supported for semantic search mode"
        )
    
    # Build search payload...
    search_payload = SearchRequest(
        text=query,
        # ...
    )

This matches the pattern used in search_long_term_memory at lines 603-606, where the validation happens right before the parameters are used.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16884348a9

ℹ️ 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".

[Copilot]

Pull request overview

This PR updates the MCP memory_prompt tool to support session-only hydration (no long-term search) and improves parity with the server’s existing search modes, while also updating client/tooling and docs to consistently describe semantic/keyword/hybrid search.

Changes:

• Add include_long_term_search to MCP memory_prompt to allow session-only vs session+long-term vs long-term-only modes.
• Forward search_mode (and additional search controls) through MCP and client tool-resolution paths; remove LLM exposure to hybrid_alpha/text_scorer where intended.
• Update SDK/docs/examples and add/adjust tests to reflect semantic/keyword/hybrid search support.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
agent_memory_server/mcp.py	Adds include_long_term_search mode selection to memory_prompt, updates namespace injection target, and expands/adjusts MCP search parameter handling.
agent_memory_server/api.py	Docstring clarification for optimize_query semantics across search modes.
agent-memory-client/agent_memory_client/client.py	Forwards additional tool-call args (search_mode, offset, optimize_query), aligns defaults, and expands hydrate_memory_prompt filter forwarding.
agent-memory-client/agent_memory_client/integrations/langchain.py	Adds search_mode to the LangChain search_memory tool wrapper and updates tool description.
tests/test_mcp.py	Extends MCP parameter-passing assertions to verify search_mode forwarding.
tests/test_client_tool_calls.py	Adds regression test ensuring search_mode is forwarded via resolve_function_call and hyperparams are not.
agent-memory-client/tests/test_langchain_integration.py	Adds test ensuring LangChain tool forwards search_mode and omits hyperparams.
README.md	Updates feature/architecture wording to include semantic/keyword/hybrid search.
examples/README.md	Updates example descriptions to mention semantic/keyword/hybrid search.
docs/README.md	Updates feature matrix wording to include semantic/keyword/hybrid search.
docs/mcp.md	Updates MCP docs to describe semantic/keyword/hybrid search modes.
docs/quick-start.md	Updates quick-start narrative to mention keyword and hybrid search.
docs/long-term-memory.md	Expands long-term memory docs to describe semantic/keyword/hybrid search and indexing.
docs/typescript-sdk.md	Adds keyword/hybrid search examples to TS SDK docs.
docs/java-sdk.md	Adds keyword/hybrid search examples to Java SDK docs.
agent-memory-client/README.md	Updates client README examples for get_or_create_working_memory and adds keyword/hybrid search examples.
agent-memory-client/agent-memory-client-js/README.md	Adds keyword/hybrid search examples and clarifies default semantic mode.
docs/index.md	Updates marketing text to mention semantic/keyword/hybrid search.
docs/use-cases.md	Updates guidance text to include keyword/hybrid search alongside semantic.
docs/agent-examples.md	Updates example bullets and corrects working-memory method usage in code sample.

---

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