Synk - Universal Memory Layer

A production-ready universal memory layer that extracts personal information from text and files using Claude AI, then stores and retrieves memories using hybrid search with Elasticsearch cloud.

Quick Start

1. Install Dependencies & Config

cp env.example .env # copy env file and add keys
pip install -r requirements.txt

2. Test complete flow

You can test the complete flow by running the end-to-end test.

python test_e2e_flow.py

3. Test Memory Extraction

Text Input Extraction

python tests/test_definite_extraction.py

File Processing (PDF, DOCX, Images, Text)

python tests/test_file_extraction.py

Resume Processing with MCP Prompts

# Test with PDF resume
python tests/test_resume.py tests/sample_resume_2.pdf

# Test with PNG resume (OCR)
python tests/test_resume.py tests/example_resume.png

# Test with DOCX resume
python tests/test_resume.py tests/sample_resume_3.pdf

4. Run the Hybrid Search Demo

python3 examples/hybrid_search_demo.py

5. Run Test Suite

python3 tests/test_hybrid_search.py

6. Start MCP Server

python3 mcp_server.py

Or using FastMCP CLI:

fastmcp run mcp_server.py:mcp

This will:

• Start the MCP server for LLM integration
• Expose hybrid search and memory extraction as MCP tools

Project Structure

memry-mcp/
├── models/
│   └── memory.py                # Memory data models and validation
├── utils/
│   ├── claude_extractor.py      # Claude AI memory extraction
│   └── file_processor.py       # File processing (PDF, DOCX, OCR)
├── hybrid_search_client.py      # Core hybrid search functionality
├── hybrid_search_service.py     # High-level service interface
├── examples/                     # Example applications
│   └── hybrid_search_demo.py    # Demo application
├── tests/                       # Test suite
│   ├── test_definite_extraction.py  # Text extraction tests
│   ├── test_file_extraction.py      # File processing tests
│   ├── test_resume.py               # Resume processing tests
│   ├── test_hybrid_search.py        # Search functionality tests
│   ├── example_resume.png           # Sample resume (image)
│   ├── sample_resume_2.pdf          # Sample resume (PDF)
│   └── sample_resume_3.pdf          # Sample resume (PDF)
├── docs/                        # Documentation
│   └── ARCHITECTURE.md          # Architecture documentation
├── requirements.txt             # Dependencies
└── README.md                    # This file

Architecture

Service Layers

• Client Layer: Direct Elasticsearch operations and query construction
• Service Layer: High-level interface with formatting and analysis
• Demo Layer: Example applications and usage demonstrations

How It Works

┌─────────────────────┐    ┌──────────────────┐
│   Hybrid Search     │────│   Elasticsearch  │
│   Service Layer     │    │   (Cloud)        │
│                     │    │                  │
│ • Client Layer      │    │ • semantic_text  │
│ • Service Layer     │    │ • text search    │
│ • Demo Application  │    │ • hybrid search  │
└─────────────────────┘    └──────────────────┘

Key Features

🧠 Claude AI Memory Extraction

• Intelligent Processing: Uses Claude AI to extract personal information from text and files
• Definite-Only Extraction: Only extracts explicitly stated information (no inference)
• High Confidence: All extracted memories have 100% confidence scores
• Multiple Memory Types: Supports preferences, facts, events, notes, tasks, and ideas

📄 Universal File Processing

• PDF Processing: Extract text from PDF documents
• DOCX Support: Process Microsoft Word documents
• Image OCR: Extract text from images using Tesseract OCR
• Text Files: Handle plain text files
• Auto-Detection: Automatically detects file types and processing methods

🔍 Hybrid Search Capabilities

• Semantic Search: Find content by meaning using ELSER model
• Text Search: Traditional keyword matching for exact terms
• Hybrid Approach: Combines both for optimal results
• Performance Analysis: Built-in timing and scoring metrics

🚀 MCP Server Integration

• FastMCP Framework: Modern, Pythonic MCP server implementation
• LLM-Ready Tools: Expose functionality as MCP tools for AI applications
• Memory Management: Extract, store, and search personal memories
• Batch Operations: Efficient processing of multiple queries

Example Queries

• "Python performance optimization" → Finds Python optimization content
• "Database query tuning" → Finds database performance content
• "Machine learning evaluation" → Finds ML evaluation content
• "API design best practices" → Finds API development content

