Development

Development setup and testing with MemSync

Development Environment Setup

This guide covers setting up MemSync for local development, testing, and contributing to the project.

Prerequisites: Python 3.9+, PostgreSQL, and Redis are required for local development.

Local Installation

Step 1: Clone the Repository

git clone https://github.com/memsync/memsync.git
cd memsync

Step 2: Install Dependencies

MemSync uses Poetry for dependency management:

Install with Poetry

poetry install

poetry install
poetry run pip install groq together boto3 litellm ollama chromadb weaviate weaviate-client sentence_transformers vertexai \
                    google-generativeai elasticsearch opensearch-py vecs pinecone pinecone-text faiss-cpu langchain-community \
                    upstash-vector azure-search-documents

Step 3: Environment Configuration

Create a .env file in the project root:

# Database Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=memsync_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password

# Redis Configuration  
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# API Keys
OPENAI_API_KEY=your_openai_key
API_KEY=your_api_key

# Supabase (for authentication)
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

Step 4: Database Setup

Initialize the PostgreSQL database with pgvector extension:

# Create database and install pgvector
createdb memsync_dev
psql memsync_dev -c "CREATE EXTENSION vector;"

# Run migrations
cd server
alembic upgrade head

Step 5: Start Development Server

Start API Server

cd server
python main.py

docker-compose up -d

The API server will be available at http://localhost:8000

Testing

MemSync includes comprehensive test suites for all components:

Running Tests

# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_memory.py

# Run with coverage
poetry run pytest --cov=memsync tests/

Test Categories

Unit Tests

Test individual components like memory extraction, embedding generation, and vector operations.

pytest tests/test_memory.py
pytest tests/test_embeddings.py
pytest tests/test_user_registry.py

Integration Tests

Test API endpoints and database interactions.

pytest tests/test_api_key.py
pytest tests/test_buffer.py

Memory Buffer Tests

Test the buffered memory system for conversation processing.

pytest tests/test_buffer.py

Integration Testing

Test external integrations with sample data:

# Test Reddit integration
python tests/integration_tester.py --type reddit --username sample_user

# Test memory extraction
python tests/memory_tester.py --input "sample conversation"

Development Tools

Code Quality

MemSync uses several tools to maintain code quality:

Formatting

# Format code with ruff
ruff format .

# Run all formatting tools
make format

# Check code with ruff
ruff check .

# Run pre-commit hooks
pre-commit run --all-files

# Run mypy type checking
mypy memsync/

Available Make Commands

# Install dependencies
make install

# Run tests
make test

# Format and lint code
make format

# Build package
make build

# Generate documentation
make docs

Performance Testing

Benchmarking

MemSync includes comprehensive benchmarking against the Locomo dataset:

# Run memory indexing benchmark
python evaluation/run_experiments.py \
   --technique_type memsync \
   --method add \
   --input_file evaluation/dataset/locomo10.json

# Run search benchmark  
python evaluation/run_experiments.py \
   --technique_type memsync \
   --method search \
   --input_file evaluation/dataset/locomo10.json

# Evaluate results
python evaluation/evals.py \
   --input_file evaluation/results/memsync_search_results.json

Performance Metrics

Key metrics tracked:

• Memory extraction accuracy: How well facts are extracted from conversations
• Search relevance: Quality of semantic search results
• Storage efficiency: Memory usage vs. retrieval accuracy
• Processing speed: Time to index and search memories

API Development

Testing API Endpoints

Use the interactive API documentation at http://localhost:8000/docs or test with curl:

# Health check
curl http://localhost:8000/healthcheck

# Store memories (requires auth)
curl -X POST "http://localhost:8000/v1/memories" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Test message"}], "agent_id": "test", "thread_id": "test", "source": "test"}'

# Search memories
curl -X POST "http://localhost:8000/v1/memories/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test query", "limit": 5}'

Adding New Endpoints

1. Define request/response models in server/main.py
2. Implement the endpoint function
3. Add tests in tests/
4. Update API documentation

Example endpoint structure:

@app.post("/v1/new-endpoint")
async def new_endpoint(request: NewEndpointRequest, auth: CurrentAuth):
    # Validate request
    # Process with MemSync
    # Return response
    pass

Configuration Options

Memory Configuration

Customize memory extraction and storage:

config = {
    "llm": {
        "provider": "openai",  # or "gemini"
        "config": {
            "model": "gpt-4o",
            "temperature": 0.0
        }
    },
    "embedder": {
        "provider": "openai",  # or custom endpoint
        "config": {
            "model": "text-embedding-3-large",
            "embedding_dims": 1024
        }
    },
    "vector_store": {
        "provider": "pgvector",
        "config": {
            "collection_name": "memories_v5",
            "embedding_model_dims": 1024
        }
    },
    "memory_categories": ["career", "interests", "relationships", ...]
}

Integration Configuration

Configure external service integrations:

# Social media integrations
REDDIT_CLIENT_ID = "your_reddit_client_id"
REDDIT_CLIENT_SECRET = "your_reddit_client_secret"

# Document processing
DOCLING_API_KEY = "your_docling_key"

# Monitoring
DATADOG_API_KEY = "your_datadog_key"

Debugging

Common Issues

Database Connection Errors

Ensure PostgreSQL is running and pgvector extension is installed:

# Check PostgreSQL status
pg_isready

# Install pgvector if missing
psql -d memsync_dev -c "CREATE EXTENSION IF NOT EXISTS vector;"

Memory Extraction Not Working

Check LLM configuration and API keys:

# Test OpenAI connection
python -c "import openai; print(openai.api_key)"

# Check memory extraction logs
tail -f logs/memsync.log

Vector Search Issues

Verify embeddings are being generated correctly:

# Test embedding generation
python tests/test_embeddings.py

# Check vector store connection
python operations/check_embeddings.py

Logging

Enable detailed logging for debugging:

import logging
logging.basicConfig(level=logging.DEBUG)

# Or set environment variable
export LOG_LEVEL=DEBUG

Contributing

Development Workflow

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make changes and add tests
4. Run tests: pytest
5. Run linting: ruff check .
6. Commit changes: Follow conventional commit format
7. Push and create PR

Code Standards

• Follow PEP 8 style guidelines
• Add type hints for all functions
• Write tests for new functionality
• Update documentation as needed
• Use conventional commit messages

Testing Requirements

All PRs must include:

• Unit tests for new functionality
• Integration tests for API changes
• Performance benchmarks for core features
• Documentation updates

Deployment

Production Setup

1. Environment variables: Configure all required environment variables
2. Database: Set up PostgreSQL with pgvector in production
3. Redis: Configure Redis for task queue
4. Monitoring: Set up Datadog or similar monitoring
5. Security: Configure CORS, rate limiting, and authentication

Docker Deployment

# Build production image
docker build -f server/Dockerfile -t memsync:latest .

# Run with docker-compose
docker-compose -f docker-compose.prod.yml up -d

For more detailed deployment instructions, see the deployment guide.

Need Help?

• Documentation: Check our API Reference
• Issues: Report bugs on GitHub Issues
• Community: Join our Discord community
• Email: Contact us at [e-mail]