Deploy Memory Spine in 15 Minutes

1. Prerequisites and Setup

Before we start, verify you have the required dependencies. Memory Spine is designed to run anywhere Python 3.10+ runs — local development, cloud VMs, or containers.

System Requirements

• Python 3.10+ (3.11 recommended)
• pip for package installation
• 2GB+ RAM for production workloads
• 5GB+ disk space for memory storage
• Network access for dependency installation

# Verify Python version
python3 --version
# Should output: Python 3.10.x or higher

# Check pip is available
pip3 --version

# Optional: Create isolated environment
python3 -m venv memory-spine-env
source memory-spine-env/bin/activate

2. Step 1: Install Memory Spine

Installation is a single pip command. Memory Spine includes all dependencies needed for production deployment.

# Install Memory Spine and dependencies
pip install memory-spine

# Verify installation
memory-spine --version
# Should output: memory-spine v1.2.3

# Check available commands
memory-spine --help

Optional Dependencies

For advanced features, install optional packages:

# Production deployment extras
pip install memory-spine[production]

# Includes:
# - uvicorn[standard] (ASGI server)
# - gunicorn (process manager)
# - redis (optional cache backend)
# - prometheus-client (metrics)
# - structlog (structured logging)

The base installation includes everything needed for development and small production deployments. The [production] extras add monitoring, caching, and performance optimizations.

3. Step 2: Configure Server

Memory Spine uses YAML configuration files. The quickstart config gets you running in under 60 seconds:

# Create config directory
mkdir -p ~/.config/memory-spine

# Generate default configuration
memory-spine init --config ~/.config/memory-spine/config.yml

This creates a minimal configuration file. Here’s what it looks like:

# ~/.config/memory-spine/config.yml
server:
  host: "0.0.0.0"
  port: 8080
  workers: 4

storage:
  type: "sqlite"
  path: "~/.local/share/memory-spine/memories.db"
  
vector_index:
  dimensions: 3072  # OpenAI text-embedding-3-large
  metric: "cosine"
  index_type: "hnsw"
  
embeddings:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key: "${OPENAI_API_KEY}"  # Set via environment variable

cache:
  enabled: true
  type: "memory"
  max_size_mb: 512

logging:
  level: "INFO"
  format: "structured"

Set Required Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY="sk-your-openai-api-key-here"

# Reload environment
source ~/.bashrc

4. Step 3: Start Server

Start the Memory Spine server using the configuration you just created:

# Start server with your config
memory-spine start --config ~/.config/memory-spine/config.yml

# Output:
# INFO: Starting Memory Spine v1.2.3
# INFO: Loading configuration from ~/.config/memory-spine/config.yml
# INFO: Initializing vector index (dimensions=3072, metric=cosine)
# INFO: Starting server on http://0.0.0.0:8080
# INFO: Ready to accept connections

The server starts in the foreground by default. For background operation, use the --daemon flag:

# Start as background daemon
memory-spine start --config ~/.config/memory-spine/config.yml --daemon

# Check status
memory-spine status

Health Check

Verify the server is running properly:

# Test health endpoint
curl http://localhost:8080/health

# Expected response:
{
  "status": "healthy",
  "version": "1.2.3",
  "uptime_seconds": 42,
  "memory_count": 0,
  "index_size": "0 MB"
}

5. Step 4: Store First Memory

Now let’s store your first memory. You can use the CLI, HTTP API, or Python client:

Using the CLI

# Store a memory via CLI
memory-spine store \
  --content "Our authentication service uses JWT tokens with 15-minute expiry. Refresh tokens are valid for 30 days and stored in Redis." \
  --tags "authentication,jwt,redis" \
  --importance 8.0

# Output:
# Memory stored successfully
# ID: mem_2Fk9xL7nQ4zR8tY3wE6pA1sD
# Embedding: 3072 dimensions
# Tags: authentication, jwt, redis

Using the HTTP API

# Store via HTTP API
curl -X POST http://localhost:8080/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Code reviews must include security checklist: input validation, auth checks, SQL injection prevention, XSS protection.",
    "tags": ["security", "code-review", "checklist"],
    "importance": 9.0,
    "metadata": {
      "category": "security-policy",
      "team": "engineering"
    }
  }'

