Feature/mongodb atlas memory tool #281

ayanray089 · 2025-10-09T20:51:44Z

Description

This PR adds a comprehensive MongoDB Atlas Memory tool that provides semantic memory management capabilities using MongoDB Atlas as the backend with vector embeddings for semantic search.

Key Features:

Semantic Search: Automatic embedding generation using Amazon Bedrock Titan for vector similarity search
Memory Management: Store, retrieve, list, get, and delete memory operations
Index Management: Automatic vector search index creation with proper configuration
Namespace Support: Organize memories by namespace for multi-user scenarios
Pagination: Support for paginated results in list and retrieve operations
Error Handling: Comprehensive error handling with clear error messages

Implementation Details:

Uses MongoDB Atlas Vector Search with $vectorSearch aggregation pipeline
Supports Amazon Bedrock Titan v2 embeddings (1024 dimensions, cosine similarity)
Includes namespace-based data isolation for multi-tenant scenarios
Implements pagination support with next_token (skip/limit pattern)
Follows the same action-based interface as elasticsearch_memory (record, retrieve, list, get, delete)

Related Issues

Documentation PR

Type of Change

New Tool

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare
All 27 unit tests pass successfully
Integration tests with real MongoDB Atlas cluster verified functionality
Code formatting and linting checks pass
No breaking changes to existing functionality

Test Coverage:

Complete unit test suite with 27 test functions covering all CRUD operations
Mocking of MongoDB client and Bedrock client for isolated testing
Error handling scenarios, pagination, namespaces, and metadata handling
Integration test with real MongoDB Atlas credentials (kept local)

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

- Implement mongodb_memory.py following elasticsearch_memory.py patterns - Add MongoDB Atlas vector search with Amazon Bedrock Titan v2 embeddings - Support all CRUD operations: record, retrieve, list, get, delete - Include namespace-based data isolation and pagination - Add comprehensive unit tests (27 tests) with full coverage - Update pyproject.toml with pymongo optional dependency - Graceful error handling for vector index creation - Production-ready with proper logging and validation

- Implement mongodb_memory.py following elasticsearch_memory.py design patterns - Add MongoDB Atlas Vector Search with aggregation pipeline - Support Amazon Bedrock Titan v2 embeddings (1024 dimensions, cosine similarity) - Include namespace-based data isolation for multi-tenant scenarios - Add pagination support with next_token (skip/limit pattern) - Comprehensive error handling and logging - Add 27 unit tests covering all CRUD operations and edge cases - Create detailed documentation following elasticsearch_memory_tool.md pattern - Update README.md with MongoDB Atlas Memory usage examples - Add environment variables configuration for MongoDB Atlas - Add mongodb_memory optional dependency to pyproject.toml

- Integration test file contains sensitive credentials and should remain local only

JackYPCOnline · 2025-10-11T05:26:45Z

src/strands_tools/mongodb_memory.py

+DEFAULT_VECTOR_INDEX_NAME = "vector_index"
+
+
+def _ensure_vector_search_index(collection, index_name: str = DEFAULT_VECTOR_INDEX_NAME):


for each parameter we should specify type annotation

JackYPCOnline · 2025-10-11T05:33:57Z

src/strands_tools/mongodb_memory.py

+            logger.info(f"Created vector search index: {index_name}")
+
+            # Wait a moment for index to be ready
+            import time


Why not top

JackYPCOnline · 2025-10-11T05:35:38Z

src/strands_tools/mongodb_memory.py

+        # Don't raise exception - allow the tool to work without vector search
+
+
+def _generate_embedding(bedrock_runtime, text: str, embedding_model: str) -> List[float]:


same here and remaining functions

Also functions shouldn't receive infrastructure dependencies as parameters

src/strands_tools/mongodb_memory.py

JackYPCOnline · 2025-10-11T05:45:10Z

src/strands_tools/mongodb_memory.py

