├── .air.toml ├── .dockerignore ├── .env.example ├── .github └── workflows │ ├── main.yml │ └── release.yml ├── .gitignore ├── .golangci.yml ├── .gosec.json ├── CLAUDE.md ├── CONTRIBUTING.md ├── Dockerfile ├── Dockerfile.dev ├── LICENSE ├── Makefile ├── README.md ├── api └── openapi.yaml ├── cmd ├── migrate │ └── main.go ├── openapi │ └── main.go └── server │ ├── main.go │ └── main_test.go ├── configs ├── dev │ └── config.yaml ├── docker │ └── config.yaml └── production │ └── config.yaml ├── docker-compose.dev.yml ├── docker-compose.yml ├── go.mod ├── go.sum ├── internal ├── analytics │ ├── memory_analytics.go │ ├── memory_analytics_test.go │ └── task_integration_test.go ├── audit │ ├── audit_logger.go │ └── audit_logger_test.go ├── bulk │ ├── alias_manager.go │ ├── bulk_exporter.go │ ├── bulk_importer.go │ ├── bulk_manager.go │ └── bulk_manager_simple_test.go ├── chains │ ├── analyzer.go │ ├── memory_chain.go │ ├── memory_chain_test.go │ └── store.go ├── chunking │ ├── chunker.go │ └── chunker_test.go ├── circuitbreaker │ ├── circuit_breaker.go │ ├── circuit_breaker_test.go │ └── circuit_breaker_test.go.bak3 ├── config │ ├── config.go │ └── config_test.go ├── context │ ├── detector.go │ └── detector_test.go ├── decay │ ├── memory_decay.go │ ├── memory_decay_test.go │ └── summarizer.go ├── deployment │ ├── graceful_shutdown.go │ ├── health.go │ └── monitoring.go ├── di │ ├── container.go │ └── container_test.go ├── embeddings │ ├── circuit_breaker_wrapper.go │ ├── openai.go │ ├── openai_test.go │ └── retry_wrapper.go ├── errors │ ├── mcp_integration.go │ ├── multi_protocol_integration_test.go │ ├── standard_errors.go │ └── standard_errors_test.go ├── final_validation_test.go ├── intelligence │ ├── builtin_patterns.go │ ├── citation_manager.go │ ├── confidence_engine.go │ ├── conflict_detector.go │ ├── conflict_detector_test.go │ ├── conflict_resolver.go │ ├── conflict_resolver_test.go │ ├── extractors.go │ ├── freshness_manager.go │ ├── knowledge_graph.go │ ├── knowledge_graph_test.go │ ├── learning_engine.go │ ├── learning_engine_test.go │ ├── multi_repo_engine.go │ ├── multi_repo_engine_test.go │ ├── pattern_engine.go │ ├── pattern_engine_test.go │ ├── pattern_matcher.go │ ├── search_explainer.go │ └── sequence_recognizer.go ├── logging │ └── logger.go ├── mcp │ ├── backward_compatibility.go │ ├── backward_compatibility_test.go │ ├── consolidated_tools.go │ ├── consolidated_tools_test.go │ ├── constants.go │ ├── core_handlers_test.go │ ├── executor.go │ ├── repository_test.go │ ├── server.go │ ├── server_test.go │ ├── task_handlers_test.go │ └── task_logic_test.go ├── monitoring │ └── performance_monitor.go ├── performance │ ├── cache_manager.go │ ├── metrics_collector.go │ ├── optimizer.go │ ├── optimizer_test.go │ ├── performance_simple_test.go │ ├── query_optimizer.go │ └── resource_manager.go ├── persistence │ ├── backup.go │ └── backup_test.go ├── relationships │ ├── detector.go │ ├── manager.go │ └── manager_test.go ├── retry │ └── retry.go ├── security │ ├── access_control.go │ ├── access_control_test.go │ ├── encryption.go │ └── encryption_test.go ├── storage │ ├── circuit_breaker_wrapper.go │ ├── circuit_breaker_wrapper_test.go │ ├── context_adapter.go │ ├── interface.go │ ├── interface_test.go │ ├── mock_store.go │ ├── pattern_adapter.go │ ├── pool │ │ ├── connection_pool.go │ │ └── connection_pool_test.go │ ├── qdrant.go │ ├── qdrant_test.go │ ├── relationships.go │ ├── retry_wrapper.go │ └── retry_wrapper_test.go ├── templates │ └── memory_templates.go ├── threading │ ├── memory_store.go │ └── memory_threads.go ├── types │ └── extended_types.go ├── websocket │ └── hub.go └── workflow │ ├── context_suggester.go │ ├── context_suggester_test.go │ ├── flow_detector.go │ ├── flow_detector_test.go │ ├── pattern_analyzer.go │ ├── pattern_analyzer_test.go │ ├── todo_tracker.go │ └── todo_tracker_test.go ├── mcp-proxy.js ├── pkg └── types │ ├── extended_metadata.go │ ├── relationships.go │ ├── types.go │ └── types_test.go └── scripts ├── format-code.sh └── init-postgres.sql /.air.toml: -------------------------------------------------------------------------------- 1 | root = "." 2 | tmp_dir = "tmp" 3 | 4 | [build] 5 | # Binary to execute after build 6 | bin = "./tmp/lerian-mcp-memory-server" 7 | # Arguments to pass to the binary 8 | args_bin = ["-mode=http", "-addr=:9080"] 9 | # Build command 10 | cmd = "go build -o ./tmp/lerian-mcp-memory-server ./cmd/server" 11 | # Watch these directories 12 | include_dir = ["cmd", "internal", "pkg"] 13 | # Watch these file extensions 14 | include_ext = ["go", "tpl", "tmpl", "html"] 15 | # Exclude these directories 16 | exclude_dir = ["assets", "tmp", "vendor", "testdata", ".git", ".idea"] 17 | # Exclude specific files 18 | exclude_file = [] 19 | # Exclude unchanged files 20 | exclude_unchanged = true 21 | # Follow symlinks 22 | follow_symlink = false 23 | # Build delay after file change (ms) 24 | delay = 1000 25 | # Stop running old binary before starting new one 26 | kill_delay = 500 27 | 28 | [color] 29 | # Colorize output 30 | main = "magenta" 31 | watcher = "cyan" 32 | build = "yellow" 33 | runner = "green" 34 | 35 | [log] 36 | # Show log time 37 | time = false 38 | 39 | [misc] 40 | # Delete tmp directory on exit 41 | clean_on_exit = true -------------------------------------------------------------------------------- /.dockerignore: -------------------------------------------------------------------------------- 1 | # Ignore files and directories not needed in Docker context 2 | 3 | # Version control 4 | .git/ 5 | .gitignore 6 | .gitattributes 7 | 8 | # Development files 9 | .vscode/ 10 | .idea/ 11 | *.swp 12 | *.swo 13 | *~ 14 | 15 | # Documentation (except essential ones) 16 | *.md 17 | !README.md 18 | examples/ 19 | 20 | # Build artifacts 21 | bin/ 22 | dist/ 23 | build/ 24 | *.exe 25 | *.dll 26 | *.so 27 | *.dylib 28 | 29 | # Test files 30 | *_test.go 31 | testdata/ 32 | coverage.out 33 | *.test 34 | 35 | # Temporary files 36 | tmp/ 37 | temp/ 38 | .tmp/ 39 | *.tmp 40 | *.temp 41 | 42 | # OS generated files 43 | .DS_Store 44 | .DS_Store? 45 | ._* 46 | .Spotlight-V100 47 | .Trashes 48 | ehthumbs.db 49 | Thumbs.db 50 | 51 | # IDE files 52 | .vscode/ 53 | .idea/ 54 | *.iml 55 | *.ipr 56 | *.iws 57 | 58 | # Dependencies (will be downloaded during build) 59 | vendor/ 60 | 61 | # Local configuration files 62 | .env 63 | .env.* 64 | !.env.example 65 | 66 | # Logs 67 | *.log 68 | logs/ 69 | 70 | # Data directories 71 | data/ 72 | backups/ 73 | 74 | # CI/CD files (not needed in container) 75 | .github/ 76 | .gitlab-ci.yml 77 | .travis.yml 78 | Jenkinsfile 79 | 80 | # Docker files (avoid recursion) 81 | Dockerfile* 82 | docker-compose*.yml 83 | .dockerignore 84 | 85 | # Development scripts 86 | scripts/dev/ 87 | scripts/local/ 88 | Makefile.local 89 | 90 | # Coverage and profiling 91 | *.cover 92 | *.prof 93 | *.out 94 | 95 | # Node.js (if any frontend assets) 96 | node_modules/ 97 | npm-debug.log* 98 | yarn-debug.log* 99 | yarn-error.log* 100 | 101 | # Python (if any scripts) 102 | __pycache__/ 103 | *.py[cod] 104 | *$py.class 105 | *.egg-info/ 106 | .pytest_cache/ 107 | 108 | # Local database files 109 | *.db 110 | *.sqlite 111 | *.sqlite3 -------------------------------------------------------------------------------- /.env.example: -------------------------------------------------------------------------------- 1 | # Lerian MCP Memory Server - Configuration 2 | # Copy this file to .env and update the values as needed 3 | # 4 | # This file is the single source of truth for all configuration 5 | # All variables are automatically passed to Docker containers via env_file 6 | 7 | # ================================================================ 8 | # REQUIRED - API & EMBEDDING 9 | # ================================================================ 10 | 11 | # OpenAI Configuration (Required for embeddings) 12 | # This defaults to your global OPENAI_API_KEY environment variable 13 | # If you don't have a global OPENAI_API_KEY set, replace with your actual key 14 | OPENAI_API_KEY=${OPENAI_API_KEY:-your_openai_api_key_here} 15 | OPENAI_EMBEDDING_MODEL=text-embedding-ada-002 16 | 17 | # ================================================================ 18 | # SERVER CONFIGURATION 19 | # ================================================================ 20 | 21 | # Server ports 22 | MCP_HOST_PORT=9080 # Main MCP API port 23 | MCP_HEALTH_PORT=9081 # Health check endpoint 24 | MCP_METRICS_PORT=9082 # Metrics endpoint (optional) 25 | 26 | # Server host 27 | MCP_MEMORY_HOST=localhost 28 | 29 | # ================================================================ 30 | # VECTOR DATABASE (QDRANT) 31 | # ================================================================ 32 | 33 | # Qdrant Vector Database ports 34 | QDRANT_HOST_PORT=6333 # Qdrant HTTP API 35 | QDRANT_GRPC_PORT=6334 # Qdrant gRPC API 36 | 37 | # Vector configuration 38 | QDRANT_COLLECTION=claude_memory # Collection name 39 | MCP_MEMORY_EMBEDDING_DIMENSION=1536 # Embedding dimension (ada-002) 40 | 41 | # ================================================================ 42 | # STORAGE & DATA 43 | # ================================================================ 44 | 45 | # SQLite metadata storage 46 | SQLITE_DB_PATH=/app/data/memory.db 47 | 48 | # Data retention 49 | RETENTION_DAYS=90 50 | 51 | # ================================================================ 52 | # LOGGING & MONITORING 53 | # ================================================================ 54 | 55 | # Logging configuration 56 | MCP_MEMORY_LOG_LEVEL=info # debug, info, warn, error 57 | LOG_FORMAT=json 58 | 59 | # Health checks 60 | HEALTH_CHECK_INTERVAL=30s 61 | HEALTH_CHECK_TIMEOUT=10s 62 | HEALTH_CHECK_RETRIES=3 63 | 64 | # ================================================================ 65 | # SECURITY & BACKUP 66 | # ================================================================ 67 | 68 | # Security settings 69 | MCP_MEMORY_ENCRYPTION_ENABLED=true 70 | MCP_MEMORY_ACCESS_CONTROL_ENABLED=true 71 | 72 | # Backup configuration 73 | MCP_MEMORY_BACKUP_ENABLED=true 74 | MCP_MEMORY_BACKUP_INTERVAL_HOURS=24 75 | 76 | # ================================================================ 77 | # MCP PROTOCOL CONFIGURATION 78 | # ================================================================ 79 | 80 | # CORS settings (for web clients) 81 | MCP_MEMORY_CORS_ENABLED=true 82 | MCP_MEMORY_CORS_ORIGINS=http://localhost:*,https://localhost:* 83 | 84 | # Protocol support 85 | MCP_STDIO_ENABLED=true # stdio + proxy support 86 | MCP_HTTP_ENABLED=true # Direct HTTP JSON-RPC 87 | MCP_WS_ENABLED=true # WebSocket support 88 | MCP_SSE_ENABLED=true # Server-Sent Events 89 | 90 | # MCP proxy configuration (for stdio clients) 91 | MCP_SERVER_HOST=localhost 92 | MCP_SERVER_PORT=9080 93 | MCP_SERVER_PATH=/mcp 94 | MCP_PROXY_DEBUG=false 95 | 96 | # ================================================================ 97 | # OPTIONAL - ADVANCED FEATURES 98 | # ================================================================ 99 | 100 | # Multi-repository support 101 | MCP_MEMORY_MAX_REPOSITORIES=100 102 | MCP_MEMORY_ENABLE_TEAM_LEARNING=true 103 | 104 | # Pattern recognition 105 | MCP_MEMORY_PATTERN_MIN_FREQUENCY=3 106 | MCP_MEMORY_REPO_SIMILARITY_THRESHOLD=0.6 107 | 108 | # Performance optimization 109 | MCP_MEMORY_VECTOR_CACHE_MAX_SIZE=1000 110 | MCP_MEMORY_QUERY_CACHE_TTL_MINUTES=15 111 | 112 | # Circuit breaker settings 113 | MCP_MEMORY_CIRCUIT_BREAKER_ENABLED=true 114 | MCP_MEMORY_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 115 | MCP_MEMORY_CIRCUIT_BREAKER_TIMEOUT_SECONDS=60 116 | 117 | # ================================================================ 118 | # AUTO-UPDATE SETTINGS (WATCHTOWER) 119 | # ================================================================ 120 | 121 | # How often to check for updates (seconds) 122 | WATCHTOWER_POLL_INTERVAL=300 # 5 minutes 123 | 124 | # Set to false to disable automatic updates 125 | WATCHTOWER_LABEL_ENABLE=true 126 | 127 | # Remove old images after updating 128 | WATCHTOWER_CLEANUP=true 129 | 130 | # ================================================================ 131 | # DATABASE TUNING (OPTIONAL) 132 | # ================================================================ 133 | 134 | # Storage provider 135 | MCP_MEMORY_STORAGE_PROVIDER=qdrant 136 | MCP_MEMORY_DB_TYPE=sqlite 137 | 138 | # Performance settings 139 | MCP_MEMORY_MAX_CONNECTIONS=10 140 | MCP_MEMORY_CONNECTION_TIMEOUT_SECONDS=30 141 | MCP_MEMORY_QUERY_TIMEOUT_SECONDS=60 142 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI/CD 2 | 3 | on: 4 | push: 5 | branches: [main, develop] 6 | pull_request: 7 | branches: [main, develop] 8 | release: 9 | types: [created] 10 | 11 | jobs: 12 | test-and-lint: 13 | name: Test & Lint 14 | runs-on: ubuntu-latest 15 | 16 | steps: 17 | - name: Checkout code 18 | uses: actions/checkout@v4 19 | 20 | - name: Set up Go 21 | uses: actions/setup-go@v5 22 | with: 23 | go-version: '1.23' 24 | 25 | - name: Cache Go modules 26 | uses: actions/cache@v4 27 | with: 28 | path: | 29 | ~/go/pkg/mod 30 | ~/.cache/go-build 31 | key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}-${{ hashFiles('**/*.go') }} 32 | restore-keys: | 33 | ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}- 34 | ${{ runner.os }}-go- 35 | 36 | - name: Clean Go caches 37 | run: | 38 | go clean -cache -modcache -testcache || true 39 | 40 | - name: Download dependencies 41 | run: go mod download 42 | 43 | - name: Install build dependencies 44 | run: | 45 | sudo apt-get update 46 | sudo apt-get install -y build-essential 47 | 48 | - name: Run tests with coverage 49 | run: go test -v -coverprofile=coverage.txt -covermode=atomic ./... 50 | 51 | - name: Run golangci-lint 52 | uses: golangci/golangci-lint-action@v8 53 | with: 54 | version: v2.1.6 55 | args: --timeout=5m --config=.golangci.yml 56 | skip-cache: false 57 | 58 | - name: Build server binary 59 | run: go build -o server ./cmd/server 60 | 61 | - name: Integration tests 62 | run: | 63 | # Basic integration test - ensure server starts 64 | timeout 5s ./server -mode=stdio || true 65 | echo "Integration test completed" 66 | 67 | security: 68 | name: Security Scan 69 | runs-on: ubuntu-latest 70 | if: github.event_name == 'push' && github.ref == 'refs/heads/main' 71 | 72 | steps: 73 | - name: Checkout code 74 | uses: actions/checkout@v4 75 | 76 | - name: Set up Go 77 | uses: actions/setup-go@v5 78 | with: 79 | go-version: '1.23' 80 | 81 | - name: Run gosec security scanner 82 | continue-on-error: true 83 | run: | 84 | go install github.com/securecodewarrior/gosec/v2/cmd/gosec@latest 85 | gosec ./... || echo "Security scan completed with warnings" 86 | 87 | docker: 88 | name: Build & Push Docker 89 | runs-on: ubuntu-latest 90 | needs: [test-and-lint] 91 | if: github.event_name == 'push' && github.ref == 'refs/heads/main' 92 | 93 | permissions: 94 | contents: read 95 | packages: write 96 | id-token: write 97 | attestations: write 98 | 99 | steps: 100 | - name: Checkout code 101 | uses: actions/checkout@v4 102 | 103 | - name: Set up Docker Buildx 104 | uses: docker/setup-buildx-action@v3 105 | 106 | - name: Log in to GitHub Container Registry 107 | uses: docker/login-action@v3 108 | with: 109 | registry: ghcr.io 110 | username: ${{ github.actor }} 111 | password: ${{ secrets.GITHUB_TOKEN }} 112 | 113 | - name: Build and push Docker image 114 | id: push 115 | uses: docker/build-push-action@v5 116 | with: 117 | context: . 118 | platforms: linux/amd64,linux/arm64 119 | push: true 120 | tags: | 121 | ghcr.io/lerianstudio/lerian-mcp-memory:latest 122 | ghcr.io/lerianstudio/lerian-mcp-memory:${{ github.sha }} 123 | cache-from: type=gha 124 | cache-to: type=gha,mode=max 125 | 126 | - name: Generate build provenance 127 | uses: actions/attest-build-provenance@v1 128 | with: 129 | subject-name: ghcr.io/lerianstudio/lerian-mcp-memory 130 | subject-digest: ${{ steps.push.outputs.digest }} 131 | push-to-registry: true 132 | 133 | release: 134 | name: Release 135 | runs-on: ubuntu-latest 136 | needs: [test-and-lint, security] 137 | if: github.event_name == 'release' 138 | 139 | permissions: 140 | contents: write 141 | packages: write 142 | 143 | steps: 144 | - name: Checkout code 145 | uses: actions/checkout@v4 146 | with: 147 | fetch-depth: 0 148 | 149 | - name: Set up Go 150 | uses: actions/setup-go@v5 151 | with: 152 | go-version: '1.23' 153 | 154 | - name: Run GoReleaser 155 | uses: goreleaser/goreleaser-action@v5 156 | with: 157 | distribution: goreleaser 158 | version: latest 159 | args: release --clean 160 | env: 161 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 162 | 163 | package-registry: 164 | name: Publish to GitHub Packages 165 | runs-on: ubuntu-latest 166 | needs: [test-and-lint] 167 | if: github.event_name == 'push' && github.ref == 'refs/heads/main' 168 | 169 | permissions: 170 | contents: read 171 | packages: write 172 | 173 | steps: 174 | - name: Checkout code 175 | uses: actions/checkout@v4 176 | 177 | - name: Set up Go 178 | uses: actions/setup-go@v5 179 | with: 180 | go-version: '1.23' 181 | 182 | - name: Install build dependencies for CGO 183 | run: | 184 | sudo apt-get update 185 | sudo apt-get install -y build-essential 186 | 187 | - name: Build binaries for multiple platforms 188 | run: | 189 | mkdir -p bin 190 | # Build for Linux (CGO enabled for native platform) 191 | go build -ldflags="-s -w" -o bin/lerian-mcp-memory-linux-amd64 ./cmd/server 192 | 193 | # Cross-compile for other platforms (CGO disabled for cross-compilation) 194 | CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o bin/lerian-mcp-memory-linux-arm64 ./cmd/server 195 | CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o bin/lerian-mcp-memory-darwin-amd64 ./cmd/server 196 | CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o bin/lerian-mcp-memory-darwin-arm64 ./cmd/server 197 | CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o bin/lerian-mcp-memory-windows-amd64.exe ./cmd/server 198 | 199 | - name: Create version info 200 | run: | 201 | mkdir -p packages 202 | echo "commit: ${{ github.sha }}" > packages/VERSION 203 | echo "ref: ${{ github.ref }}" >> packages/VERSION 204 | echo "build_date: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> packages/VERSION 205 | 206 | - name: Package binaries 207 | run: | 208 | cd bin 209 | for binary in *; do 210 | if [[ "$binary" == *.exe ]]; then 211 | zip -9 "../packages/${binary%.exe}.zip" "$binary" 212 | else 213 | tar -czf "../packages/${binary}.tar.gz" "$binary" 214 | fi 215 | done 216 | 217 | - name: Upload artifacts to GitHub 218 | uses: actions/upload-artifact@v4 219 | with: 220 | name: lerian-mcp-memory-binaries-${{ github.sha }} 221 | path: packages/ 222 | retention-days: 30 223 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Binaries for programs and plugins 2 | *.exe 3 | *.exe~ 4 | *.dll 5 | *.so 6 | *.dylib 7 | 8 | # Test binary, built with `go test -c` 9 | *.test 10 | 11 | # Output of the go coverage tool, specifically when used with LiteIDE 12 | *.out 13 | coverage.html 14 | 15 | # Project binaries 16 | lerian-mcp-memory 17 | lerian-mcp-memory_unix 18 | lerian-mcp-memory-server 19 | /bin/ 20 | /server 21 | 22 | # Dependency directories (remove the comment below to include it) 23 | # vendor/ 24 | 25 | # Go workspace file 26 | go.work 27 | 28 | # Environment variables 29 | .env 30 | .env.local 31 | .env.*.local 32 | 33 | # Docker volumes and data 34 | data/ 35 | docker-compose.override.yml 36 | 37 | # IDE 38 | .vscode/ 39 | .idea/ 40 | *.swp 41 | *.swo 42 | 43 | # OS 44 | .DS_Store 45 | Thumbs.db 46 | 47 | # Logs 48 | *.log 49 | 50 | # Audit logs (all development audit logs) 51 | **/audit_logs/ 52 | audit_logs/ 53 | 54 | # Local development 55 | /dist/ 56 | /tmp/ 57 | 58 | # AI development artifacts 59 | tmp/ 60 | *.tmp 61 | .claude/ 62 | CLAUDE.md 63 | 64 | # Development backup files 65 | *.bak 66 | *.backup 67 | *.bak2 68 | 69 | # Marketing prototypes (should be in separate repo) 70 | /lp/ 71 | 72 | # External documentation copies 73 | docs/tmp/ 74 | 75 | # Next.js build artifacts 76 | web-ui/.next/ 77 | web-ui/out/ 78 | web-ui/.env.local 79 | web-ui/.env.*.local 80 | web-ui/node_modules/ 81 | 82 | coverage.out 83 | coverage.txt 84 | -------------------------------------------------------------------------------- /.golangci.yml: -------------------------------------------------------------------------------- 1 | version: "2" 2 | 3 | run: 4 | timeout: 10m 5 | tests: true 6 | go: '1.23' 7 | 8 | linters: 9 | enable: 10 | # Core quality checks 11 | - errcheck # Check for unchecked errors 12 | - govet # Vet examines Go source code 13 | - ineffassign # Detects ineffectual assignments 14 | - staticcheck # Advanced Go linter 15 | - unused # Checks for unused constants, variables, functions and types 16 | 17 | # Security and best practices 18 | - gosec # Security analyzer 19 | - bodyclose # Check HTTP response bodies are closed 20 | - contextcheck # Check the function whether use a non-inherited context 21 | - errorlint # Find code that will cause problems with the error wrapping scheme 22 | - copyloopvar # Checks for pointers to enclosing loop variables 23 | - goconst # Finds repeated strings that could be replaced by a constant 24 | - gocyclo # Computes and checks the cyclomatic complexity of functions 25 | - nestif # Reports deeply nested if statements 26 | 27 | # Code quality 28 | - dupl # Tool for code clone detection 29 | - durationcheck # Check for two durations multiplied together 30 | - misspell # Finds commonly misspelled English words in comments 31 | - prealloc # Find slice declarations that could potentially be preallocated 32 | - unconvert # Remove unnecessary type conversions 33 | - unparam # Reports unused function parameters 34 | - whitespace # Tool for detection of leading and trailing whitespace 35 | 36 | # Additional quality checks 37 | - gocritic # Comprehensive Go linter 38 | - nilnil # Checks that there is no simultaneous return of nil error and nil value 39 | - nolintlint # Reports ill-formed or insufficient nolint directives 40 | settings: 41 | gocyclo: 42 | min-complexity: 15 43 | nestif: 44 | min-complexity: 5 45 | gocritic: 46 | enabled-tags: 47 | - diagnostic 48 | - style 49 | - performance 50 | disabled-checks: 51 | - commentedOutCode 52 | - ifElseChain 53 | gosec: 54 | excludes: 55 | - G204 # Subprocess launched with variable 56 | - G304 # File path provided as taint input 57 | staticcheck: 58 | checks: ["all"] 59 | 60 | issues: 61 | max-issues-per-linter: 0 62 | max-same-issues: 0 63 | -------------------------------------------------------------------------------- /.gosec.json: -------------------------------------------------------------------------------- 1 | { 2 | "tests": false, 3 | "exclude-dir": [ 4 | "internal/storage/chroma-go", 5 | "pkg/mcp/examples", 6 | "pkg/mcp/testutil" 7 | ], 8 | "exclude-rules": [] 9 | } -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md 2 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 | 5 | ## Project Overview 6 | 7 | Lerian MCP Memory Server is a high-performance Go-based Model Context Protocol (MCP) server that gives AI assistants persistent memory capabilities. It stores conversations, learns patterns, and provides intelligent context suggestions across sessions and projects. The server supports multiple transport protocols (stdio, WebSocket, SSE, HTTP) and uses Qdrant for vector storage with OpenAI embeddings. 8 | 9 | **Key Focus**: This is a Go-only project focused on the MCP server engine. The web-ui has been removed to maintain simplicity and performance. 10 | 11 | ## Core Architecture 12 | 13 | ### Technology Stack 14 | - **Language**: Go 1.23+ with gomcp-sdk v1.0.3 15 | - **Vector Database**: Qdrant for embeddings and similarity search 16 | - **Metadata Storage**: SQLite for structured data 17 | - **AI Service**: OpenAI for text embeddings 18 | - **Transport**: Multiple protocols (stdio, WebSocket, SSE, HTTP) 19 | 20 | ### Key Components 21 | - `internal/mcp/` - MCP protocol handlers and memory server implementation 22 | - `internal/storage/` - Qdrant vector database and SQLite adapters 23 | - `internal/intelligence/` - Pattern recognition, learning engines, conflict detection 24 | - `internal/embeddings/` - OpenAI integration with circuit breakers and retries 25 | - `internal/chunking/` - Smart content chunking with context awareness 26 | - `pkg/types/` - Core data structures and type definitions 27 | 28 | ### Entry Points 29 | - `cmd/server/main.go` - Main server with stdio/HTTP mode support 30 | - `cmd/migrate/main.go` - Database migration utility 31 | - `cmd/openapi/main.go` - OpenAPI specification generator 32 | 33 | ## Common Development Commands 34 | 35 | ### Environment Setup 36 | ```bash 37 | # Initial setup with environment file 38 | make setup-env 39 | 40 | # Production mode - uses pre-built image from GHCR 41 | make docker-up 42 | 43 | # Development mode with hot reload 44 | make dev-docker-up 45 | 46 | # Regular development mode (stdio) 47 | make dev 48 | 49 | # HTTP mode for testing 50 | make dev-http 51 | ``` 52 | 53 | ### Building and Testing 54 | ```bash 55 | # Build binary 56 | make build 57 | 58 | # Run all tests 59 | make test 60 | 61 | # Run tests with coverage (70% threshold) 62 | make test-coverage 63 | 64 | # Run integration tests 65 | make test-integration 66 | 67 | # Run with race detector 68 | make test-race 69 | 70 | # Run benchmarks 71 | make benchmark 72 | ``` 73 | 74 | ### Code Quality 75 | ```bash 76 | # Format code and run imports 77 | make fmt 78 | 79 | # Run linter (golangci-lint) 80 | make lint 81 | 82 | # Run go vet 83 | make vet 84 | 85 | # Security scanning (gosec + govulncheck) 86 | make security-scan 87 | 88 | # Complete CI pipeline 89 | make ci 90 | ``` 91 | 92 | ### Docker Operations 93 | ```bash 94 | # Start with docker-compose 95 | make docker-compose-up 96 | 97 | # Stop services 98 | make docker-compose-down 99 | 100 | # Development mode with hot reload 101 | make dev-up 102 | make dev-logs 103 | make dev-restart 104 | ``` 105 | 106 | ### Testing Individual Components 107 | ```bash 108 | # Test specific package 109 | go test -v ./internal/mcp/ 110 | 111 | # Test with integration tag 112 | go test -tags=integration -v ./internal/storage/ 113 | 114 | # Test specific function 115 | go test -v -run TestMemorySearch ./internal/mcp/ 116 | ``` 117 | 118 | ## Environment Configuration 119 | 120 | Copy `.env.example` to `.env` and configure: 121 | 122 | ### Required 123 | - `OPENAI_API_KEY` - Your OpenAI API key for embeddings 124 | 125 | ### Key Environment Variables 126 | - `MCP_HOST_PORT` - Main MCP server port (default: 9080) 127 | - `QDRANT_HOST_PORT` - Qdrant vector DB port (default: 6333) 128 | - `MCP_MEMORY_LOG_LEVEL` - Logging level (debug, info, warn, error) 129 | - `MCP_MEMORY_VECTOR_DIM` - Embedding dimension (default: 1536 for ada-002) 130 | 131 | ## Code Conventions 132 | 133 | ### Error Handling 134 | - Always return explicit errors, never panic in production code 135 | - Use context.Context as first parameter for all operations 136 | - Implement circuit breakers for external service calls (OpenAI, Qdrant) 137 | 138 | ### Testing Patterns 139 | - Use testify/assert for assertions 140 | - Mock external dependencies (OpenAI API, Qdrant) 141 | - Integration tests tagged with `integration` 142 | - Benchmark tests for performance-critical code 143 | 144 | ### Memory Management 145 | - 41 MCP tools for memory operations (search, store, analyze, etc.) 146 | - Smart chunking with configurable strategies 147 | - Vector similarity search with confidence scoring 148 | - Cross-repository pattern learning 149 | 150 | ### Package Structure 151 | ``` 152 | internal/ 153 | ├── mcp/ # MCP protocol and memory server 154 | ├── storage/ # Database and vector storage 155 | ├── intelligence/ # Learning engines and pattern detection 156 | ├── embeddings/ # OpenAI integration with reliability 157 | ├── chunking/ # Content processing and chunking 158 | └── config/ # Configuration management 159 | ``` 160 | 161 | ### Database Schema 162 | - SQLite for metadata (chunks, relationships, sessions) 163 | - Qdrant for vector embeddings and similarity search 164 | - Automatic backup and persistence management 165 | 166 | ## Important Implementation Notes 167 | 168 | ### MCP Transport Support 169 | The server supports multiple transport protocols: 170 | - **stdio + proxy** - For legacy MCP clients (Claude Desktop, VS Code) 171 | - **WebSocket** - Real-time bidirectional communication 172 | - **SSE** - Server-sent events with HTTP fallback 173 | - **Direct HTTP** - Simple JSON-RPC over HTTP 174 | 175 | ### Vector Operations 176 | - Uses Qdrant for high-performance vector search 177 | - OpenAI text-embedding-ada-002 by default (1536 dimensions) 178 | - Circuit breakers and retries for reliability 179 | - Intelligent chunking to maximize embedding effectiveness 180 | 181 | ### Memory Intelligence 182 | - Pattern recognition across conversations and repositories 183 | - Conflict detection for contradictory decisions 184 | - Learning engine that improves suggestions over time 185 | - Cross-repository knowledge sharing 186 | 187 | ### Performance Considerations 188 | - Connection pooling for Qdrant 189 | - Embedding caching to reduce OpenAI API calls 190 | - Query optimization with performance monitoring 191 | - Graceful degradation under high load 192 | 193 | ## Deployment Endpoints 194 | 195 | When running via docker-compose: 196 | - `http://localhost:9080/mcp` - Main MCP JSON-RPC endpoint 197 | - `http://localhost:9080/health` - Health check 198 | - `ws://localhost:9080/ws` - WebSocket endpoint 199 | - `http://localhost:9080/sse` - Server-sent events endpoint 200 | - `http://localhost:6333` - Qdrant vector database UI 201 | 202 | ## Troubleshooting 203 | 204 | ### Common Issues 205 | - **Connection refused**: Run `make docker-compose-restart` 206 | - **OpenAI API errors**: Check API key and account credits in `.env` 207 | - **Vector search failures**: Verify Qdrant is running (`docker logs mcp-qdrant`) 208 | - **Memory not persisting**: Check volume mounts and permissions 209 | 210 | ### Debugging 211 | ```bash 212 | # View logs 213 | docker logs mcp-memory-server 214 | make dev-logs 215 | 216 | # Health check 217 | curl http://localhost:9080/health 218 | 219 | # Test MCP protocol 220 | echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker exec -i mcp-memory-server node /app/mcp-proxy.js 221 | ``` -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to MCP-Memory 2 | 3 | First off, thank you for considering contributing to MCP-Memory! 🎉 It's people like you that make MCP-Memory such a great tool. 4 | 5 | ## Table of Contents 6 | 7 | - [Code of Conduct](#code-of-conduct) 8 | - [Getting Started](#getting-started) 9 | - [How Can I Contribute?](#how-can-i-contribute) 10 | - [Reporting Bugs](#reporting-bugs) 11 | - [Suggesting Enhancements](#suggesting-enhancements) 12 | - [Your First Code Contribution](#your-first-code-contribution) 13 | - [Pull Requests](#pull-requests) 14 | - [Development Process](#development-process) 15 | - [Setting Up Your Environment](#setting-up-your-environment) 16 | - [Running Tests](#running-tests) 17 | - [Code Style](#code-style) 18 | - [Commit Messages](#commit-messages) 19 | - [Community](#community) 20 | 21 | ## Code of Conduct 22 | 23 | This project and everyone participating in it is governed by the [MCP-Memory Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [security@mcp-memory.io](mailto:security@mcp-memory.io). 24 | 25 | ## Getting Started 26 | 27 | MCP-Memory is a Go-based implementation of the Model Context Protocol (MCP) with advanced memory capabilities. Before you begin: 28 | 29 | 1. Make sure you have Go 1.21+ installed 30 | 2. Fork and clone the repository 31 | 3. Install dependencies: `go mod download` 32 | 4. Run tests to ensure everything works: `make test` 33 | 34 | ## How Can I Contribute? 35 | 36 | ### Reporting Bugs 37 | 38 | Before creating bug reports, please check [existing issues](https://github.com/LerianStudio/lerian-mcp-memory/issues) as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible: 39 | 40 | **Bug Report Template:** 41 | ```markdown 42 | **Describe the bug** 43 | A clear and concise description of what the bug is. 44 | 45 | **To Reproduce** 46 | Steps to reproduce the behavior: 47 | 1. Go to '...' 48 | 2. Run command '....' 49 | 3. See error 50 | 51 | **Expected behavior** 52 | What you expected to happen. 53 | 54 | **Environment:** 55 | - OS: [e.g. macOS 14.0] 56 | - Go version: [e.g. 1.21.5] 57 | - MCP-Memory version: [e.g. 0.1.0] 58 | 59 | **Additional context** 60 | Add any other context about the problem here. 61 | ``` 62 | 63 | ### Suggesting Enhancements 64 | 65 | Enhancement suggestions are tracked as [GitHub issues](https://github.com/LerianStudio/lerian-mcp-memory/issues). Create an issue and provide: 66 | 67 | - **Use a clear and descriptive title** 68 | - **Provide a step-by-step description** of the suggested enhancement 69 | - **Provide specific examples** to demonstrate the steps 70 | - **Describe the current behavior** and **explain which behavior you expected to see instead** 71 | - **Explain why this enhancement would be useful** 72 | 73 | ### Your First Code Contribution 74 | 75 | Unsure where to begin? You can start by looking through these issues: 76 | 77 | - [Beginner issues](https://github.com/LerianStudio/lerian-mcp-memory/labels/good%20first%20issue) - issues which should only require a few lines of code 78 | - [Help wanted issues](https://github.com/LerianStudio/lerian-mcp-memory/labels/help%20wanted) - issues which should be a bit more involved 79 | 80 | ### Pull Requests 81 | 82 | 1. Fork the repo and create your branch from `main`. 83 | 2. If you've added code that should be tested, add tests. 84 | 3. If you've changed APIs, update the documentation. 85 | 4. Ensure the test suite passes. 86 | 5. Make sure your code follows the existing style. 87 | 6. Issue that pull request! 88 | 89 | ## Development Process 90 | 91 | ### Setting Up Your Environment 92 | 93 | ```bash 94 | # Clone your fork 95 | git clone https://github.com/YOUR_USERNAME/lerian-mcp-memory.git 96 | cd lerian-mcp-memory 97 | 98 | # Add upstream remote 99 | git remote add upstream https://github.com/LerianStudio/lerian-mcp-memory.git 100 | 101 | # Install dependencies 102 | go mod download 103 | 104 | # Install development tools 105 | make dev-tools 106 | 107 | # Set up pre-commit hooks 108 | make setup-hooks 109 | ``` 110 | 111 | ### Running Tests 112 | 113 | ```bash 114 | # Run all tests 115 | make test 116 | 117 | # Run tests with coverage 118 | make test-coverage 119 | 120 | # Run specific package tests 121 | go test ./internal/storage/... 122 | 123 | # Run tests with race detection 124 | go test -race ./... 125 | 126 | # Run integration tests 127 | make test-integration 128 | ``` 129 | 130 | ### Code Style 131 | 132 | We follow the standard Go coding conventions: 133 | 134 | - Run `gofmt` on your code 135 | - Follow [Effective Go](https://golang.org/doc/effective_go.html) 136 | - Use `golangci-lint` for additional checks: `make lint` 137 | - Write meaningful variable and function names 138 | - Keep functions focused and small 139 | - Document exported functions and types 140 | 141 | **Example:** 142 | ```go 143 | // StoreChunk stores a conversation chunk in memory with automatic analysis 144 | // and embedding generation. It returns the stored chunk ID or an error. 145 | func (s *Server) StoreChunk(ctx context.Context, content string, sessionID string) (string, error) { 146 | // Implementation 147 | } 148 | ``` 149 | 150 | ### Commit Messages 151 | 152 | We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: 153 | 154 | ``` 155 | (): 156 | 157 | 158 | 159 |