Using Python Client

# Python client example
from memory_spine import MemorySpine

# Connect to server
memory = MemorySpine(base_url="http://localhost:8080")

# Store memory
result = memory.store_memory(
    content="Database migrations must be backwards-compatible. Always add new columns as nullable, never drop columns directly.",
    tags=["database", "migrations", "policy"],
    importance=8.5,
    metadata={
        "category": "database-policy",
        "author": "dba-team"
    }
)

print(f"Stored memory: {result.memory_id}")

6. Step 5: Search Memories

Test memory retrieval with semantic search:

# Search via CLI
memory-spine search "How do we handle user authentication?"

# Output:
# Found 1 relevant memories:
#
# [1] Score: 0.87 | ID: mem_2Fk9xL7nQ4zR8tY3wE6pA1sD
#     Tags: authentication, jwt, redis
#     Content: Our authentication service uses JWT tokens with 
#              15-minute expiry. Refresh tokens are valid for 
#              30 days and stored in Redis.

Advanced Search Options

# Search with filters
memory-spine search \
  --query "security policies" \
  --tags "security,code-review" \
  --min-importance 8.0 \
  --limit 5

# Search via HTTP API with filters
curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database best practices",
    "filters": {
      "tags": ["database"],
      "min_importance": 7.0
    },
    "limit": 3
  }'

7. Docker Deployment

For containerized deployments, use our official Docker image:

# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  memory-spine:
    image: chaozcode/memory-spine:latest
    ports:
      - "8080:8080"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./config.yml:/app/config.yml:ro
      - memory-data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  memory-data:
EOF

# Start container
docker-compose up -d

# Check logs
docker-compose logs -f memory-spine

Docker Configuration

Create a production-ready config file:

# config.yml for Docker
server:
  host: "0.0.0.0"
  port: 8080
  workers: 4

storage:
  type: "sqlite"
  path: "/app/data/memories.db"
  
vector_index:
  dimensions: 3072
  metric: "cosine"
  index_type: "hnsw"
  m: 48
  ef_construction: 400
  
embeddings:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key: "${OPENAI_API_KEY}"

cache:
  enabled: true
  type: "memory"
  max_size_mb: 1024

logging:
  level: "INFO"
  format: "json"  # Structured logging for container environments

8. Production Configuration

For production deployments, add these optimizations:

Systemd Service

# Create systemd service file
sudo tee /etc/systemd/system/memory-spine.service << 'EOF'
[Unit]
Description=Memory Spine Server
After=network.target
Wants=network.target

[Service]
Type=exec
User=memory-spine
Group=memory-spine
WorkingDirectory=/opt/memory-spine
ExecStart=/opt/memory-spine/venv/bin/memory-spine start --config /etc/memory-spine/config.yml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
Environment=OPENAI_API_KEY=your-key-here

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl enable memory-spine
sudo systemctl start memory-spine
sudo systemctl status memory-spine

Nginx Reverse Proxy

# Nginx configuration
sudo tee /etc/nginx/sites-available/memory-spine << 'EOF'
server {
    listen 80;
    server_name memory-spine.yourdomain.com;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Timeouts for long-running operations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
    
    # Health check endpoint
    location /health {
        access_log off;
        proxy_pass http://127.0.0.1:8080/health;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/memory-spine /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL with Certbot

# Install certbot and get SSL certificate
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d memory-spine.yourdomain.com

# Auto-renewal is configured automatically

Health Check Verification

Verify your production deployment:

# Check service status
sudo systemctl status memory-spine

# Test health endpoint
curl https://memory-spine.yourdomain.com/health

# Test memory operations
curl -X POST https://memory-spine.yourdomain.com/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "Production deployment successful!", "tags": ["deployment", "success"]}'

Congratulations! You now have Memory Spine running in production. Your AI agents can store and retrieve memories across sessions, maintaining context and knowledge that improves over time.

Next steps: integrate Memory Spine with your agent framework, set up monitoring and alerting, and configure backup strategies for your memory data.