postgres-mcp-tools

# Memory Concepts This document explains key concepts of the vector-based memory system used in PostgreSQL MCP Tools. ## Vector Embeddings Vector embeddings are numerical representations of text that capture semantic meaning. In this system: - **Dimension**: Typically 1536-dimensional vectors - **Similarity**: Measured using cosine similarity - **Semantic Understanding**: Similar meanings have similar vectors ### How Embeddings Work When text is processed: 1. The text is sent to an embedding model (OpenAI, Anthropic, or mock) 2. The model returns a vector representation 3. This vector is stored alongside the text 4. Searches compare vector similarity rather than text matching This approach enables: - **Semantic Search**: Finding conceptually similar content - **Fuzzy Matching**: Handling variations in wording - **Concept Association**: Connecting related ideas ## Memory Organization Memories are organized around: ### Conversation Context - **Conversation ID**: Groups memories by conversation - **User ID**: Associates memories with specific users - **Timestamp**: Records when memories were created - **Content**: The actual text of the memory - **Metadata**: Additional information about the memory ### Vector Search - **Similarity Search**: Finds memories with similar meaning - **Relevance Ranking**: Returns the most relevant memories first - **Threshold Filtering**: Only returns sufficiently similar results ## Memory Lifecycle Memories follow a lifecycle: 1. **Creation**: New information is saved with embeddings 2. **Retrieval**: Relevant memories are fetched based on query 3. **Archiving**: Older memories are marked as archived 4. **Optimization**: Vector indexes are optimized periodically ## Memory Types The system supports different types of memories: ### Factual Memories - Specific information shared by the user - Example: "My favorite color is blue" - High precision retrieval is critical ### Conversational Context - General discussion topics and themes - Example: "We were discussing database technologies" - Broader semantic matching is useful ### Long-term Preferences - Persistent user preferences - Example: "I prefer technical explanations" - Should persist across multiple conversations ## Semantic Search The heart of the memory system is semantic search: ### Search Process 1. Convert the current query to a vector embedding 2. Compare this vector to all stored memory vectors 3. Calculate similarity scores using cosine similarity 4. Return memories above a similarity threshold 5. Rank results by relevance ### Search Parameters - **Max Results**: Limits the number of memories returned - **Similarity Threshold**: Sets minimum relevance - **Scope**: Filters by conversation or user ID - **Archived Status**: Includes or excludes archived memories ## Vector Database Implementation The system uses PostgreSQL with pgvector: ### pgvector Extension - Enables vector operations in PostgreSQL - Provides indexing for efficient similarity search - Supports both L2 distance and cosine similarity ### Indexing - **IVFFlat**: Inverted file with flat quantization - **Index Lists**: Optimized for vector search operations - **Index Maintenance**: Regular optimization needed ## Memory Management The system provides tools for memory management: ### Listing - View memories for a conversation - See similarity scores for current context - Inspect metadata and timestamps ### Archiving - Mark old memories as archived - Remove irrelevant or outdated information - Manage storage growth ### Optimization - Rebuild vector indexes - Vacuum the database - Optimize query performance ## Privacy and Data Retention Important considerations for memory systems: - **Data Ownership**: User data remains under user control - **Retention Policies**: Configure how long memories are kept - **Privacy Controls**: Ability to delete specific memories - **Data Isolation**: Separate memories by user and conversation ## Memory Limitations Current limitations of the system: - **Context Window**: Limited by Claude's context window size - **Retrieval Accuracy**: Depends on embedding quality - **Cold Start**: New systems have limited historical context - **Embedding Drift**: Models may change over time ## Best Practices Recommendations for optimal memory usage: - **Regular Maintenance**: Schedule routine database optimization - **Clear Identification**: Use consistent conversation and user IDs - **Targeted Retrieval**: Use specific queries for better results - **Balanced Context**: Return enough context without overwhelming ## Advanced Concepts ### Multi-context Retrieval - Combine memories from different conversations - Weight relevance based on recency and similarity - Balance broad context with specific details ### Memory Hierarchies - Organize memories in hierarchical structures - Differentiate between facts, preferences, and history - Create memory "categories" for better organization ### Active Learning - Improve memory retrieval based on user feedback - Adjust similarity thresholds dynamically - Learn from retrieval successes and failures ## Future Directions Potential enhancements for future versions: - **Hybrid Search**: Combine vector and keyword search - **Memory Summarization**: Condense repeated information - **Multi-vector Representations**: Multiple embeddings per memory - **Structured Memory**: More complex memory relationships - **Cross-modality**: Support for images and other content types