Feature/elasticsearch memory tool (#277)

* feat: Add Elasticsearch as Memory tool

- Add ElasticsearchMemoryToolProvider with full CRUD operations (record, retrieve, list, get, delete)
- Support both Elasticsearch Cloud (cloud_id) and serverless (es_url) connections
- Integrate Amazon Bedrock Titan embeddings for semantic search with 1024-dimensional vectors
- Implement k-NN vector search with cosine similarity and namespace isolation
- Add comprehensive unit tests (19 tests) with full mocking
- Include detailed documentation with usage examples and best practices
- Update README.md with Elasticsearch Memory usage examples
- Add elasticsearch>=8.0.0 dependency to pyproject.toml

* feat: Add Elasticsearch memory backend with semantic search

- Implement ElasticsearchMemoryToolProvider following agent_core_memory pattern
- Support dual connection methods: cloud_id and serverless URL
- Add semantic search using Amazon Bedrock Titan embeddings (1024-dim vectors)
- Implement k-NN vector search with cosine similarity
- Support all CRUD operations: record, retrieve, list, get, delete
- Add namespace-based memory isolation for multi-tenant applications
- Include comprehensive unit tests (19 tests) with mocking
- Add detailed documentation and usage examples
- Support environment variable configuration
- Add elasticsearch>=8.0.0 dependency to pyproject.toml
- Update README.md with usage examples

Resolves semantic memory storage requirements with Elasticsearch backend.

* Address PR feedback: improve error handling, parameter validation, and code quality

- Remove test_ayan_index.py from git tracking and add to .gitignore (security fix)
- Add custom exception classes for better error specificity:
  - ElasticsearchConnectionError
  - ElasticsearchMemoryNotFoundError
  - ElasticsearchEmbeddingError
  - ElasticsearchValidationError
- Fix parameter validation logic to use 'is None' instead of falsy check
- Add JSON parsing safety with proper error handling in embedding generation
- Simplify NotFoundError handling using direct import and proper exception chaining
- Reduce logging verbosity by removing excessive debug statements
- Update return format to match agent_core_memory pattern consistently
- Update tests to work with new custom exception types
- All 19 Elasticsearch memory tests passing

Addresses all reviewer feedback from PR #277:
- @cagataycali: credentials removal, return format standardization
- @JackYPCOnline: exception specificity, parameter validation, JSON safety, logging reduction, error handling simplification

* Remove verbose logging to match agent_core_memory pattern

- Remove debug logging from _generate_embedding method
- Remove info logging from _ensure_index_exists method
- Keep only essential error logging for actual failures
- Follow minimal logging approach used in agent_core_memory.py
- Addresses reviewer feedback about logging being 'too verbose'

* Refactor elasticsearch_memory tool to use direct tool pattern

- Added standalone @tool decorated elasticsearch_memory function
- Function accepts configuration parameters (cloud_id, api_key, es_url, etc.)
- Creates ElasticsearchMemoryToolProvider instance internally
- Enables new usage pattern: Agent(tools=[elasticsearch_memory])
- Maintains backward compatibility with existing provider class
- Updated tests to use new direct tool pattern
- Updated test_ayan_index.py to use direct tool calls
- All tests passing with new pattern

* Remove provider class and implement direct tool pattern only

- Removed ElasticsearchMemoryToolProvider class completely
- Refactored to only support Agent(tools=[elasticsearch_memory]) pattern
- Moved all functionality into standalone @tool decorated function
- Updated all tests to use direct tool pattern only
- Removed backward compatibility as requested
- All 18 unit tests passing
- Integration test working correctly with new pattern

* Update documentation to reflect direct tool pattern

- Updated docs/elasticsearch_memory_tool.md completely
- Removed all provider-based examples
- Added comprehensive direct tool usage examples
- Updated Quick Start section with new pattern
- Added configuration dictionary examples
- Updated all code samples to use elasticsearch_memory() function directly
- Maintained all advanced features and troubleshooting sections

* Update README.md Elasticsearch Memory section to use direct tool pattern

* Update unit tests to use proper agent.tool.elasticsearch_memory() pattern

- Updated all 18 test functions in tests/test_elasticsearch_memory.py
- Changed from direct elasticsearch_memory() calls to agent.tool.elasticsearch_memory()
- Maintains consistency with framework's standard tool usage pattern
- All tests pass successfully with the new agent pattern

* Update documentation to use proper agent.tool.elasticsearch_memory() pattern

- Updated docs/elasticsearch_memory_tool.md with agent.tool usage examples
- Updated README.md Elasticsearch Memory section to show correct invocation pattern
- All examples now demonstrate the standard framework pattern: agent.tool.elasticsearch_memory()
- Maintains consistency with other tools like use_computer and agent_core_memory
- Fixes documentation inconsistency identified in PR feedback

* Complete documentation updates and comprehensive test coverage

- Fixed remaining sections in docs/elasticsearch_memory_tool.md to use agent.tool pattern
- Updated Error Handling and Metadata Usage sections with proper agent invocation
- Added 9 new comprehensive test scenarios to tests/test_elasticsearch_memory.py:
  * Custom embedding model testing
  * Multiple namespaces for data isolation
  * Configuration dictionary pattern
  * Batch operations
  * Error handling scenarios
  * Metadata usage scenarios
  * Performance scenarios (pagination)
  * Security scenarios (namespace validation)
  * Troubleshooting scenarios
- Enhanced test_ayan_index.py with 7 additional test scenarios covering all documentation examples
- Total test coverage: 27 unit tests + 12 integration test scenarios
- All tests pass successfully (27/27)
- Ensures comprehensive coverage of all scenarios mentioned in documentation

* feat: Implement direct tool pattern for Elasticsearch Memory Tool

- Refactor elasticsearch_memory.py to use @tool decorator instead of provider class
- Remove ElasticsearchMemoryToolProvider class for cleaner direct tool usage
- Support Agent(tools=[elasticsearch_memory]) pattern as requested
- Add comprehensive test suite with 27 unit tests covering all scenarios
- Update documentation to reflect new direct tool usage patterns
- Add AWS credentials requirement note to README.md
- Fix line length linting issues for code style compliance
- Remove test_ayan_index.py from .gitignore (keep file local-only)

Key improvements:
- Simplified tool usage: Agent(tools=[elasticsearch_memory])
- Enhanced error handling with custom exceptions
- Parameter validation using 'is None' checks
- JSON parsing safety for API responses
- Standardized return format: {'status': 'success|error', 'content': [...]}
- Support for both Elasticsearch Cloud and Serverless connections
- Comprehensive semantic search with vector embeddings via Amazon Bedrock Titan

---------

Co-authored-by: Ayan Ray <[email protected]>

Author: ayanray089

.gitignore

@@ -15,4 +15,4 @@ venv/
 *.egg-info
 .DS_Store
 .prompt
-.kiro
+.kiro

README.md

@@ -786,6 +786,79 @@ result = agent.tool.use_computer(
 )
 ```
 
+### Elasticsearch Memory
+
+**Note**: This tool requires AWS account credentials to generate embeddings using Amazon Bedrock Titan models.
+
+```python
+from strands import Agent
+from strands_tools.elasticsearch_memory import elasticsearch_memory
+
+# Create agent with direct tool usage
+agent = Agent(tools=[elasticsearch_memory])
+
+# Store a memory with semantic embeddings
+result = agent.tool.elasticsearch_memory(
+    action="record",
+    content="User prefers vegetarian pizza with extra cheese",
+    metadata={"category": "food_preferences", "type": "dietary"},
+    cloud_id="your-elasticsearch-cloud-id",
+    api_key="your-api-key",
+    index_name="memories",
+    namespace="user_123"
+)
+
+# Search memories using semantic similarity (vector search)
+result = agent.tool.elasticsearch_memory(
+    action="retrieve",
+    query="food preferences and dietary restrictions",
+    max_results=5,
+    cloud_id="your-elasticsearch-cloud-id",
+    api_key="your-api-key",
+    index_name="memories",
+    namespace="user_123"
+)
+
+# Use configuration dictionary for cleaner code
+config = {
+    "cloud_id": "your-elasticsearch-cloud-id",
+    "api_key": "your-api-key",
+    "index_name": "memories",
+    "namespace": "user_123"
+}
+
+# List all memories with pagination
+result = agent.tool.elasticsearch_memory(
+    action="list",
+    max_results=10,
+    **config
+)
+
+# Get specific memory by ID
+result = agent.tool.elasticsearch_memory(
+    action="get",
+    memory_id="mem_1234567890_abcd1234",
+    **config
+)
+
+# Delete a memory
+result = agent.tool.elasticsearch_memory(
+    action="delete",
+    memory_id="mem_1234567890_abcd1234",
+    **config
+)
+
+# Use Elasticsearch Serverless (URL-based connection)
+result = agent.tool.elasticsearch_memory(
+    action="record",
+    content="User prefers vegetarian pizza",
+    es_url="https://your-serverless-cluster.es.region.aws.elastic.cloud:443",
+    api_key="your-api-key",
+    index_name="memories",
+    namespace="user_123"
+)
+```
+
 ## 🌍 Environment Variables Configuration
 
 Agents Tools provides extensive customization through environment variables. This allows you to configure tool behavior without modifying code, making it ideal for different environments (development, testing, production).