+    skip_count = int(next_token) if next_token else 0
+
+    # Query for memories in namespace
+    cursor = (


question: does this naming consist with other memory tool?

JackYPCOnline · 2025-10-11T05:45:44Z

src/strands_tools/mongodb_memory.py

+    # Query for memories in namespace
+    cursor = (
+        collection.find(
+            {"namespace": namespace}, {"memory_id": 1, "content": 1, "timestamp": 1, "metadata": 1, "_id": 0}


why these numbers are hardcoded?

cagataycali · 2025-10-13T14:43:33Z

README.md

+    action="record",
+    content="User prefers vegetarian pizza with extra cheese",
+    metadata={"category": "food_preferences", "type": "dietary"},
+    cluster_uri="mongodb+srv://user:[email protected]/?retryWrites=true&w=majority",


I believe cluster_uri can be defined upfront (using class based init) so the agents have no access to possible sensitive information like password of cluster

cagataycali · 2025-10-13T14:45:06Z

src/strands_tools/mongodb_memory.py

+            # Wait a moment for index to be ready
+            import time
+
+            time.sleep(2)


I think we can remove the time.sleep(2) from here ^^

cagataycali · 2025-10-13T14:46:17Z

src/strands_tools/mongodb_memory.py

+                "index": index_name,
+                "path": "embedding",
+                "queryVector": query_embedding,
+                "numCandidates": max_results * 3,


Is there a specific reason we're gathering x3 results?

cagataycali · 2025-10-13T14:47:50Z

src/strands_tools/mongodb_memory.py

+                )
+                return {
+                    "status": "success",
+                    "content": [{"text": f"Memories retrieved successfully: {json.dumps(response, default=str)}"}],


We can place the json under "content": [{"json": ..., }] block instead of serializing into text here ^^

- Implement complete MongoDB Atlas memory tool with vector search capabilities - Add semantic search using Amazon Bedrock Titan embeddings (1024 dimensions) - Support full CRUD operations: record, retrieve, list, get, delete - Add namespace support for multi-user memory isolation - Include environment variable configuration support - Add security features including connection string masking - Implement JSON response format optimization - Add comprehensive test suite with 27 test cases covering all functionality - Follow same design principles as existing Elasticsearch memory tool

ayanray089 · 2025-10-13T17:28:42Z

@JackYPCOnline , @cagataycali Addressed all the feedback in the latest commit

JackYPCOnline · 2025-10-14T16:26:40Z

src/strands_tools/mongodb_memory.py

+)
+
+# Create agent with secure tool usage
+agent = Agent(tools=[memory_tool.mongodb_memory])


should be : mongodb_memory

JackYPCOnline · 2025-10-14T16:28:18Z

src/strands_tools/mongodb_memory.py

+from strands_tools.mongodb_memory import MongoDBMemoryTool
+
+# RECOMMENDED: Secure class-based approach (credentials hidden from agents)
+memory_tool = MongoDBMemoryTool(


This example is different from doc. Please keep all docs consitent.

JackYPCOnline · 2025-10-14T16:30:32Z

src/strands_tools/mongodb_memory.py

+
+    try:
+        # Pattern to match mongodb+srv://username:password@host/...
+        import re


JackYPCOnline · 2025-10-14T16:32:45Z

docs/mongodb_memory_tool.md

+result = agent.tool.mongodb_memory(
+    action="record",
+    content="User prefers vegetarian pizza with extra cheese",
+    cluster_uri="mongodb+srv://user:[email protected]/?retryWrites=true&w=majority",


actually we don't need ?retryWrites=true&w=majority

JackYPCOnline · 2025-10-14T16:35:30Z

docs/mongodb_memory_tool.md

+## Prerequisites
+
+1. **MongoDB Atlas**: You need a MongoDB Atlas cluster with:
+   - Connection URI (mongodb+srv format)


Assume user have no knowledge with MongoDB, we should point them where to find this URI.

- Fix documentation examples to use consistent class-based approach - Remove unnecessary query parameters from connection string examples - Add comprehensive MongoDB Atlas connection URI guidance - Add explanatory code comments for numCandidates usage - Ensure all examples follow the same pattern throughout documentation - All 27 unit tests continue to pass - Tested with real MongoDB Atlas credentials successfully

ayanray089 · 2025-10-15T23:10:16Z

@JackYPCOnline Addressed the latest feedback

- Resolve conflicts in README.md by merging MongoDB Atlas Memory Tool and Retrieve Tool sections - Resolve conflicts in pyproject.toml by including both elasticsearch_memory and mongodb_memory dependencies

JackYPCOnline

Please review all files thoroughly to ensure code quality

JackYPCOnline · 2025-10-22T16:24:30Z

README.md

+    action="record",
+    content="User prefers vegetarian pizza with extra cheese",
+    metadata={"category": "food_preferences", "type": "dietary"},
+    cluster_uri="mongodb+srv://user:[email protected]/?retryWrites=true&w=majority",


we dont need ?retryWrites=true&w=majority and all other places

JackYPCOnline · 2025-10-22T16:25:20Z

README.md

+| Environment Variable | Description | Default |
+|----------------------|-------------|---------|
+| RETRIEVE_ENABLE_METADATA_DEFAULT | Default setting for enabling metadata in retrieve tool responses | false |
+>>>>>>> origin/main


please remove

Looks like the conflict resolution is not done here ^^

Suggested change

>>>>>>> origin/main

…MongoDB connection strings - Remove ?retryWrites=true&w=majority from all MongoDB connection string examples in README.md - Clean up connection string format to follow best practices - Addresses review comment about unnecessary query parameters

ayanray089 · 2025-10-23T03:23:18Z

@JackYPCOnline Addressed latest feedback

cagataycali · 2025-10-23T15:22:59Z

README.md

+| Environment Variable | Description | Default |
+|----------------------|-------------|---------|
+| RETRIEVE_ENABLE_METADATA_DEFAULT | Default setting for enabling metadata in retrieve tool responses | false |
+>>>>>>> origin/main


Suggested change

>>>>>>> origin/main

Can we remove this too ^^

cagataycali · 2025-10-23T15:25:56Z

src/strands_tools/mongodb_memory.py

+                    response = _record_memory(collection, bedrock_runtime, namespace, self._embedding_model, content, metadata)
+                    return {
+                        "status": "success",
+                        "content": [{"text": f"Memory stored successfully: {json.dumps(response, default=str)}"}],


Can we return the JSON as content block?

"content" blocks supports "json",

"content": [{"text": f"Memory stored successfully: {json.dumps(response, default=str)}"}],

"content": [{"text": "Memory stored successfully"}, {"json": response}],

cagataycali · 2025-10-23T15:27:36Z

src/strands_tools/mongodb_memory.py

+        raise MongoDBEmbeddingError(f"Embedding generation failed: {str(e)}") from e
+
+
+def _truncate_content(content: str, max_length: int = MAX_CONTENT_LENGTH) -> str:


Looks like default MAX_CONTENT_LENGTH is set for 30 which will be pretty short for the retrieved context.

- Increased MAX_RESPONSE_SIZE from 1,000 to 70,000 characters - Increased MAX_CONTENT_LENGTH from 8,000 to 12,000 characters - Increased MAX_MEMORIES_IN_RESPONSE from 2 to 5 memories - Fixed unit tests to correctly access JSON from response content - All 27 unit tests now passing

ayanray089 · 2025-10-23T19:27:39Z

@JackYPCOnline @cagataycali Addressed the latest comments

Ayan Ray added 3 commits October 9, 2025 11:51

Remove test_mongodb_atlas.py from repository

175c935

- Integration test file contains sensitive credentials and should remain local only

ayanray089 requested a review from a team as a code owner October 9, 2025 20:51

ayanray089 requested a deployment to manual-approval October 9, 2025 20:51 — with GitHub Actions Waiting

ayanray089 mentioned this pull request Oct 9, 2025

[FEATURE] mongodb atlas memory tool #282

Open

JackYPCOnline reviewed Oct 11, 2025

View reviewed changes

src/strands_tools/mongodb_memory.py Show resolved Hide resolved

JackYPCOnline reviewed Oct 11, 2025

View reviewed changes

cagataycali reviewed Oct 13, 2025

View reviewed changes

ayanray089 requested a deployment to manual-approval October 13, 2025 17:25 — with GitHub Actions Waiting

JackYPCOnline reviewed Oct 14, 2025

View reviewed changes

ayanray089 requested a deployment to manual-approval October 15, 2025 23:06 — with GitHub Actions Waiting

JackYPCOnline previously approved these changes Oct 21, 2025

View reviewed changes

Merge origin/main into feature/mongodb-atlas-memory-tool

1381918

- Resolve conflicts in README.md by merging MongoDB Atlas Memory Tool and Retrieve Tool sections - Resolve conflicts in pyproject.toml by including both elasticsearch_memory and mongodb_memory dependencies

ayanray089 dismissed JackYPCOnline’s stale review via 1381918 October 21, 2025 17:27

ayanray089 requested a deployment to manual-approval October 21, 2025 17:28 — with GitHub Actions Waiting

JackYPCOnline requested changes Oct 22, 2025

View reviewed changes

ayanray089 requested a deployment to manual-approval October 23, 2025 03:21 — with GitHub Actions Waiting

cagataycali reviewed Oct 23, 2025

View reviewed changes

ayanray089 requested a deployment to manual-approval October 23, 2025 19:24 — with GitHub Actions Waiting

JackYPCOnline approved these changes Oct 26, 2025

View reviewed changes

		DEFAULT_VECTOR_INDEX_NAME = "vector_index"


		def _ensure_vector_search_index(collection, index_name: str = DEFAULT_VECTOR_INDEX_NAME):

		# Don't raise exception - allow the tool to work without vector search


		def _generate_embedding(bedrock_runtime, text: str, embedding_model: str) -> List[float]:

		raise MongoDBEmbeddingError(f"Embedding generation failed: {str(e)}") from e


		def _truncate_content(content: str, max_length: int = MAX_CONTENT_LENGTH) -> str:

Uh oh!

Feature/mongodb atlas memory tool #281

Are you sure you want to change the base?

Feature/mongodb atlas memory tool #281

Conversation

ayanray089 commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

JackYPCOnline Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

ayanray089 commented Oct 13, 2025

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!

ayanray089 commented Oct 15, 2025

Uh oh!

JackYPCOnline left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

ayanray089 commented Oct 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cagataycali Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayanray089 commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

ayanray089 commented Oct 9, 2025 •

edited

Loading

JackYPCOnline Oct 11, 2025 •

edited

Loading

JackYPCOnline left a comment •

edited

Loading

cagataycali Oct 23, 2025 •

edited

Loading