Describe your use case

Users need more granular control over search results beyond simple text queries. They want to filter by:

• Time ranges (memories created/updated between dates)
• Importance score thresholds
• Memory types (short-term, long-term, private, shared)
• Tags (multiple tags with AND/OR logic)
• Agent or user scopes
• Custom metadata fields
• Ebbinghaus retention scores

Currently, search supports basic filtering, but advanced combinations are limited.

Describe the solution you'd like

Implement a comprehensive filtering system:

1. Filter types:

   • Time filters: created_after, created_before, updated_after, updated_before
   • Score filters: min_importance, max_importance, min_retention, max_retention
   • Type filters: memory_types (list of types)
   • Tag filters: tags (with tag_logic: "AND" or "OR")
   • Scope filters: user_ids, agent_ids, scopes
   • Metadata filters: metadata_contains, metadata_equals (custom key-value)

2. Filter combinations:

   • Support multiple filters with AND logic
   • Optional OR logic for specific filters (e.g., tags)
   • Filter precedence and grouping

3. API enhancement:

   results = memory.search(
       "query",
       filters={
           "created_after": "2024-01-01",
           "min_importance": 0.7,
           "tags": ["work", "urgent"],
           "tag_logic": "AND",
           "memory_types": ["long_term"],
           "metadata_contains": {"category": "shopping"}
       },
       user_id="user123"
   )

4. Query builder:

   • Fluent API for building complex filters
   • Example: FilterBuilder().after("2024-01-01").importance(0.7).tags(["work"]).build()

The solution should:

• Be performant (use database indexes where possible)
• Support all existing search features
• Provide clear error messages for invalid filters
• Document all filter options

Describe alternatives you've considered

No response

Additional context

No response