[P3-Enhancement] Add idempotency keys to store/upsert endpoints

[VirtualAgentics]

Description

Add idempotency key support to store and upsert endpoints to ensure reliable operations and prevent duplicate processing.

Background

This enhancement extends Issue #63 (batch endpoints) by adding standard REST idempotency support, ensuring operations can be safely retried without side effects.

Requirements

• Add Idempotency-Key header support to store/upsert endpoints
• Implement idempotency key validation and storage
• Add idempotency key TTL configuration
• Return appropriate responses for duplicate requests
• Add idempotency key metrics
• Document idempotency key usage
• Add idempotency key tests

Implementation Details

Files to modify:

• src/contextforge_memory/main.py - Add idempotency handling
• src/contextforge_memory/middleware/ - Add idempotency middleware
• src/contextforge_memory/config.py - Add idempotency configuration
• tests/ - Add idempotency tests
• README.md - Document idempotency usage

Technical approach:

• Implement idempotency middleware for request processing
• Store idempotency keys with request results
• Return cached responses for duplicate keys
• Add configuration for key TTL and storage
• Implement idempotency metrics

Acceptance Criteria

• Idempotency keys work correctly for store/upsert
• Duplicate requests return cached responses
• Idempotency key TTL is respected
• Metrics track idempotency usage
• Documentation explains usage patterns

Testing Requirements

• Unit tests for idempotency logic
• Integration tests for duplicate requests
• Performance tests for idempotency overhead
• TTL and expiration tests

Documentation Updates

• README.md - Document idempotency keys
• API documentation - Idempotency header
• Best practices - When to use idempotency
• Examples - Idempotency usage patterns

Related Issues

• Enhances: [P3] Implement batch_search and upsert endpoints #63 (batch endpoints)
• Depends on: None
• Blocks: None