feat: Add new toolset for OpenSearch Agentic Memory API #138

oujezdsky · 2025-11-17T01:19:07Z

Description

This pull request introduces a set of 7 new tools to support the OpenSearch Agentic Memory API (released in 3.3). This allows agents using the MCP server to create, manage, and interact with agentic memories.

Key changes include:

New Tools: Adds CreateAgenticMemoryContainerTool, CreateAgenticMemorySessionTool, AddAgenticMemoriesTool, GetAgenticMemoryTool, UpdateAgenticMemoryArgsTool, DeleteAgenticMemoryByIDTool, DeleteAgenticMemoryByQueryTool, and SearchAgenticMemoryTool.
Pydantic Models: Implements Pydantic V2 models for all new tool arguments.
Async Implementation: The core logic is implemented as async helper functions in src/opensearch/helper.py.
Error Handling: Introduces a new HelperOperationError to provide better, contextualized error logging.
Testing: Adds a set of unit tests for the new tools, using pytest.mark.parametrize for all happy paths and pytest.raises for Pydantic validation.

Issues Resolved

Closes #113

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

…uster_name param Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

…Tool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

…moryTool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky · 2025-11-18T19:13:28Z

Hello,

This PR is ready for review again.

5 new commits that address issues:

Fixed packaging by moving exceptions.py.
Added compatibility checks to all Agentic Memory tools.
Corrected naming for UpdateAgenticMemoryTool (in code and CHANGELOG).
Fixed CreateAgenticMemoryContainerTool validation by changing the strategy field from invalid strategy_type to the correct type.

Thank you for the review and apologies for the inconvenience.

rithin-pullela-aws · 2025-11-18T19:39:24Z

Hi @oujezdsky thanks for the PR!

Few high level thoughts before I review the PR:

Can we fix the failing tests?
Can we add the tools in Readme and Userguide?
Looks like the tool_params.py and tool.py have a lot of lines of code added. Can we create separate files for agentic_memory related tools and import the tools into tools.py ? I believe this would make the code more readable

oujezdsky · 2025-11-18T20:09:39Z

Hello @rithin-pullela-aws,
Yes, I will look at the failed tests ~~(seemed OK in my dev env.)~~ and at the separation of agentic_memory tools.

Regarding the Readme and Userguide—no problem, I’ll add the new tools there as well.
I originally thought it was outside the scope of this issue, and I had a similar assumption about adding the new AM tools to src/tools/tool_filter.py, specifically inside process_tool_filter() function and its core_tools. Without that, opensearch-mcp-server-py won’t detect them. Should I add them there as well?

~~And if so, would you prefer that I include them directly in core_tools, or should I create a separate group like agentic_memory_tools and follow the same pattern used for core_tools?~~

thanks

…Tool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky · 2025-11-19T12:36:02Z

This PR has been updated to address all comments and is now ready for re-review.

Refactoring and Readability
- Solution: All Agentic Memory implementation logic (functions, Pydantic models, constants) has been extracted from the large files (tools.py and tool_params.py) into a new, dedicated Python package: src/tools/agentic_memory/.
- This package now segregates logic into actions.py and data models into params.py.
Fixing Failing Tests (Version Compatibility)
- Problem: The new tools required OpenSearch 3.3.0+, but the existing test class (TestTools) was mocked to version 2.19.0 in its setup_method. The check_tool_compatibility function correctly raised an incompatibility error, causing all Agentic Memory tests to fail.
- Solution: To fix this without affecting the current test environment, I have isolated all Agentic Memory tests into a new file: tests/tools/test_agentic_memory_tools.py. The test class within this file now defines its own isolated setup_method, mocking the OpenSearch version as 3.3.0. This ensures the new feature is tested against the correct version while preserving the existing test baseline.
Documentation Updates (README & User Guide)
- README.md: Updated the "Available Tools" section, adding the full list of Agentic Memory tools and their parameter definitions.
- USER_GUIDE.md: Added a new chapter "Agentic Memory Usage" with a detailed 5-step workflow (Create, Session, Add, Search, Update/Delete) using the "Vacation Planner" example.

