### PHASE 1: MEMORY REQUIREMENTS ANALYSIS 🔍 ### 1.1 Application Memory Objectives MemoraAI requires a persistent memory infrastructure that allows an AI customer-support agent to maintain customer-specific knowledge across independent conversations. The system must remember relevant information without requiring customers to repeat previously shared details. Primary objectives: * Maintain persistent customer profiles. * Remember previous support interactions. * Retrieve relevant historical issues. * Track unresolved customer problems. * Detect updated or corrected information. * Prevent duplicate memory creation. * Resolve conflicting customer information safely. * Maintain memory continuity across devices and sessions. * Control memory growth through retention policies. * Protect customer information through strict access controls. ### 1.2 Information Persistence Classification Memory information must be classified according to its expected lifetime. | Information | Classification | Persistence | | -------------------------- | -------------- | ------------------------------ | | Customer name | Durable | Long-term | | Preferred language | Durable | Until updated | | Communication preference | Durable | Until updated | | Current support issue | Temporary | Until resolved or expired | | Previous support summary | Historical | Policy-based | | Unresolved complaint | Important | Until resolved | | Current conversation state | Temporary | Session-based | | Customer correction | Durable event | Historical record retained | | Authentication token | Sensitive | Never store as ordinary memory | ### 1.3 Memory Creation Events The system should generate memory candidates when: * A customer shares a new preference. * A customer reports a recurring issue. * A support agent resolves an important problem. * A customer corrects previously stored information. * A customer requests future follow-up. * A conversation establishes an important customer-specific instruction. Not every message should create permanent memory. ### 1.4 Memory Retrieval Patterns The architecture must support these retrieval scenarios: Scenario A: Customer recognition Customer: "Hello, I need help again." Agent retrieves the customer's relevant profile and recent support history. Scenario B: Previous issue Customer: "The same payment issue happened again." Agent retrieves the previous payment-related support case. Scenario C: Preference retrieval Customer: "Please explain the solution." Agent retrieves the customer's saved preference for simple English explanations. Scenario D: Unresolved request Customer: "Any update on my complaint?" Agent retrieves the active complaint and its latest status. ### 1.5 Privacy and Retention Requirements * Separate memories by customer and tenant. * Encrypt stored information. * Avoid storing passwords, payment credentials, or unnecessary sensitive data. * Support customer-requested memory deletion. * Maintain auditable memory modifications. * Apply configurable retention periods. * Prevent one customer's memories from appearing in another customer's context. ### 1.6 Proposed Non-Functional Requirements Proposed targets, not measured results | Metric | Initial target | | ------------------------ | --------------------------- | | Memory retrieval latency | P95 under 300 ms | | Memory write latency | P95 under 500 ms | | API availability | 99.9% | | Concurrent sessions | 5,000 | | Memory isolation | Strict tenant isolation | | Data durability | Database-backed persistence | ### 1.7 Identified Engineering Risks | Risk | Mitigation | | ----------------------------- | ------------------------------ | | Duplicate memories | Similarity-based deduplication | | Outdated preferences | Versioned memory updates | | Incorrect extraction | Confidence thresholds | | Cross-customer leakage | Tenant-scoped authorization | | Excessive storage growth | Retention and consolidation | | Incorrect conflict resolution | Preserve competing evidence | ### 1.8 Phase 1 Deliverable Requirements specification established MemoraAI requires a hybrid persistent memory system combining structured customer records, historical memory records, semantic retrieval, and session-independent context reconstruction. Key architectural decision: Conversation history and persistent memory must be maintained as separate data domains. ### PHASE 2: MEMORY DOMAIN MODELING 🧩 ### 2.1 Memory Categories The system will use six primary memory categories. | Category | Purpose | Retention | | --------------------- | ---------------------------------- | --------------------- | | Customer Profile | Basic customer information | Until updated/deleted | | Preferences | Language and communication choices | Until updated | | Support History | Previous support interactions | Policy-based | | Active Issues | Unresolved complaints | Until resolution | | Customer Instructions | Persistent instructions | Until revoked | | Important Decisions | Confirmed support decisions | Historical | ### 2.2 Domain Structures A. Customer Profile ```json { "customer_id": "CUS-10001", "name": "Rahul", "preferred_language": "English", "account_status": "active" } ``` B. Customer Preferences ```json { "customer_id": "CUS-10001", "preferences": { "communication_style": "simple", "response_language": "English", "notification_channel": "email" } } ``` C. Support History ```json { "memory_id": "MEM-20001", "customer_id": "CUS-10001", "category": "support_history", "content": "Customer previously reported a failed payment.", "status": "resolved" } ``` D. Active Issues ```json { "memory_id": "MEM-20002", "customer_id": "CUS-10001", "category": "active_issue", "issue_type": "payment_failure", "status": "open", "priority": "high" } ``` ### 2.3 Memory Relationships ```mermaid erDiagram TENANT ||--o{ CUSTOMER : owns CUSTOMER ||--o{ MEMORY : has CUSTOMER ||--o{ SESSION : starts SESSION ||--o{ CONVERSATION : contains CONVERSATION ||--o{ MEMORY_CANDIDATE : produces MEMORY ||--o{ MEMORY_VERSION : maintains MEMORY ||--o{ MEMORY_EMBEDDING : indexed_by MEMORY ||--o{ MEMORY_SOURCE : supported_by TENANT { uuid tenant_id PK } CUSTOMER { uuid customer_id PK uuid tenant_id FK } MEMORY { uuid memory_id PK uuid customer_id FK string category string status } MEMORY_VERSION { uuid version_id PK uuid memory_id FK } ``` ### 2.4 Domain-Level Rules * Every customer memory must belong to an authorized customer. * Every tenant-specific memory must include a tenant identifier. * Temporary conversation context must not automatically become permanent memory. * Corrections must preserve historical versions. * Sensitive information must be filtered before persistence. * Active issues must remain retrievable until properly resolved. ### 2.5 Phase 2 Deliverable MemoraAI will use a customer-centric memory domain with structured profiles, preferences, historical interactions, active issues, instructions, and versioned decisions. ### PHASE 3: PERSISTENT MEMORY ARCHITECTURE 🏗️ ### 3.1 Proposed Architecture ```mermaid flowchart TD A[Customer] --> B[AI Support Agent] B --> C[Memory Orchestrator] C --> D[Memory Capture Service] C --> E[Memory Retrieval Service] D --> F[Memory Validation] F --> G[PostgreSQL] F --> H[Qdrant] E --> G E --> H C --> I[Redis Cache] J[Background Workers] --> G J --> H J --> K[Memory Consolidation] K --> G ``` ### 3.2 Infrastructure Components | Component | Responsibility | | ------------------- | ------------------------------- | | FastAPI | Memory backend APIs | | PostgreSQL | Authoritative persistent memory | | Qdrant | Semantic vector retrieval | | Redis | Short-lived retrieval cache | | Background Workers | Extraction and consolidation | | Embedding Service | Convert memory into vectors | | Memory Orchestrator | Coordinate memory operations | ### 3.3 Persistence Workflow * Customer starts a session. * Application authenticates the customer. * Memory orchestrator identifies the customer. * Relevant memories are retrieved. * AI agent receives selected context. * New conversation information is analyzed. * Memory candidates are validated. * Approved memories are persisted. * Vector indexes are updated. * Future sessions retrieve the saved information. ### 3.4 Persistence Guarantees * PostgreSQL acts as the source of truth. * A successful memory-write response is returned only after the authoritative database transaction commits. * Vector indexing can happen asynchronously through a transactional outbox. * Failed indexing operations must be retried. * Memory versions must be preserved. * Database backups must be tested through restoration exercises. ### 3.5 Phase 3 Deliverable A hybrid architecture with PostgreSQL as durable storage, Qdrant as a semantic retrieval index, Redis as a cache, and FastAPI as the service layer. ### PHASE 4: MEMORY DATA SCHEMA DESIGN 🗃️ ### 4.1 Main Memory Record ```json { "memory_id": "MEM-20001", "tenant_id": "TEN-001", "customer_id": "CUS-10001", "category": "preference", "content": "Customer prefers simple English explanations.", "attributes": { "preference_type": "communication", "value": "simple_english" }, "source": { "type": "conversation", "conversation_id": "CONV-1001" }, "confidence": 0.98, "importance": 0.85, "status": "active", "version": 1, "created_at": "2026-11-14T08:00:00Z", "updated_at": "2026-11-14T08:00:00Z", "expires_at": null, "access_scope": "customer_private" } ``` ### 4.2 PostgreSQL Table Design ```sql CREATE TABLE memories ( memory_id UUID PRIMARY KEY, tenant_id UUID NOT NULL, customer_id UUID NOT NULL, category VARCHAR(50) NOT NULL, content TEXT NOT NULL, attributes JSONB DEFAULT '{}', confidence NUMERIC(4,3), importance NUMERIC(4,3), status VARCHAR(30) NOT NULL, version INTEGER DEFAULT 1, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW(), expires_at TIMESTAMPTZ ); CREATE INDEX idx_memory_customer ON memories(tenant_id, customer_id, category); CREATE INDEX idx_memory_status ON memories(tenant_id, status); ``` ### 4.3 Version Table ```sql CREATE TABLE memory_versions ( version_id UUID PRIMARY KEY, memory_id UUID NOT NULL, version_number INTEGER NOT NULL, previous_content TEXT, new_content TEXT NOT NULL, change_reason TEXT, created_at TIMESTAMPTZ DEFAULT NOW() ); ``` ### 4.4 Additional Tables * customers * tenants * sessions * conversations * memory_sources * memory_embeddings * memory_audit_logs * memory_conflicts * memory_outbox ### 4.5 Validation Rules * Memory ID must be unique. * Customer ID must be valid. * Tenant association must be verified. * Confidence must remain between 0 and 1. * Importance must remain between 0 and 1. * Expiration timestamps must be valid. * Content must pass privacy filters. * Version numbers must increase monotonically. ### 4.6 Phase 4 Deliverable A normalized relational memory schema with JSONB attributes, source tracking, version history, timestamps, and authorization metadata. ### PHASE 5: MEMORY CAPTURE AND EXTRACTION 🧠 ### 5.1 Capture Pipeline ```mermaid flowchart TD A[Incoming Conversation] --> B[Message Analysis] B --> C[Information Extraction] C --> D[Candidate Generation] D --> E[Sensitivity Filter] E --> F[Importance Scoring] F --> G[Confidence Validation] G --> H{Approval Decision} H -->|Accept| I[Memory Repository] H -->|Reject| J[Discard Candidate] H -->|Review| K[Pending Review] I --> L[Vector Indexing] ``` ### 5.2 Extraction Categories The extraction engine identifies: * Customer identity facts. * Communication preferences. * Repeated problems. * Current support requests. * Customer instructions. * Important corrections. ### 5.3 Memory Scoring Proposed scoring formula: S = 0.35I + 0.30R + 0.20C + 0.15F Where: * = Importance. * = Relevance. * = Confidence. * = Future usefulness. Each variable is normalized between 0 and 1. Proposed decision rules: | Score | Action | | ---------- | ------------------------------ | | 0.80–1.00 | Eligible for automatic storage | | 0.60–0.79 | Additional validation | | Below 0.60 | Do not persist automatically | These are initial engineering thresholds requiring evaluation. ### 5.4 Example Customer says: "Please always explain technical solutions in simple English." Extracted candidate: ```json { "category": "preference", "content": "Customer prefers simple English explanations.", "importance": 0.85, "confidence": 0.98, "proposed_action": "create" } ``` ### 5.5 Phase 5 Deliverable A controlled memory extraction pipeline that converts meaningful conversational information into validated memory candidates. ### PHASE 6: MEMORY STORAGE ENGINE 💾 ### 6.1 Technology Evaluation | Technology | Use Case | Decision | | ------------- | ---------------------------- | ------------------------ | | PostgreSQL | Structured persistent memory | Primary | | Qdrant | Semantic retrieval | Primary | | Redis | Temporary caching | Supporting | | MongoDB | Document storage | Not initially required | | Elasticsearch | Advanced keyword search | Optional future addition | ### 6.2 Storage Interfaces ```python class MemoryRepository: async def create_memory(self, memory): pass async def get_memory(self, memory_id): pass async def update_memory(self, memory_id, data): pass async def delete_memory(self, memory_id): pass async def search_memories(self, customer_id, query): pass ``` These are interface examples, not executed implementation code. ### 6.3 Indexing Strategy PostgreSQL indexes: * tenant_id * customer_id * category * status * created_at * expires_at Qdrant indexes: * tenant_id * customer_id * memory_id * category * status ### 6.4 Consistency Strategy PostgreSQL remains authoritative. When a memory is created: * Commit the memory and outbox event in one transaction. * Background worker reads the event. * Generate or retrieve the embedding. * Upsert the vector into Qdrant. * Mark the event as processed. * Retry failures using idempotent operations. ### 6.5 Phase 6 Deliverable A hybrid storage engine with relational durability, semantic indexing, metadata filtering, and asynchronous index synchronization. ### PHASE 7: INTELLIGENT MEMORY RETRIEVAL 🔎 ### 7.1 Retrieval Workflow ```mermaid flowchart TD A[Customer Query] --> B[Identity Verification] B --> C[Query Understanding] C --> D[Metadata Filtering] D --> E[Keyword Search] D --> F[Semantic Search] E --> G[Hybrid Ranking] F --> G G --> H[Relevance Threshold] H --> I[Context Assembly] I --> J[AI Agent] ``` ### 7.2 Retrieval Example Customer query: "The payment problem is happening again." Retrieval engine searches for: * Previous payment failures. * Previous payment support tickets. * Related troubleshooting steps. * Open payment complaints. * Previous resolutions. ### 7.3 Hybrid Retrieval The system combines: * Semantic similarity. * Keyword matching. * Customer metadata filtering. * Category filtering. * Recency information. Proposed hybrid score: R = 0.50S + 0.25K + 0.15I + 0.10T Where: * = Semantic similarity. * = Keyword relevance. * = Importance. * = Temporal relevance. ### 7.4 Retrieval Safety Every retrieval request must filter by authorized tenant and customer before memory content is exposed to the AI agent. ### 7.5 Phase 7 Deliverable A hybrid retrieval engine that returns relevant customer memories using semantic and structured search. ### PHASE 8: MEMORY RANKING AND SELECTION 📊 ### 8.1 Ranking Dimensions | Dimension | Weight | | ------------------ | ------ | | Semantic relevance | 35% | | Importance | 25% | | Recency | 15% | | Confidence | 15% | | Usage frequency | 10% | ### 8.2 Ranking Formula M = 0.35S + 0.25I + 0.15R + 0.15C + 0.10U All values are normalized between 0 and 1. Expired and unauthorized memories must be excluded before ranking. ### 8.3 Selection Example Customer query: "What happened with my last complaint?" | Memory | Score | Decision | | ------------------------------ | ----- | -------- | | Previous complaint | 0.96 | Include | | Complaint resolution | 0.91 | Include | | Language preference | 0.42 | Exclude | | Old unrelated product question | 0.18 | Exclude | ### 8.4 Context Budget Initial proposed configuration: * Maximum retrieved memories: 15. * Maximum context allocation: 4,000 tokens. * Reserve context for current conversation and system instructions. The system must prioritize relevant memories instead of filling the context window unnecessarily. ### 8.5 Phase 8 Deliverable A ranking and selection engine that balances relevance, importance, confidence, and context limitations. ### PHASE 9: MEMORY UPDATING AND CORRECTION 🔄 ### 9.1 Update Workflow ```mermaid flowchart TD A[New Information] --> B[Candidate Extraction] B --> C[Existing Memory Search] C --> D{Matching Memory?} D -->|No| E[Create Memory] D -->|Yes| F[Compare Information] F --> G{Conflict?} G -->|No| H[Update Existing Memory] G -->|Yes| I[Create Conflict Record] I --> J[Validate Evidence] J --> K[Resolve or Preserve Conflict] H --> L[Version History] E --> L ``` ### 9.2 Update Scenarios Scenario A: Preference change Old memory: Customer prefers email. New information: "Please contact me through SMS instead." Action: Update communication preference and preserve its previous version. Scenario B: Customer correction Old memory: Customer's name is Rahul. New information: "My name is actually Rohan." Action: Update the customer profile after validating the correction. Scenario C: Temporary information Customer: "I am unavailable this afternoon." Action: Store as temporary session or scheduling context, not permanent preference. ### 9.3 Versioning Each update creates a new version. ```json { "memory_id": "MEM-20001", "version": 2, "previous_value": "email", "new_value": "sms", "change_reason": "customer_explicit_correction", "updated_at": "2026-11-14T09:00:00Z" } ``` ### 9.4 Phase 9 Deliverable A version-controlled memory update engine with duplicate detection, correction tracking, and conflict-aware operations. ### PHASE 10: MEMORY CONSOLIDATION 🧹 ### 10.1 Consolidation Objectives * Identify repeated memories. * Remove unnecessary duplication. * Combine related support events. * Generate compact summaries. * Preserve original source references. * Maintain historical versions. ### 10.2 Consolidation Workflow ```mermaid flowchart TD A[Stored Memories] --> B[Duplicate Detection] B --> C[Related Memory Grouping] C --> D[Summary Generation] D --> E[Source Verification] E --> F{Validation Passed?} F -->|Yes| G[Create Consolidated Memory] F -->|No| H[Keep Original Memories] G --> I[Preserve Source References] I --> J[Update Retrieval Index] ``` ### 10.3 Example Original observations: * Customer reported payment failure on Monday. * Customer reported the same payment failure on Tuesday. * Customer contacted support again on Wednesday. Consolidated memory: ```json { "category": "support_pattern", "content": "Customer experienced repeated payment failures over three consecutive days.", "source_memory_ids": [ "MEM-301", "MEM-302", "MEM-303" ], "status": "active" } ``` The original memories remain available for historical verification. ### 10.4 Consolidation Schedule Proposed background schedule: * Every 24 hours: Duplicate detection. * Every 7 days: Related memory consolidation. * Monthly: Storage optimization and archival review. ### 10.5 Phase 10 Deliverable A controlled consolidation engine that reduces redundant context without destroying original evidence. ### PHASE 11: CONTEXT RETENTION AND OPTIMIZATION ⚡ ### 11.1 Context Assembly Strategy The AI agent should receive: * Relevant customer profile. * Important communication preferences. * Current unresolved issues. * Related historical support summaries. * Important customer instructions. * Current conversation context. ### 11.2 Context Construction ```json { "customer_context": { "preferred_language": "English", "communication_style": "simple" }, "active_issues": [ { "issue": "payment_failure", "status": "open" } ], "historical_context": [ "Customer previously experienced payment failures." ], "important_instructions": [ "Explain technical solutions simply." ] } ``` ### 11.3 Optimization Methods * Retrieve only relevant memories. * Compress historical conversation summaries. * Remove duplicate context. * Preserve important identifiers and dates. * Avoid repeatedly injecting unrelated profile information. * Apply token budgeting. * Use structured context instead of large raw transcripts. ### 11.4 Phase 11 Deliverable A retrieval-driven context assembly engine that provides the agent with relevant information while controlling token consumption. ### PHASE 12: MEMORY LIFECYCLE MANAGEMENT ♻️ ### 12.1 Lifecycle States ```mermaid stateDiagram-v2 [*] --> Candidate Candidate --> Validating Validating --> Active Validating --> Rejected Active --> Updated Updated --> Active Active --> Consolidated Consolidated --> Archived Active --> Expired Active --> DeletionPending Archived --> DeletionPending Expired --> DeletionPending DeletionPending --> Deleted ``` ### 12.2 Lifecycle Operations | State | Description | | ---------------- | ------------------------------------------------------------ | | Candidate | Extracted information | | Validating | Undergoing checks | | Active | Available for retrieval | | Updated | New version generated | | Consolidated | Included in a summary | | Archived | Retained outside active retrieval | | Expired | No longer valid for normal retrieval | | Deletion Pending | Awaiting complete deletion | | Deleted | Removed from active and backup lifecycle according to policy | ### 12.3 Lifecycle Controls Every state transition must be auditable. Deleted memories must not reappear through vector indexes, caches, or restoration workflows. ### 12.4 Phase 12 Deliverable A formal lifecycle management framework covering creation through verified deletion. ### PHASE 13: MEMORY DECAY AND EXPIRATION ⏳ ### 13.1 Category-Based Retention | Memory Type | Proposed Policy | | ------------------------------ | ---------------------------------------- | | Customer profile | Until correction or deletion | | Preferences | Until changed or revoked | | Active issues | Until resolved plus applicable retention | | Support summaries | 12 months, subject to compliance | | Temporary session context | Session expiry | | Important decisions | Policy-based historical retention | | Security-sensitive information | Do not store unnecessarily | ### 13.2 Importance-Based Decay Proposed decay model: I_t = I_0e^{-\\lambda t} Where: * = Initial importance. * = Category-specific decay coefficient. * = Time elapsed. Important customer facts should not automatically disappear merely because their retrieval frequency is low. ### 13.3 Expiration Workflow * Identify records approaching expiration. * Verify retention category. * Check legal or operational holds. * Mark eligible records as expired. * Remove them from normal retrieval. * Archive or delete according to policy. * Update vector indexes and caches. * Record the lifecycle event. ### 13.4 Phase 13 Deliverable A configurable retention framework with category-specific expiration, importance-aware decay, and explicit deletion policies. ### PHASE 14: CONTRADICTION DETECTION AND RESOLUTION ⚖️ ### 14.1 Conflict Types * Customer identity conflicts. * Preference conflicts. * Account-status conflicts. * Issue-status conflicts. * Historical decision conflicts. * Conflicting information from different sources. ### 14.2 Conflict Resolution Workflow ```mermaid flowchart TD A[New Memory Candidate] --> B[Find Related Memories] B --> C[Detect Contradiction] C --> D{Conflict Found?} D -->|No| E[Normal Update] D -->|Yes| F[Compare Sources] F --> G[Compare Timestamps] G --> H[Compare Confidence] H --> I{Evidence Sufficient?} I -->|Yes| J[Apply Resolution Policy] I -->|No| K[Preserve Both Versions] K --> L[Request Clarification] J --> M[Record Audit Event] ``` ### 14.3 Example Existing memory: "Preferred language: English." New customer statement: "I prefer Bengali now." Resolution: * Identify the same preference attribute. * Confirm the new statement is explicit. * Create a new memory version. * Preserve the old value in history. * Update the active preference. * Record the correction source. ### 14.4 Conflict Record ```json { "conflict_id": "CONFLICT-100", "memory_id": "MEM-20001", "old_value": "English", "new_value": "Bengali", "resolution_status": "resolved", "resolution_reason": "explicit_customer_correction" } ``` ### 14.5 Phase 14 Deliverable An evidence-based conflict resolution system that avoids silent replacement and preserves unresolved competing information. ### PHASE 15: CROSS-SESSION MEMORY CONTINUITY 🌐 ### 15.1 Continuity Architecture Each customer must have an independent persistent identity that remains consistent across sessions and devices. ```mermaid flowchart TD A[Web Session] --> D[Identity Service] B[Mobile Session] --> D C[API Session] --> D D --> E[Customer ID Mapping] E --> F[Memory Orchestrator] F --> G[Persistent Memory] G --> H[Context Reconstruction] H --> I[AI Agent] ``` ### 15.2 Continuity Workflow * Customer logs in from a new device. * Identity service validates the customer. * Customer ID is resolved. * Tenant association is verified. * Relevant persistent memories are retrieved. * Current session context is reconstructed. * AI agent receives authorized customer context. ### 15.3 Multi-Device Support The architecture must support: * Web applications. * Mobile applications. * API-based integrations. * Multiple active sessions. * Session expiration. * Concurrent memory updates. ### 15.4 Concurrency Strategy Use optimistic locking with memory version numbers. If two sessions update the same memory simultaneously, the backend must detect the version mismatch rather than silently overwriting changes. ### 15.5 Phase 15 Deliverable A session-independent identity and memory retrieval architecture supporting multi-device continuity and concurrent access. ### PHASE 16: MEMORY API AND BACKEND SERVICES 🔌 ### 16.1 API Endpoint Design Base URL: `/api/v1/memories` | Operation | Method | Endpoint | | -------------------- | ------ | -------------------- | | Create memory | POST | / | | Retrieve memory | GET | /{memory_id} | | Update memory | PATCH | /{memory_id} | | Delete memory | DELETE | /{memory_id} | | Search memories | POST | /search | | Consolidate memories | POST | /consolidate | | View memory history | GET | /{memory_id}/history | | Memory analytics | GET | /analytics | ### 16.2 Create Memory API Request: ```json { "customer_id": "CUS-10001", "category": "preference", "content": "Customer prefers simple English.", "importance": 0.85 } ``` Response: ```json { "memory_id": "MEM-20001", "status": "active", "version": 1, "created": true } ``` ### 16.3 Search Memory API Request: ```json { "customer_id": "CUS-10001", "query": "Previous payment issues", "categories": [ "support_history", "active_issue" ], "limit": 10 } ``` Response: ```json { "results": [ { "memory_id": "MEM-20002", "content": "Customer previously reported a payment failure.", "relevance_score": 0.94 } ], "total": 1 } ``` ### 16.4 Update API The update request should support optimistic concurrency. ```json { "expected_version": 1, "content": "Customer prefers Bengali explanations.", "change_reason": "customer_correction" } ``` If the stored version is no longer 1, return HTTP 409 Conflict. ### 16.5 API Security * OAuth 2.0 or equivalent authentication. * Tenant-scoped authorization. * Customer-level ownership checks. * Request validation. * Rate limiting. * Idempotency keys for retryable writes. * Structured error responses. * Audit logging. ### 16.6 Standard Error Structure ```json { "error": { "code": "MEMORY_VERSION_CONFLICT", "message": "Memory was updated by another operation.", "request_id": "REQ-10001" } } ``` ### 16.7 Phase 16 Deliverable A versioned REST API supporting memory creation, retrieval, searching, updating, deletion, consolidation, and analytics. ### PHASE 17: SECURITY AND PRIVACY ARCHITECTURE 🔐 ### 17.1 Security Layers | Layer | Security Control | | ---------------- | --------------------------- | | Authentication | OAuth 2.0 | | Authorization | RBAC and ownership policies | | Database | Tenant-scoped access | | Network | TLS encryption | | Storage | Encryption at rest | | Secrets | Secret manager | | Logging | Audit trails | | Vector retrieval | Metadata isolation | | API | Rate limiting | ### 17.2 Data Isolation Every memory retrieval must enforce: ```sql SELECT * FROM memories WHERE tenant_id = :authenticated_tenant AND customer_id = :authenticated_customer AND status = 'active'; ``` Tenant and customer identifiers must come from verified authorization context, not untrusted request parameters alone. ### 17.3 Sensitive Information Filtering The capture pipeline must reject or appropriately handle: * Passwords. * Authentication tokens. * Payment card credentials. * Secret API keys. * Unnecessary personal sensitive information. ### 17.4 Deletion Verification When a customer requests deletion: * Authenticate the request. * Identify all associated memory records. * Mark deletion pending. * Delete PostgreSQL records and versions according to policy. * Remove corresponding Qdrant vectors. * Invalidate Redis cache entries. * Handle dependent summaries. * Record deletion evidence. * Apply backup retention and deletion procedures. ### 17.5 Phase 17 Deliverable A defense-in-depth security architecture with tenant isolation, encrypted persistence, controlled access, sensitive-data filtering, and auditable deletion. ### PHASE 18: PERFORMANCE AND SCALABILITY 📈 ### 18.1 Expected Workload Project assumptions: * 100,000 customers. * 10 million memory records. * 5,000 concurrent sessions. * Hybrid retrieval. * Continuous background indexing. These are planning inputs, not measured workload results. ### 18.2 Scaling Strategy | Component | Scaling Approach | | ---------- | ------------------------------------ | | FastAPI | Horizontal replicas | | PostgreSQL | Connection pooling and read replicas | | Qdrant | Distributed collections and sharding | | Redis | Replication and clustering | | Workers | Queue-based horizontal scaling | | Embeddings | Batch processing | ### 18.3 Performance Optimization * Use database connection pooling. * Batch embedding generation. * Cache frequently retrieved memories. * Partition large tables where beneficial. * Apply metadata filters before semantic ranking. * Use asynchronous background workers. * Avoid unnecessary embedding regeneration. * Apply pagination for history APIs. ### 18.4 Capacity Planning Initial storage and throughput estimates must be calculated using: * Average memory size. * Average embeddings per customer. * Daily memory creation rate. * Retrieval requests per second. * Embedding dimensions. * Index overhead. * Replication factor. * Backup requirements. ### 18.5 Phase 18 Deliverable A horizontally scalable memory infrastructure with workload-aware database, vector search, caching, and background processing. ### PHASE 19: OBSERVABILITY AND MONITORING 📡 ### 19.1 Monitoring Metrics | Metric | Purpose | | -------------------------- | --------------------------- | | memory_created_total | Memory creation volume | | memory_update_total | Update activity | | retrieval_latency | Search performance | | retrieval_relevance | Retrieval quality | | duplicate_memory_rate | Duplicate detection quality | | memory_write_failures | Persistence reliability | | embedding_queue_depth | Indexing backlog | | consolidation_success_rate | Consolidation health | | storage_growth | Storage utilization | | deletion_completion_rate | Deletion reliability | ### 19.2 Observability Architecture ```mermaid flowchart TD A[FastAPI Services] --> D[OpenTelemetry] B[Background Workers] --> D C[Databases] --> D D --> E[Metrics] D --> F[Distributed Traces] D --> G[Structured Logs] E --> H[Monitoring Dashboard] F --> H G --> H H --> I[Alerts] ``` ### 19.3 Alert Conditions * PostgreSQL write failures. * Qdrant indexing backlog. * Retrieval latency exceeding target. * Abnormal memory growth. * Repeated authorization failures. * Consolidation worker failures. * Incomplete deletion workflows. ### 19.4 Phase 19 Deliverable A monitoring framework providing visibility into system reliability, memory quality, retrieval performance, and infrastructure cost. ### PHASE 20: TESTING AND VALIDATION 🧪 ### 20.1 Testing Categories | Test Type | Validation Objective | | ------------------- | ---------------------------- | | Unit Testing | Memory operations | | Integration Testing | Database and vector indexing | | Persistence Testing | Cross-session storage | | Retrieval Testing | Relevant memory selection | | Conflict Testing | Contradiction handling | | Security Testing | Customer isolation | | Load Testing | Concurrent requests | | Recovery Testing | Backup restoration | | Lifecycle Testing | Expiration and deletion | ### 20.2 Sample Test Scenarios Test 1: Persistent Memory Input: Customer: "I prefer Bengali." Expected result: * Preference extracted. * Memory validated. * PostgreSQL record created. * Memory available in a new session. Test 2: Memory Correction Input: Customer: "I now prefer English instead." Expected result: * Existing preference identified. * New version created. * Old version preserved. * English becomes the active preference. Test 3: Cross-Customer Isolation Input: Customer A requests their support history. Expected result: * Customer A receives only authorized memories. * Customer B's records remain inaccessible. Test 4: Contradiction Handling Input: Two independent sources provide conflicting account statuses. Expected result: * Conflict detected. * Both sources preserved. * Resolution deferred until sufficient evidence exists. Test 5: Memory Deletion Input: Customer requests deletion of their stored memories. Expected result: * Deletion workflow initiated. * Database records removed according to policy. * Vector entries removed. * Cache invalidated. * Completion independently verified. ### 20.3 Evaluation Metrics | Metric | Initial Target | | ------------------------------- | -------------------- | | Memory extraction precision | 95% | | Retrieval Precision@5 | 90% | | Duplicate detection accuracy | 95% | | Cross-session retrieval success | 99% | | Unauthorized retrieval | 0 successful cases | | Memory update consistency | 100% in tested cases | These are proposed acceptance targets, not achieved results. ### 20.4 Phase 20 Deliverable A comprehensive test framework covering functional correctness, retrieval quality, persistence, isolation, concurrency, and recovery. ### PHASE 21: DEPLOYMENT AND IMPLEMENTATION ROADMAP 🚀 ### 21.1 Deployment Architecture ```mermaid flowchart TD A[Frontend Applications] --> B[API Gateway] B --> C[FastAPI Cluster] C --> D[Memory Orchestrator] D --> E[PostgreSQL] D --> F[Qdrant] D --> G[Redis] D --> H[Task Queue] H --> I[Background Workers] I --> E I --> F I --> J[Embedding Service] C --> K[Monitoring Stack] ``` ### 21.2 Implementation Stages * Stage 1: Core Infrastructure Week 1–2 * Configure PostgreSQL. * Configure FastAPI. * Implement authentication. * Create initial memory schemas. Acceptance: Authenticated customers can create and retrieve isolated memory records. * Stage 2: Memory Capture Week 3–4 * Implement information extraction. * Build candidate validation. * Add confidence scoring. * Implement memory persistence. Acceptance: Relevant customer information can be converted into validated memory records. * Stage 3: Semantic Retrieval Week 5–6 * Configure Qdrant. * Implement embeddings. * Build hybrid retrieval. * Add ranking and context assembly. Acceptance: Relevant memories can be retrieved across independent sessions. * Stage 4: Memory Intelligence Week 7–8 * Implement versioning. * Build contradiction detection. * Implement consolidation. * Add retention workflows. Acceptance: Memory updates and historical corrections are handled safely. * Stage 5: Security and Optimization Week 9–10 * Implement encryption. * Add deletion workflows. * Optimize database queries. * Configure caching. Acceptance: Privacy, isolation, and performance tests meet agreed targets. * Stage 6: Production Readiness Week 11–12 * Configure CI/CD. * Implement monitoring. * Test backup recovery. * Execute load tests. * Conduct production-readiness review. Acceptance: Deployment passes agreed release gates. ### 21.3 CI/CD Pipeline ```text Developer Commit | v Code Quality Checks | v Unit Tests | v Integration Tests | v Security Scanning | v Docker Build | v Staging Deployment | v Acceptance Testing | v Production Deployment | v Monitoring ``` ### 21.4 Phase 21 Deliverable A staged 12-week implementation roadmap with deployment architecture, infrastructure dependencies, testing gates, and measurable acceptance criteria. ### PHASE 22: ADDITIONAL DEPLOYMENT ARCHITECTURE 🏢 ### 22.1 Environment Separation | Environment | Purpose | | ----------- | ----------------------- | | Development | Feature development | | Testing | Automated validation | | Staging | Production-like testing | | Production | Live customer traffic | ### 22.2 Infrastructure Requirements * Docker-based service packaging. * Kubernetes or managed container orchestration when justified. * Managed PostgreSQL. * Qdrant deployment. * Redis deployment. * Background worker infrastructure. * Centralized logging. * Automated database backups. * Secret management. * CI/CD deployment pipelines. ### 22.3 Disaster Recovery Proposed initial targets: * Recovery Point Objective (RPO): 15 minutes. * Recovery Time Objective (RTO): 2 hours. These require validation against actual database backup frequency, replication architecture, and recovery testing. ### 22.4 Phase 22 Deliverable A production deployment blueprint supporting isolated environments, controlled releases, observability, backups, and disaster recovery. ### PHASE 23: IMPLEMENTATION ROADMAP AND ENGINEERING DEPENDENCIES 🛠️ ### 23.1 Engineering Work Breakdown | Workstream | Dependency | Priority | | ------------------ | ----------------------- | -------- | | Identity service | Authentication | Critical | | Memory schema | Domain modeling | Critical | | Memory repository | PostgreSQL | Critical | | Extraction engine | AI model integration | High | | Semantic retrieval | Qdrant and embeddings | High | | Memory ranking | Retrieval engine | High | | Versioning | Memory repository | High | | Consolidation | Historical memory data | Medium | | Monitoring | Service instrumentation | High | | Analytics | Event collection | Medium | ### 23.2 Important Unresolved Decisions Before implementation, the engineering team must finalize: * Whether customer data is subject to specific regional data residency requirements. * Whether memory deletion must include immediate physical deletion or policy-based backup expiry. * Whether customers can manually inspect and edit individual memories. * Whether all memory categories require semantic embeddings. * Which AI model will handle memory extraction. * Whether enterprise tenants require dedicated storage. * Whether support agents can access customer memories with explicit authorization. ### 23.3 Phase 23 Deliverable A dependency-aware implementation plan identifying critical engineering decisions and sequencing infrastructure work. ### PHASE 24: FINAL ARCHITECTURE REVIEW 🏆 ### 24.1 Final Technology Stack | Layer | Selected Technology | | --------------------- | ---------------------------------- | | Backend | Python + FastAPI | | Primary Database | PostgreSQL | | Vector Database | Qdrant | | Cache | Redis | | Embeddings | OpenAI Embeddings | | Background Processing | Queue-based workers | | Authentication | OAuth 2.0 | | Monitoring | OpenTelemetry | | Deployment | Docker + Kubernetes when justified | | CI/CD | Automated deployment pipeline | ### 24.2 Complete Memory System Flow ```mermaid flowchart TD A[Customer Interaction] --> B[Identity Verification] B --> C[Memory Retrieval] C --> D[Context Ranking] D --> E[Context Assembly] E --> F[AI Support Agent] F --> G[Customer Response] F --> H[Memory Extraction] H --> I[Validation and Privacy] I --> J[Duplicate and Conflict Detection] J --> K[Memory Storage] K --> L[Vector Indexing] L --> M[Future Session Retrieval] K --> N[Consolidation and Retention] ``` ### 24.3 Architecture Acceptance Checklist Production Readiness Checklist 0/12 completed Persistent memory survives application restarts. Customer memories remain isolated across tenants. Relevant memories can be retrieved across sessions. Memory updates preserve historical versions. Contradictions are detected and safely handled. Duplicate memories are identified. Consolidation preserves original source information. Expiration follows category-specific retention policies. Deletion propagates across databases and caches. Retrieval respects the context budget. Monitoring captures memory failures and latency. Backup restoration is successfully tested. Reset checklist ### 24.4 Final Engineering Assessment Architecture blueprint completed MemoraAI is designed as a hybrid, multi-tenant, persistent memory infrastructure for AI customer-support applications. Its central engineering principles are: * PostgreSQL provides durable and authoritative memory storage. * Qdrant provides semantic memory retrieval. * Redis supports temporary caching. * FastAPI exposes controlled memory operations. * Background workers handle embeddings and consolidation. * Versioning protects historical information. * Conflict detection prevents unsafe memory replacement. * Retention policies control memory growth. * Identity and authorization enforce customer isolation. * Observability supports production reliability. Final recommendation: Build the structured memory repository, identity isolation, and persistence layer first. Introduce semantic retrieval after reliable memory capture is established. Add consolidation and advanced memory intelligence only after the foundational system passes persistence and security validation. SAMPLE TEST 01 — ALL 24 ARCHITECTURE SECTIONS COMPLETED This is a proposed engineering blueprint. No application code, deployment, performance benchmark, or test execution has been performed.