MCP Tools

The MCP server exposes the following core tools for LLM applications:

search_memories

Search through personal memories using hybrid search.

• Parameters: query (string), limit (int, default: 5), min_score (float, default: 8.0)
• Returns: Search results with scores and metadata

extract_memories

Extract personal memories from text or files using Claude AI.

• Parameters:
  • input_text (string, optional): Direct text input
  • input_file (string, optional): File path for processing
  • file_type (string, optional): File type ("text", "pdf", "docx", "image")
  • source (string, default: "chat")
• Returns: Extracted memories with confidence scores
• Supported Files: PDF, DOCX, images (PNG, JPG), text files

MCP Usage

The MemMe MCP server exposes your hybrid search and memory management capabilities as tools for LLM applications. See MCP_USAGE.md for detailed usage instructions.

Quick MCP Examples

Text Extraction

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        # Search memories
        result = await client.call_tool("search_memories", {
            "query": "Where should I eat breakfast?",
            "limit": 3
        })
        print(f"Search results: {result}")

asyncio.run(main())

What You'll See

The demo will show:

• Service initialization and connection
• Individual hybrid search results with scores
• Batch search processing
• Performance metrics and analysis
• Real-time search with your actual data

Requirements

• Python 3.7+
• elasticsearch package
• Your Elasticsearch cloud instance (already configured)

Flow

1. User says: "I love Italian food and prefer morning meetings"
2. Claude AI processing (claude_extractor.py) -- extracts personal info from the user. Analysis result:

[
  {
    "type": "preference",
    "content": "User loves Italian food",
    "confidence": 1.0
  },
  {
    "type": "preference", 
    "content": "User prefers morning meetings",
    "confidence": 1.0
  }
]

3. Memory object creation

for item in extracted_data:
    if all(key in item for key in ['type', 'content', 'confidence']):
        try:
            memory_type = MemoryType(item['type'])
            memory = Memory(
                type=memory_type,
                content=item['content'],
                source=SourceType.CHAT,
                confidence=1.0,  # Always 1.0 for definite information
            )
            memories.append(memory)

4. Created Memory Objects:

Memory(
    id=UUID('12345678-1234-5678-9012-123456789abc'),
    type=MemoryType.PREFERENCE,
    content="User loves Italian food",
    source=SourceType.CHAT,
    created_at=datetime(2025, 10, 25, 19, 2, 30),
    confidence=1.0
)

Memory(
    id=UUID('87654321-4321-8765-2109-987654321def'),
    type=MemoryType.PREFERENCE,
    content="User prefers morning meetings",
    source=SourceType.CHAT,
    created_at=datetime(2025, 10, 25, 19, 2, 30),
    confidence=1.0
)

5. Store in Elasticsearch - these memories can stored as Elasticsearch documents
6. Search & Retrieval: Later, the user asks "Where should I eat dinner tonight?"
7. Hybrid search execution:

def hybrid_search(self, query: str, limit: int = 5) -> Dict[str, Any]:
    search_body = {
        "query": {
            "bool": {
                "should": [
                    {
                        "match": {
                            "content": {
                                "query": query,
                                "boost": 1.0
                            }
                        }
                    },
                    {
                        "semantic": {
                            "field": "text",
                            "query": query,
                            "boost": 1.5
                        }
                    }
                ]
            }
        },
        "size": limit,
        "_source": ["content", "source", "category", "tags"]
    }

Search Process:

• Text Search: Looks for keywords like "eat", "dinner" → Low relevance
• Semantic Search: ELSER model understands "dinner" relates to "Italian food" → High relevance
• Combined Scoring: Semantic match gets higher boost (1.5x vs 1.0x)

8. Now, we get a context-aware recommendation:

Based on your preferences:
   - You love Italian food
   - Consider Italian restaurants for dinner tonight
   - Score: 2.34 (High confidence match)

Complete Data Flow Diagram

User Input: "I love Italian food and prefer morning meetings"

↓

PHASE 1: EXTRACTION
Claude AI → Extract personal info → Create Memory objs

↓

PHASE 2: STORAGE
Memory.to_vector_document() → Elasticsearch indexing
↓

PHASE 3: RETRIEVAL
User query → Hybrid search → Semantic + Text matching
↓

PHASE 4: RESPONSE
Format results → Confidence scoring → Smart suggestions