DL-7: Manage Memories

[spuentesp]

Category: data-layer | Epic: 0 | Priority: medium

Summary

Implement CRUD operations for CharacterMemory documents in MongoDB with
vector embedding support via Qdrant. Memories belong to entities (characters)
and can reference scenes or facts. Supports importance-based recall and
semantic search.

Acceptance Criteria

• mongodb_create_memory creates CharacterMemory document
• mongodb_create_memory validates entity_id exists
• mongodb_create_memory supports optional scene_id and fact_id references
• mongodb_create_memory enforces importance range (0.0-1.0)
• mongodb_get_memory returns full memory with metadata
• mongodb_list_memories supports filtering by entity_id, importance threshold
• mongodb_update_memory allows updating importance and metadata
• qdrant_embed_memory generates and stores embedding for memory text
• qdrant_search_memories performs semantic search within entity's memories
• qdrant_search_memories supports filtering by entity_id, scene_id, importance
• Memory deletion removes both MongoDB doc and Qdrant vector
• Unit tests achieve >= 80% coverage

Dependencies

This use case depends on:

• DL-2
• DL-3
• DL-4
• DL-10

Blocks

This use case blocks:

• CF-2
• Q-5

Implementation

Layer: 1

Files to create:

• packages/data-layer/src/monitor_data/schemas/memories.py
• packages/data-layer/tests/test_tools/test_memory_tools.py
  Files to modify:
• packages/data-layer/src/monitor_data/tools/mongodb_tools.py
• packages/data-layer/src/monitor_data/tools/qdrant_tools.py
• packages/data-layer/src/monitor_data/middleware/auth.py

MONGODB Operations:

• mongodb_create_memory (authority: *)
• mongodb_get_memory (authority: *)
• mongodb_list_memories (authority: *)
• mongodb_update_memory (authority: *)
• mongodb_delete_memory (authority: *)

QDRANT Operations:

• qdrant_embed_memory (authority: *)
• qdrant_search_memories (authority: *)

Notes:

• Memories are subjective, belong to a single entity
• importance affects recall priority (higher = more likely to surface)
• Consider decay mechanism for old memories
• Embedding model should match scene embeddings for consistency

Testing Requirements

Minimum coverage: 80%

Unit tests:

• test_create_memory_success: valid params → Memory doc
• test_create_memory_importance_range: validates 0.0-1.0
• test_embed_memory: creates Qdrant vector
• test_search_memories: returns ranked results
• test_search_memories_by_entity: entity filter works
• ... and 2 more

Integration tests:

• test_memory_lifecycle: create → embed → search → delete
• test_memory_recall: create multiple → search → verify ranking

References

Documentation:

• docs/ontology/ONTOLOGY.md#28-memories
• docs/architecture/DATABASE_INTEGRATION.md
  Code:
• packages/data-layer/src/monitor_data/db/mongodb.py
• packages/data-layer/src/monitor_data/db/qdrant.py

---

Generated from /home/sebas/monitor2/docs/use-cases/data-layer/DL-7.yml