nathaliellenaa

Thanks for raising this PR @oujezdsky! Added some comments

nathaliellenaa · 2025-11-19T23:55:00Z

CHANGELOG.md


 ### Fixed
 - Fix AWS auth issues for cat based tools, pin OpenSearchPy to 2.18.0 ([#135](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/135))
+- Add new toolset for the OpenSearch Agentic Memory API: `CreateAgenticMemoryContainerTool`, `CreateAgenticMemorySessionTool`, `AddAgenticMemoriesTool`, `GetAgenticMemoryTool`, `UpdateAgenticMemoryTool`, `DeleteAgenticMemoryByIDTool`, `DeleteAgenticMemoryByQueryTool`, and `SearchAgenticMemoryTool`. ([#113](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/138))


Suggested change

- Add new toolset for the OpenSearch Agentic Memory API: `CreateAgenticMemoryContainerTool`, `CreateAgenticMemorySessionTool`, `AddAgenticMemoriesTool`, `GetAgenticMemoryTool`, `UpdateAgenticMemoryTool`, `DeleteAgenticMemoryByIDTool`, `DeleteAgenticMemoryByQueryTool`, and `SearchAgenticMemoryTool`. ([#113](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/138))

- Add new toolset for the OpenSearch Agentic Memory API: `CreateAgenticMemoryContainerTool`, `CreateAgenticMemorySessionTool`, `AddAgenticMemoriesTool`, `GetAgenticMemoryTool`, `UpdateAgenticMemoryTool`, `DeleteAgenticMemoryByIDTool`, `DeleteAgenticMemoryByQueryTool`, and `SearchAgenticMemoryTool`. ([#138](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/138))

nathaliellenaa · 2025-11-20T00:04:54Z

README.md

+  - `messages` (conditional): A list of messages. Required when `payload_type` is `conversational`. *(Body Parameter)*
+  - `structured_data` (conditional): Structured data content. Required when `payload_type` is `data`. *(Body Parameter)*
+  - `binary_data` (optional): 	Binary data content encoded as a Base64 string for binary payloads. *(Body Parameter)*
+  - `payload_type` (required): The type of payload. Valid values are `conversational` or `data`. See [See Payload types](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#payload-types). *(Body Parameter)*


Suggested change

- `payload_type` (required): The type of payload. Valid values are `conversational` or `data`. See [See Payload types](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#payload-types). *(Body Parameter)*

- `payload_type` (required): The type of payload. Valid values are `conversational` or `data`. See [Payload types](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#payload-types). *(Body Parameter)*

nathaliellenaa · 2025-11-20T00:05:17Z

README.md

+  - `namespace` (optional): The [namespace](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#namespaces) context for organizing memories (for example, `user_id`, `session_id`, or `agent_id`). If `session_id` is not specified in the namespace field and `disable_session`: `false` (default is `true`), a new session with a new session ID is created. *(Body Parameter)*
+  - `metadata` (optional): Additional metadata for the memory (for example, `status`, `branch`, or custom fields). *(Body Parameter)*
+  - `tags` (optional): Tags for categorizing memories. *(Body Parameter)*
+  - `infer` (optional): Whether to use an LLM to extract key information (default: `false`). When `true`, the LLM extracts key information from the original text and stores it as a memory. [See Inference mode](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#inference-mode). *(Body Parameter)*


Suggested change

- `infer` (optional): Whether to use an LLM to extract key information (default: `false`). When `true`, the LLM extracts key information from the original text and stores it as a memory. [See Inference mode](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#inference-mode). *(Body Parameter)*

- `infer` (optional): Whether to use an LLM to extract key information (default: `false`). When `true`, the LLM extracts key information from the original text and stores it as a memory. See [Inference mode](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#inference-mode). *(Body Parameter)*

nathaliellenaa · 2025-11-20T00:16:44Z

src/opensearch/helper.py

+    """Create a new agentic memory session in the specified memory container.
+
+    Args:
+        args: CreateSessionArgs containing memory_container_id and optional session_id, summary, metadata, namespace


Nit:

Suggested change

args: CreateSessionArgs containing memory_container_id and optional session_id, summary, metadata, namespace

args: CreateAgenticMemorySessionArgs containing memory_container_id and optional session_id, summary, metadata, namespace

nathaliellenaa · 2025-11-20T00:26:13Z

src/tools/agentic_memory/actions.py

+        return [{'type': 'text', 'text': f'Error updating memory: {str(error_to_report)}'}]
+
+
+async def delete_agentic_memoryby_ID_tool(


Function name be should be delete_agentic_memory_by_id_tool to make it consistent with other function names

nathaliellenaa · 2025-11-20T00:32:42Z

src/tools/agentic_memory/actions.py

+        if container_id:
+            message = f'Successfully created memory container. ID: {container_id}. Response: {json.dumps(result)}'
+        else:
+            message = (
+                f'Memory container created, but no ID was returned. Response: {json.dumps(result)}'
+            )


Should we keep a consistent message formatting? We can follow the format in create_agentic_memory_session_tool, for example

message = ( f'Successfully created memory container. ID: {container_id}. Response: {json.dumps(result)}' if container_id else f'Memory container created, but no ID was returned. Response: {json.dumps(result)}' )

nathaliellenaa · 2025-11-20T00:40:05Z

src/tools/agentic_memory/params.py

+    @model_validator(mode='after')
+    def validate_embedding_configuration(self) -> 'AgenticMemoryConfigurationArgs':
+        """Validate embedding model configuration."""
+        if self.embedding_model_type == 'TEXT_EMBEDDING' and self.embedding_dimension is None:


Can we do if self.embedding_model_type == EmbeddingModelType.text_embedding?

nathaliellenaa · 2025-11-20T00:57:56Z

src/tools/tools.py

+        'function': create_agentic_memory_session_tool,
+        'args_model': CreateAgenticMemorySessionArgs,
+        'min_version': '3.3.0',  # Agentic memory APIs requires OpenSearch 3.3+
+        'http_methods': 'UPDATE',


The http_methods should be the actual REST API method being called, so in this case it should be POST. The same should be applied for the other agentic memory tools

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

…tency Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky · 2025-11-20T12:24:39Z

@nathaliellenaa Thanks for the feedback! I've addressed all the comments.

jiapingzeng · 2025-11-24T21:11:01Z

Thanks for the PR! Overall the changes look good to me from a tools perspective.

One question is that when using these MCP tools with an agent, e.g. Claude desktop or Q/Kiro CLI, is it able to recognize that it needs to create a container before it can use the other Agentic Memory tools? Or would the user need to guide it through prompt to create container then add/get/update/delete memory?

oujezdsky added 14 commits November 17, 2025 00:22

Add tool params for memory tools

b8d5667

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Added handlers and tools for memory tools

2c988a4

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Escape user-provided path params

a1fe93b

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Improve JSON type annotations

656f1ba

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Fixed HTTP method for memory search, POST -> GET

4c0e5b7

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Added custom Exception handler, utilized in new memory tools

76a8ee2

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Helper functions reworked

949339f

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

tools functions and tool params reworked

0df7063

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

tests added

84bcec8

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

fixed issues so it works with updated baseToolArgs with opensearch_cl…

bae565a

…uster_name param Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

correctly await async calls in agentic memory helpers

07aa465

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

apply ruff formatting to agentic memory feature files

7ea5480

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

apply ruff check to agentic memory feature files

d2a1a66

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

docs: Update CHANGELOG for Agentic Memory tools

ae99d0d

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky marked this pull request as draft November 18, 2025 14:43

oujezdsky added 5 commits November 18, 2025 15:49

fix(packaging): Move exceptions.py to tools package to fix installation

00d1d98

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

Add compatibility checks to Agentic Memory tools

35dd1aa

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

fix(tools): Rename UpdateAgenticMemoryArgsTool to UpdateAgenticMemory…

114daed

…Tool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

fix(tools) Correct agentic memory strategy type field naming

c18323d

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

fix(CHANGELOG): Rename UpdateAgenticMemoryArgsTool to UpdateAgenticMe…

ab4fd94

…moryTool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky marked this pull request as ready for review November 18, 2025 19:05

oujezdsky marked this pull request as draft November 18, 2025 20:10

oujezdsky added 4 commits November 18, 2025 21:22

fix(tools): Rename UpdateAgenticMemoryArgsTool to UpdateAgenticMemory…

f383a72

…Tool Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

refactor(tools): extract Agentic Memory tools to dedicated package

714b60c

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

test(agentic-memory): isolate tests and fix OpenSearch 3.3 mocking

96e63f6

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

docs(agentic-memory): document tools, parameters, and usage examples

fdbd609

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

oujezdsky marked this pull request as ready for review November 19, 2025 12:36

nathaliellenaa reviewed Nov 20, 2025

View reviewed changes

oujezdsky added 6 commits November 20, 2025 12:26

docs(agentic-memory): apply review feedback to README and CHANGELOG

dd903e5

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

fix(agentic-memory): correct http_methods in TOOL_REGISTRY

3e15fee

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

style(agentic-memory): fix naming inconsistency

745433b

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

refactor(params, tests): prefer Enums over string literals for consis…

5496009

…tency Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

refactor(actions): consistent message formatting

7180cb4

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

style(agentic-memory): reorder components for consistency

3bed692

Signed-off-by: Jiri Oujezdsky <oujezdsky2@gmail.com>

	- Add new toolset for the OpenSearch Agentic Memory API: `CreateAgenticMemoryContainerTool`, `CreateAgenticMemorySessionTool`, `AddAgenticMemoriesTool`, `GetAgenticMemoryTool`, `UpdateAgenticMemoryTool`, `DeleteAgenticMemoryByIDTool`, `DeleteAgenticMemoryByQueryTool`, and `SearchAgenticMemoryTool`. ([#113](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/138))
	- Add new toolset for the OpenSearch Agentic Memory API: `CreateAgenticMemoryContainerTool`, `CreateAgenticMemorySessionTool`, `AddAgenticMemoriesTool`, `GetAgenticMemoryTool`, `UpdateAgenticMemoryTool`, `DeleteAgenticMemoryByIDTool`, `DeleteAgenticMemoryByQueryTool`, and `SearchAgenticMemoryTool`. ([#138](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/138))

	- `payload_type` (required): The type of payload. Valid values are `conversational` or `data`. See [See Payload types](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#payload-types). (Body Parameter)
	- `payload_type` (required): The type of payload. Valid values are `conversational` or `data`. See [Payload types](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#payload-types). (Body Parameter)

	- `infer` (optional): Whether to use an LLM to extract key information (default: `false`). When `true`, the LLM extracts key information from the original text and stores it as a memory. [See Inference mode](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#inference-mode). (Body Parameter)
	- `infer` (optional): Whether to use an LLM to extract key information (default: `false`). When `true`, the LLM extracts key information from the original text and stores it as a memory. See [Inference mode](https://docs.opensearch.org/latest/ml-commons-plugin/agentic-memory/#inference-mode). (Body Parameter)

	args: CreateSessionArgs containing memory_container_id and optional session_id, summary, metadata, namespace
	args: CreateAgenticMemorySessionArgs containing memory_container_id and optional session_id, summary, metadata, namespace

		return [{'type': 'text', 'text': f'Error updating memory: {str(error_to_report)}'}]


		async def delete_agentic_memoryby_ID_tool(

feat: Add new toolset for OpenSearch Agentic Memory API #138

Are you sure you want to change the base?

feat: Add new toolset for OpenSearch Agentic Memory API #138

Conversation

oujezdsky commented Nov 17, 2025

Description

Issues Resolved

Uh oh!

oujezdsky commented Nov 18, 2025

Uh oh!

rithin-pullela-aws commented Nov 18, 2025

Uh oh!

oujezdsky commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oujezdsky commented Nov 19, 2025

Uh oh!

nathaliellenaa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oujezdsky commented Nov 20, 2025

Uh oh!

jiapingzeng commented Nov 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

oujezdsky commented Nov 18, 2025 •

edited

Loading