vesper-memory 0.3.0

package/docker-compose.yml

@@ -0,0 +1,65 @@
+services:
+  # Vector Database for embeddings and semantic search
+  qdrant:
+    image: qdrant/qdrant:v1.7.4
+    container_name: vesper-qdrant
+    ports:
+      - "6333:6333"
+    volumes:
+      - qdrant_storage:/qdrant/storage
+    restart: unless-stopped
+    networks:
+      - vesper-network
+    healthcheck:
+      test: ["CMD-SHELL", "bash -c 'echo -e \"GET /healthz HTTP/1.1\\r\\nHost: localhost\\r\\n\\r\\n\" > /dev/tcp/localhost/6333'"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  # Cache layer and working memory
+  redis:
+    image: redis:7-alpine
+    container_name: vesper-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_storage:/data
+    command: redis-server --appendonly yes
+    restart: unless-stopped
+    networks:
+      - vesper-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+  # BGE-large Embedding Service
+  embedding:
+    build:
+      context: ./embedding-service
+      dockerfile: Dockerfile
+    container_name: vesper-embedding
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
+    networks:
+      - vesper-network
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests; requests.get('http://localhost:8000/health').raise_for_status()"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+networks:
+  vesper-network:
+    driver: bridge
+
+volumes:
+  qdrant_storage:
+    driver: local
+  redis_storage:
+    driver: local

package/embedding-service/Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the BGE-large model to avoid runtime download
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-large-en-v1.5')"
+
+# Copy application code
+COPY server.py .
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:8000/health').raise_for_status()"
+
+# Run the server
+CMD ["python", "server.py"]

package/embedding-service/README.md

@@ -0,0 +1,68 @@
+# BGE-Large Embedding Service
+
+REST API for generating 1024-dimensional semantic embeddings using BGE-large-en-v1.5.
+
+## Setup
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Start server
+python server.py
+```
+
+The service will start on `http://localhost:8000`
+
+## API Endpoints
+
+### Health Check
+```bash
+curl http://localhost:8000/health
+```
+
+### Single/Multiple Embeddings
+```bash
+curl -X POST http://localhost:8000/embed \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hello world"}'
+
+# Multiple texts
+curl -X POST http://localhost:8000/embed \
+  -H "Content-Type: application/json" \
+  -d '{"text": ["Hello", "World"]}'
+```
+
+### Batch Processing
+```bash
+curl -X POST http://localhost:8000/embed/batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "texts": ["text1", "text2", "text3"],
+    "batch_size": 32
+  }'
+```
+
+## Integration
+
+From TypeScript/Node.js:
+
+```typescript
+async function getEmbedding(text: string): Promise<number[]> {
+  const response = await fetch('http://localhost:8000/embed', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text })
+  });
+
+  const data = await response.json();
+  return data.embeddings[0];
+}
+```
+
+## Performance
+
+- **Model**: BAAI/bge-large-en-v1.5
+- **Dimensions**: 1024
+- **Throughput**: ~100-200 embeddings/sec (CPU), ~1000+/sec (GPU)
+- **Latency**: ~10-50ms per text (CPU), ~1-5ms (GPU)

package/embedding-service/requirements.txt

@@ -0,0 +1,6 @@
+flask==3.0.0
+sentence-transformers==3.3.1
+torch==2.5.1
+transformers==4.47.1
+numpy==1.26.3
+requests==2.31.0

package/embedding-service/server.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""
+BGE-Large Embedding Service - v3.0
+
+Simple REST API for generating embeddings using BGE-large-en-v1.5.
+Returns 1024-dimensional dense vectors for semantic search.
+"""
+
+from flask import Flask, request, jsonify
+from sentence_transformers import SentenceTransformer
+import numpy as np
+
+app = Flask(__name__)
+
+# Load BGE-large model (1024-dim embeddings)
+print("Loading BGE-large-en-v1.5 model...")
+model = SentenceTransformer('BAAI/bge-large-en-v1.5')
+print("Model loaded successfully!")
+
+@app.route('/health', methods=['GET'])
+def health():
+    """Health check endpoint"""
+    return jsonify({"status": "healthy", "model": "BGE-large-en-v1.5", "dimensions": 1024})
+
+@app.route('/embed', methods=['POST'])
+def embed():
+    """
+    Generate embeddings for text
+
+    Request:
+    {
+        "text": "string" or ["array", "of", "strings"],
+        "normalize": true  # optional, default true
+    }
+
+    Response:
+    {
+        "embeddings": [[...], [...]],
+        "dimensions": 1024,
+        "count": 2
+    }
+    """
+    try:
+        data = request.json
+        text = data.get('text')
+        normalize = data.get('normalize', True)
+
+        if not text:
+            return jsonify({"error": "Missing 'text' field"}), 400
+
+        # Convert single string to list
+        if isinstance(text, str):
+            text = [text]
+
+        # Generate embeddings
+        embeddings = model.encode(
+            text,
+            normalize_embeddings=normalize,
+            show_progress_bar=False
+        )
+
+        # Convert to list for JSON serialization
+        embeddings_list = embeddings.tolist()
+
+        return jsonify({
+            "embeddings": embeddings_list,
+            "dimensions": 1024,
+            "count": len(embeddings_list)
+        })
+
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+@app.route('/embed/batch', methods=['POST'])
+def embed_batch():
+    """
+    Batch embedding endpoint with better performance
+
+    Request:
+    {
+        "texts": ["text1", "text2", ...],
+        "batch_size": 32  # optional
+    }
+    """
+    try:
+        data = request.json
+        texts = data.get('texts')
+        batch_size = data.get('batch_size', 32)
+
+        if not texts or not isinstance(texts, list):
+            return jsonify({"error": "Missing or invalid 'texts' field"}), 400
+
+        embeddings = model.encode(
+            texts,
+            batch_size=batch_size,
+            normalize_embeddings=True,
+            show_progress_bar=False
+        )
+
+        return jsonify({
+            "embeddings": embeddings.tolist(),
+            "dimensions": 1024,
+            "count": len(embeddings)
+        })
+
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=8000, debug=False)

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "vesper-memory",
+  "version": "0.3.0",
+  "description": "AI memory system for Claude Code - Three-layer architecture with semantic search, knowledge graphs, and intelligent retrieval",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "dist/server.js",
+  "bin": {
+    "vesper": "dist/cli.js",
+    "vesper-server": "dist/server-wrapper.js"
+  },
+  "files": [
+    "dist/",
+    "config/",
+    "embedding-service/",
+    "scripts/",
+    "docker-compose.yml",
+    ".env.example",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude-code",
+    "claude",
+    "ai-memory",
+    "semantic-memory",
+    "semantic-search",
+    "knowledge-graph",
+    "embeddings",
+    "rag",
+    "retrieval-augmented-generation",
+    "vector-database",
+    "qdrant",
+    "redis",
+    "bge-embeddings",
+    "typescript"
+  ],
+  "author": "David Fitzsimmons",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fitz2882/vesper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fitz2882/vesper/issues"
+  },
+  "homepage": "https://github.com/fitz2882/vesper#readme",
+  "license": "MIT",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "dev": "node --loader ts-node/esm src/server.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "benchmark": "vitest run tests/benchmarks/memory-performance.test.ts",
+    "benchmark:scientific": "vitest run tests/benchmark/",
+    "benchmark:unit": "vitest run tests/benchmark/statistics.test.ts tests/benchmark/types.test.ts tests/benchmark/metrics-collector.test.ts",
+    "benchmark:real": "npx tsx scripts/run-real-benchmark.ts",
+    "benchmark:accuracy": "npx tsx scripts/run-accuracy-benchmark.ts",
+    "lint": "eslint src tests --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "init:qdrant": "npx tsx scripts/init-qdrant.ts",
+    "fresh-install": "./scripts/fresh-install.sh",
+    "fresh-install:auto": "./scripts/fresh-install-auto.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@qdrant/js-client-rest": "^1.16.2",
+    "better-sqlite3": "^9.2.2",
+    "ioredis": "^5.3.2",
+    "lru-cache": "^10.4.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "bintrees": "^1.0.2",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.39.2",
+    "prettier": "^3.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/FRESH_INSTALL.md

@@ -0,0 +1,280 @@
+# Fresh Installation Scripts
+
+Complete cleanup and fresh installation scripts for Vesper Memory System.
+
+## Overview
+
+These scripts remove **ALL** previous installations and start completely fresh, including:
+- Docker containers, volumes, and networks
+- Node modules and build artifacts
+- All database files and data
+- Logs and temporary files
+- Generated certificates (keeps scripts)
+
+**⚠️ WARNING: ALL DATA WILL BE PERMANENTLY DELETED**
+
+## Usage
+
+### Option 1: Interactive (Recommended)
+
+**Via npm:**
+```bash
+npm run fresh-install
+```
+
+**Via make:**
+```bash
+make fresh-install
+```
+
+**Via script:**
+```bash
+./scripts/fresh-install.sh
+```
+
+**Features:**
+- Safety prompts before deletion
+- Interactive .env creation
+- Colored output with progress
+- Next steps guidance
+
+### Option 2: Automated (CI/CD)
+
+**Via npm:**
+```bash
+npm run fresh-install:auto
+```
+
+**Via make:**
+```bash
+make fresh-install-auto
+```
+
+**Via script:**
+```bash
+./scripts/fresh-install-auto.sh
+```
+
+**Features:**
+- No prompts (fully automated)
+- Auto-creates .env from .env.example
+- Set `AUTO_START=true` to automatically start services
+- Ideal for CI/CD pipelines
+
+**Example with auto-start:**
+```bash
+AUTO_START=true npm run fresh-install:auto
+```
+
+## What Gets Deleted
+
+### Docker Resources
+- All containers (stopped and running)
+- All volumes (all data lost)
+- All networks
+- Dangling images
+
+### Application Files
+- `node_modules/` - All installed dependencies
+- `package-lock.json` - Lock file
+- `dist/` - Build artifacts
+- `.cache/` - Build cache
+- `.turbo/` - Turbo cache
+- `coverage/` - Test coverage
+
+### Data Directories
+- `data/` - SQLite database and application data
+- `logs/` - All log files
+- `.redis-data/` - Redis persistent data
+- `.postgres-data/` - PostgreSQL data
+- `.qdrant-data/` - Qdrant vector data
+
+### Certificates
+- `config/ssl/*` - All certificate files (keeps .sh scripts)
+
+## What Gets Preserved
+
+- Source code (`src/`)
+- Tests (`tests/`)
+- Configuration files (`config/`)
+- Docker Compose configuration
+- Scripts (`.sh` files)
+- `.env.example` template
+- Documentation
+
+## Installation Steps
+
+The scripts perform these steps automatically:
+
+1. **Stop Docker** - Gracefully stop all running containers
+2. **Remove Volumes** - Delete all Docker volumes (data loss)
+3. **Remove Networks** - Clean up Docker networks
+4. **Clean Images** - Remove dangling images
+5. **Remove Dependencies** - Delete node_modules and lock files
+6. **Clean Build** - Remove all build artifacts
+7. **Clean Data** - Delete all database and log files
+8. **Clean Certificates** - Remove old certificates
+9. **Install** - Fresh npm install
+10. **Build** - Build project from source
+
+## Post-Installation Steps
+
+After the fresh install completes:
+
+### 1. Configure Environment
+```bash
+# Edit .env with your settings
+nano .env
+```
+
+**Required changes for production:**
+- Set strong passwords (use `openssl rand -base64 32`)
+- Enable `AUTH_ENABLED=true`
+- Enable `METRICS_AUTH_ENABLED=true`
+- Configure proper domain names
+
+### 2. Generate Certificates
+
+**Development:**
+```bash
+./scripts/generate-dev-certs.sh
+```
+
+**Production:**
+```bash
+docker-compose run --rm certbot certonly \
+  --webroot --webroot-path=/var/www/certbot \
+  -d your-domain.com
+```
+
+### 3. Start Services
+```bash
+docker-compose up -d
+
+# Or use make
+make docker-up
+```
+
+### 4. Verify Installation
+```bash
+# Check service status
+make status
+
+# Run tests
+npm test
+
+# Check health
+curl -I http://localhost:8080/health
+```
+
+### 5. Generate API Key (Optional)
+```bash
+npm run generate-api-key -- --tier unlimited --name 'Development'
+```
+
+## Troubleshooting
+
+### Permission Denied
+
+```bash
+chmod +x scripts/fresh-install.sh
+chmod +x scripts/fresh-install-auto.sh
+```
+
+### Docker Issues
+
+```bash
+# If Docker services won't stop
+docker ps -a | grep vesper | awk '{print $1}' | xargs docker rm -f
+
+# If volumes won't delete
+docker volume prune -f
+```
+
+### Build Fails
+
+```bash
+# Clean npm cache
+npm cache clean --force
+
+# Try again
+npm run fresh-install
+```
+
+### Services Won't Start
+
+```bash
+# Check Docker daemon
+docker info
+
+# Check logs
+docker-compose logs -f
+
+# Restart Docker daemon (macOS)
+killall Docker && open -a Docker
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+- name: Fresh Install Vesper
+  run: npm run fresh-install:auto
+  env:
+    AUTO_START: true
+    AUTH_ENABLED: false  # Disable for testing
+```
+
+### Docker Compose Example
+
+```yaml
+version: '3.8'
+services:
+  vesper-install:
+    image: node:20
+    volumes:
+      - .:/app
+    working_dir: /app
+    command: /app/scripts/fresh-install-auto.sh
+```
+
+## Safety Features
+
+### Interactive Script
+- Requires explicit "yes" confirmation
+- Shows detailed warning of what will be deleted
+- Prompts for .env creation
+- Provides next steps guidance
+
+### Automated Script
+- Designed for trusted environments only
+- No user interaction required
+- Logs all actions
+- Returns non-zero exit code on failure
+
+## Performance
+
+**Typical runtime:** 2-5 minutes (depending on network speed)
+
+**Breakdown:**
+- Cleanup: 10-30 seconds
+- npm install: 1-3 minutes
+- Build: 30-60 seconds
+
+## Best Practices
+
+1. **Backup First** - Always backup important data before running
+2. **Use Interactive** - Use interactive version for manual operations
+3. **Use Automated** - Use automated version only for CI/CD
+4. **Review Output** - Check output for any errors
+5. **Verify Installation** - Run tests after installation
+
+## Support
+
+If you encounter issues:
+
+1. Check the troubleshooting section above
+2. Review logs: `docker-compose logs -f`
+3. Check Docker status: `make status`
+4. File an issue: https://github.com/fitz2882/vesper/issues