This is page 1 of 47. Use http://codebase.md/doobidoo/mcp-memory-service?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .claude
│ ├── agents
│ │ ├── amp-bridge.md
│ │ ├── amp-pr-automator.md
│ │ ├── code-quality-guard.md
│ │ ├── gemini-pr-automator.md
│ │ └── github-release-manager.md
│ ├── settings.local.json.backup
│ └── settings.local.json.local
├── .commit-message
├── .dockerignore
├── .env.example
├── .env.sqlite.backup
├── .envnn#
├── .gitattributes
├── .github
│ ├── FUNDING.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.yml
│ │ ├── config.yml
│ │ ├── feature_request.yml
│ │ └── performance_issue.yml
│ ├── pull_request_template.md
│ └── workflows
│ ├── bridge-tests.yml
│ ├── CACHE_FIX.md
│ ├── claude-code-review.yml
│ ├── claude.yml
│ ├── cleanup-images.yml.disabled
│ ├── dev-setup-validation.yml
│ ├── docker-publish.yml
│ ├── LATEST_FIXES.md
│ ├── main-optimized.yml.disabled
│ ├── main.yml
│ ├── publish-and-test.yml
│ ├── README_OPTIMIZATION.md
│ ├── release-tag.yml.disabled
│ ├── release.yml
│ ├── roadmap-review-reminder.yml
│ ├── SECRET_CONDITIONAL_FIX.md
│ └── WORKFLOW_FIXES.md
├── .gitignore
├── .mcp.json.backup
├── .mcp.json.template
├── .pyscn
│ ├── .gitignore
│ └── reports
│ └── analyze_20251123_214224.html
├── AGENTS.md
├── archive
│ ├── deployment
│ │ ├── deploy_fastmcp_fixed.sh
│ │ ├── deploy_http_with_mcp.sh
│ │ └── deploy_mcp_v4.sh
│ ├── deployment-configs
│ │ ├── empty_config.yml
│ │ └── smithery.yaml
│ ├── development
│ │ └── test_fastmcp.py
│ ├── docs-removed-2025-08-23
│ │ ├── authentication.md
│ │ ├── claude_integration.md
│ │ ├── claude-code-compatibility.md
│ │ ├── claude-code-integration.md
│ │ ├── claude-code-quickstart.md
│ │ ├── claude-desktop-setup.md
│ │ ├── complete-setup-guide.md
│ │ ├── database-synchronization.md
│ │ ├── development
│ │ │ ├── autonomous-memory-consolidation.md
│ │ │ ├── CLEANUP_PLAN.md
│ │ │ ├── CLEANUP_README.md
│ │ │ ├── CLEANUP_SUMMARY.md
│ │ │ ├── dream-inspired-memory-consolidation.md
│ │ │ ├── hybrid-slm-memory-consolidation.md
│ │ │ ├── mcp-milestone.md
│ │ │ ├── multi-client-architecture.md
│ │ │ ├── test-results.md
│ │ │ └── TIMESTAMP_FIX_SUMMARY.md
│ │ ├── distributed-sync.md
│ │ ├── invocation_guide.md
│ │ ├── macos-intel.md
│ │ ├── master-guide.md
│ │ ├── mcp-client-configuration.md
│ │ ├── multi-client-server.md
│ │ ├── service-installation.md
│ │ ├── sessions
│ │ │ └── MCP_ENHANCEMENT_SESSION_MEMORY_v4.1.0.md
│ │ ├── UBUNTU_SETUP.md
│ │ ├── ubuntu.md
│ │ ├── windows-setup.md
│ │ └── windows.md
│ ├── docs-root-cleanup-2025-08-23
│ │ ├── AWESOME_LIST_SUBMISSION.md
│ │ ├── CLOUDFLARE_IMPLEMENTATION.md
│ │ ├── DOCUMENTATION_ANALYSIS.md
│ │ ├── DOCUMENTATION_CLEANUP_PLAN.md
│ │ ├── DOCUMENTATION_CONSOLIDATION_COMPLETE.md
│ │ ├── LITESTREAM_SETUP_GUIDE.md
│ │ ├── lm_studio_system_prompt.md
│ │ ├── PYTORCH_DOWNLOAD_FIX.md
│ │ └── README-ORIGINAL-BACKUP.md
│ ├── investigations
│ │ └── MACOS_HOOKS_INVESTIGATION.md
│ ├── litestream-configs-v6.3.0
│ │ ├── install_service.sh
│ │ ├── litestream_master_config_fixed.yml
│ │ ├── litestream_master_config.yml
│ │ ├── litestream_replica_config_fixed.yml
│ │ ├── litestream_replica_config.yml
│ │ ├── litestream_replica_simple.yml
│ │ ├── litestream-http.service
│ │ ├── litestream.service
│ │ └── requirements-cloudflare.txt
│ ├── release-notes
│ │ └── release-notes-v7.1.4.md
│ └── setup-development
│ ├── README.md
│ ├── setup_consolidation_mdns.sh
│ ├── STARTUP_SETUP_GUIDE.md
│ └── test_service.sh
├── CHANGELOG-HISTORIC.md
├── CHANGELOG.md
├── claude_commands
│ ├── memory-context.md
│ ├── memory-health.md
│ ├── memory-ingest-dir.md
│ ├── memory-ingest.md
│ ├── memory-recall.md
│ ├── memory-search.md
│ ├── memory-store.md
│ ├── README.md
│ └── session-start.md
├── claude-hooks
│ ├── config.json
│ ├── config.template.json
│ ├── CONFIGURATION.md
│ ├── core
│ │ ├── memory-retrieval.js
│ │ ├── mid-conversation.js
│ │ ├── session-end.js
│ │ ├── session-start.js
│ │ └── topic-change.js
│ ├── debug-pattern-test.js
│ ├── install_claude_hooks_windows.ps1
│ ├── install_hooks.py
│ ├── memory-mode-controller.js
│ ├── MIGRATION.md
│ ├── README-NATURAL-TRIGGERS.md
│ ├── README-phase2.md
│ ├── README.md
│ ├── simple-test.js
│ ├── statusline.sh
│ ├── test-adaptive-weights.js
│ ├── test-dual-protocol-hook.js
│ ├── test-mcp-hook.js
│ ├── test-natural-triggers.js
│ ├── test-recency-scoring.js
│ ├── tests
│ │ ├── integration-test.js
│ │ ├── phase2-integration-test.js
│ │ ├── test-code-execution.js
│ │ ├── test-cross-session.json
│ │ ├── test-session-tracking.json
│ │ └── test-threading.json
│ ├── utilities
│ │ ├── adaptive-pattern-detector.js
│ │ ├── context-formatter.js
│ │ ├── context-shift-detector.js
│ │ ├── conversation-analyzer.js
│ │ ├── dynamic-context-updater.js
│ │ ├── git-analyzer.js
│ │ ├── mcp-client.js
│ │ ├── memory-client.js
│ │ ├── memory-scorer.js
│ │ ├── performance-manager.js
│ │ ├── project-detector.js
│ │ ├── session-tracker.js
│ │ ├── tiered-conversation-monitor.js
│ │ └── version-checker.js
│ └── WINDOWS-SESSIONSTART-BUG.md
├── CLAUDE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── Development-Sprint-November-2025.md
├── docs
│ ├── amp-cli-bridge.md
│ ├── api
│ │ ├── code-execution-interface.md
│ │ ├── memory-metadata-api.md
│ │ ├── PHASE1_IMPLEMENTATION_SUMMARY.md
│ │ ├── PHASE2_IMPLEMENTATION_SUMMARY.md
│ │ ├── PHASE2_REPORT.md
│ │ └── tag-standardization.md
│ ├── architecture
│ │ ├── search-enhancement-spec.md
│ │ └── search-examples.md
│ ├── architecture.md
│ ├── archive
│ │ └── obsolete-workflows
│ │ ├── load_memory_context.md
│ │ └── README.md
│ ├── assets
│ │ └── images
│ │ ├── dashboard-v3.3.0-preview.png
│ │ ├── memory-awareness-hooks-example.png
│ │ ├── project-infographic.svg
│ │ └── README.md
│ ├── CLAUDE_CODE_QUICK_REFERENCE.md
│ ├── cloudflare-setup.md
│ ├── deployment
│ │ ├── docker.md
│ │ ├── dual-service.md
│ │ ├── production-guide.md
│ │ └── systemd-service.md
│ ├── development
│ │ ├── ai-agent-instructions.md
│ │ ├── code-quality
│ │ │ ├── phase-2a-completion.md
│ │ │ ├── phase-2a-handle-get-prompt.md
│ │ │ ├── phase-2a-index.md
│ │ │ ├── phase-2a-install-package.md
│ │ │ └── phase-2b-session-summary.md
│ │ ├── code-quality-workflow.md
│ │ ├── dashboard-workflow.md
│ │ ├── issue-management.md
│ │ ├── pr-review-guide.md
│ │ ├── refactoring-notes.md
│ │ ├── release-checklist.md
│ │ └── todo-tracker.md
│ ├── docker-optimized-build.md
│ ├── document-ingestion.md
│ ├── DOCUMENTATION_AUDIT.md
│ ├── enhancement-roadmap-issue-14.md
│ ├── examples
│ │ ├── analysis-scripts.js
│ │ ├── maintenance-session-example.md
│ │ ├── memory-distribution-chart.jsx
│ │ └── tag-schema.json
│ ├── first-time-setup.md
│ ├── glama-deployment.md
│ ├── guides
│ │ ├── advanced-command-examples.md
│ │ ├── chromadb-migration.md
│ │ ├── commands-vs-mcp-server.md
│ │ ├── mcp-enhancements.md
│ │ ├── mdns-service-discovery.md
│ │ ├── memory-consolidation-guide.md
│ │ ├── migration.md
│ │ ├── scripts.md
│ │ └── STORAGE_BACKENDS.md
│ ├── HOOK_IMPROVEMENTS.md
│ ├── hooks
│ │ └── phase2-code-execution-migration.md
│ ├── http-server-management.md
│ ├── ide-compatability.md
│ ├── IMAGE_RETENTION_POLICY.md
│ ├── images
│ │ └── dashboard-placeholder.md
│ ├── implementation
│ │ ├── health_checks.md
│ │ └── performance.md
│ ├── IMPLEMENTATION_PLAN_HTTP_SSE.md
│ ├── integration
│ │ ├── homebrew.md
│ │ └── multi-client.md
│ ├── integrations
│ │ ├── gemini.md
│ │ ├── groq-bridge.md
│ │ ├── groq-integration-summary.md
│ │ └── groq-model-comparison.md
│ ├── integrations.md
│ ├── legacy
│ │ └── dual-protocol-hooks.md
│ ├── LM_STUDIO_COMPATIBILITY.md
│ ├── maintenance
│ │ └── memory-maintenance.md
│ ├── mastery
│ │ ├── api-reference.md
│ │ ├── architecture-overview.md
│ │ ├── configuration-guide.md
│ │ ├── local-setup-and-run.md
│ │ ├── testing-guide.md
│ │ └── troubleshooting.md
│ ├── migration
│ │ └── code-execution-api-quick-start.md
│ ├── natural-memory-triggers
│ │ ├── cli-reference.md
│ │ ├── installation-guide.md
│ │ └── performance-optimization.md
│ ├── oauth-setup.md
│ ├── pr-graphql-integration.md
│ ├── quick-setup-cloudflare-dual-environment.md
│ ├── README.md
│ ├── remote-configuration-wiki-section.md
│ ├── research
│ │ ├── code-execution-interface-implementation.md
│ │ └── code-execution-interface-summary.md
│ ├── ROADMAP.md
│ ├── sqlite-vec-backend.md
│ ├── statistics
│ │ ├── charts
│ │ │ ├── activity_patterns.png
│ │ │ ├── contributors.png
│ │ │ ├── growth_trajectory.png
│ │ │ ├── monthly_activity.png
│ │ │ └── october_sprint.png
│ │ ├── data
│ │ │ ├── activity_by_day.csv
│ │ │ ├── activity_by_hour.csv
│ │ │ ├── contributors.csv
│ │ │ └── monthly_activity.csv
│ │ ├── generate_charts.py
│ │ └── REPOSITORY_STATISTICS.md
│ ├── technical
│ │ ├── development.md
│ │ ├── memory-migration.md
│ │ ├── migration-log.md
│ │ ├── sqlite-vec-embedding-fixes.md
│ │ └── tag-storage.md
│ ├── testing
│ │ └── regression-tests.md
│ ├── testing-cloudflare-backend.md
│ ├── troubleshooting
│ │ ├── cloudflare-api-token-setup.md
│ │ ├── cloudflare-authentication.md
│ │ ├── general.md
│ │ ├── hooks-quick-reference.md
│ │ ├── pr162-schema-caching-issue.md
│ │ ├── session-end-hooks.md
│ │ └── sync-issues.md
│ └── tutorials
│ ├── advanced-techniques.md
│ ├── data-analysis.md
│ └── demo-session-walkthrough.md
├── examples
│ ├── claude_desktop_config_template.json
│ ├── claude_desktop_config_windows.json
│ ├── claude-desktop-http-config.json
│ ├── config
│ │ └── claude_desktop_config.json
│ ├── http-mcp-bridge.js
│ ├── memory_export_template.json
│ ├── README.md
│ ├── setup
│ │ └── setup_multi_client_complete.py
│ └── start_https_example.sh
├── install_service.py
├── install.py
├── LICENSE
├── NOTICE
├── pyproject.toml
├── pytest.ini
├── README.md
├── run_server.py
├── scripts
│ ├── .claude
│ │ └── settings.local.json
│ ├── archive
│ │ └── check_missing_timestamps.py
│ ├── backup
│ │ ├── backup_memories.py
│ │ ├── backup_sqlite_vec.sh
│ │ ├── export_distributable_memories.sh
│ │ └── restore_memories.py
│ ├── benchmarks
│ │ ├── benchmark_code_execution_api.py
│ │ ├── benchmark_hybrid_sync.py
│ │ └── benchmark_server_caching.py
│ ├── database
│ │ ├── analyze_sqlite_vec_db.py
│ │ ├── check_sqlite_vec_status.py
│ │ ├── db_health_check.py
│ │ └── simple_timestamp_check.py
│ ├── development
│ │ ├── debug_server_initialization.py
│ │ ├── find_orphaned_files.py
│ │ ├── fix_mdns.sh
│ │ ├── fix_sitecustomize.py
│ │ ├── remote_ingest.sh
│ │ ├── setup-git-merge-drivers.sh
│ │ ├── uv-lock-merge.sh
│ │ └── verify_hybrid_sync.py
│ ├── hooks
│ │ └── pre-commit
│ ├── installation
│ │ ├── install_linux_service.py
│ │ ├── install_macos_service.py
│ │ ├── install_uv.py
│ │ ├── install_windows_service.py
│ │ ├── install.py
│ │ ├── setup_backup_cron.sh
│ │ ├── setup_claude_mcp.sh
│ │ └── setup_cloudflare_resources.py
│ ├── linux
│ │ ├── service_status.sh
│ │ ├── start_service.sh
│ │ ├── stop_service.sh
│ │ ├── uninstall_service.sh
│ │ └── view_logs.sh
│ ├── maintenance
│ │ ├── assign_memory_types.py
│ │ ├── check_memory_types.py
│ │ ├── cleanup_corrupted_encoding.py
│ │ ├── cleanup_memories.py
│ │ ├── cleanup_organize.py
│ │ ├── consolidate_memory_types.py
│ │ ├── consolidation_mappings.json
│ │ ├── delete_orphaned_vectors_fixed.py
│ │ ├── fast_cleanup_duplicates_with_tracking.sh
│ │ ├── find_all_duplicates.py
│ │ ├── find_cloudflare_duplicates.py
│ │ ├── find_duplicates.py
│ │ ├── memory-types.md
│ │ ├── README.md
│ │ ├── recover_timestamps_from_cloudflare.py
│ │ ├── regenerate_embeddings.py
│ │ ├── repair_malformed_tags.py
│ │ ├── repair_memories.py
│ │ ├── repair_sqlite_vec_embeddings.py
│ │ ├── repair_zero_embeddings.py
│ │ ├── restore_from_json_export.py
│ │ └── scan_todos.sh
│ ├── migration
│ │ ├── cleanup_mcp_timestamps.py
│ │ ├── legacy
│ │ │ └── migrate_chroma_to_sqlite.py
│ │ ├── mcp-migration.py
│ │ ├── migrate_sqlite_vec_embeddings.py
│ │ ├── migrate_storage.py
│ │ ├── migrate_tags.py
│ │ ├── migrate_timestamps.py
│ │ ├── migrate_to_cloudflare.py
│ │ ├── migrate_to_sqlite_vec.py
│ │ ├── migrate_v5_enhanced.py
│ │ ├── TIMESTAMP_CLEANUP_README.md
│ │ └── verify_mcp_timestamps.py
│ ├── pr
│ │ ├── amp_collect_results.sh
│ │ ├── amp_detect_breaking_changes.sh
│ │ ├── amp_generate_tests.sh
│ │ ├── amp_pr_review.sh
│ │ ├── amp_quality_gate.sh
│ │ ├── amp_suggest_fixes.sh
│ │ ├── auto_review.sh
│ │ ├── detect_breaking_changes.sh
│ │ ├── generate_tests.sh
│ │ ├── lib
│ │ │ └── graphql_helpers.sh
│ │ ├── quality_gate.sh
│ │ ├── resolve_threads.sh
│ │ ├── run_pyscn_analysis.sh
│ │ ├── run_quality_checks.sh
│ │ ├── thread_status.sh
│ │ └── watch_reviews.sh
│ ├── quality
│ │ ├── fix_dead_code_install.sh
│ │ ├── phase1_dead_code_analysis.md
│ │ ├── phase2_complexity_analysis.md
│ │ ├── README_PHASE1.md
│ │ ├── README_PHASE2.md
│ │ ├── track_pyscn_metrics.sh
│ │ └── weekly_quality_review.sh
│ ├── README.md
│ ├── run
│ │ ├── run_mcp_memory.sh
│ │ ├── run-with-uv.sh
│ │ └── start_sqlite_vec.sh
│ ├── run_memory_server.py
│ ├── server
│ │ ├── check_http_server.py
│ │ ├── check_server_health.py
│ │ ├── memory_offline.py
│ │ ├── preload_models.py
│ │ ├── run_http_server.py
│ │ ├── run_memory_server.py
│ │ ├── start_http_server.bat
│ │ └── start_http_server.sh
│ ├── service
│ │ ├── deploy_dual_services.sh
│ │ ├── install_http_service.sh
│ │ ├── mcp-memory-http.service
│ │ ├── mcp-memory.service
│ │ ├── memory_service_manager.sh
│ │ ├── service_control.sh
│ │ ├── service_utils.py
│ │ └── update_service.sh
│ ├── sync
│ │ ├── check_drift.py
│ │ ├── claude_sync_commands.py
│ │ ├── export_memories.py
│ │ ├── import_memories.py
│ │ ├── litestream
│ │ │ ├── apply_local_changes.sh
│ │ │ ├── enhanced_memory_store.sh
│ │ │ ├── init_staging_db.sh
│ │ │ ├── io.litestream.replication.plist
│ │ │ ├── manual_sync.sh
│ │ │ ├── memory_sync.sh
│ │ │ ├── pull_remote_changes.sh
│ │ │ ├── push_to_remote.sh
│ │ │ ├── README.md
│ │ │ ├── resolve_conflicts.sh
│ │ │ ├── setup_local_litestream.sh
│ │ │ ├── setup_remote_litestream.sh
│ │ │ ├── staging_db_init.sql
│ │ │ ├── stash_local_changes.sh
│ │ │ ├── sync_from_remote_noconfig.sh
│ │ │ └── sync_from_remote.sh
│ │ ├── README.md
│ │ ├── safe_cloudflare_update.sh
│ │ ├── sync_memory_backends.py
│ │ └── sync_now.py
│ ├── testing
│ │ ├── run_complete_test.py
│ │ ├── run_memory_test.sh
│ │ ├── simple_test.py
│ │ ├── test_cleanup_logic.py
│ │ ├── test_cloudflare_backend.py
│ │ ├── test_docker_functionality.py
│ │ ├── test_installation.py
│ │ ├── test_mdns.py
│ │ ├── test_memory_api.py
│ │ ├── test_memory_simple.py
│ │ ├── test_migration.py
│ │ ├── test_search_api.py
│ │ ├── test_sqlite_vec_embeddings.py
│ │ ├── test_sse_events.py
│ │ ├── test-connection.py
│ │ └── test-hook.js
│ ├── utils
│ │ ├── claude_commands_utils.py
│ │ ├── generate_personalized_claude_md.sh
│ │ ├── groq
│ │ ├── groq_agent_bridge.py
│ │ ├── list-collections.py
│ │ ├── memory_wrapper_uv.py
│ │ ├── query_memories.py
│ │ ├── smithery_wrapper.py
│ │ ├── test_groq_bridge.sh
│ │ └── uv_wrapper.py
│ └── validation
│ ├── check_dev_setup.py
│ ├── check_documentation_links.py
│ ├── diagnose_backend_config.py
│ ├── validate_configuration_complete.py
│ ├── validate_memories.py
│ ├── validate_migration.py
│ ├── validate_timestamp_integrity.py
│ ├── verify_environment.py
│ ├── verify_pytorch_windows.py
│ └── verify_torch.py
├── SECURITY.md
├── selective_timestamp_recovery.py
├── SPONSORS.md
├── src
│ └── mcp_memory_service
│ ├── __init__.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── client.py
│ │ ├── operations.py
│ │ ├── sync_wrapper.py
│ │ └── types.py
│ ├── backup
│ │ ├── __init__.py
│ │ └── scheduler.py
│ ├── cli
│ │ ├── __init__.py
│ │ ├── ingestion.py
│ │ ├── main.py
│ │ └── utils.py
│ ├── config.py
│ ├── consolidation
│ │ ├── __init__.py
│ │ ├── associations.py
│ │ ├── base.py
│ │ ├── clustering.py
│ │ ├── compression.py
│ │ ├── consolidator.py
│ │ ├── decay.py
│ │ ├── forgetting.py
│ │ ├── health.py
│ │ └── scheduler.py
│ ├── dependency_check.py
│ ├── discovery
│ │ ├── __init__.py
│ │ ├── client.py
│ │ └── mdns_service.py
│ ├── embeddings
│ │ ├── __init__.py
│ │ └── onnx_embeddings.py
│ ├── ingestion
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── chunker.py
│ │ ├── csv_loader.py
│ │ ├── json_loader.py
│ │ ├── pdf_loader.py
│ │ ├── registry.py
│ │ ├── semtools_loader.py
│ │ └── text_loader.py
│ ├── lm_studio_compat.py
│ ├── mcp_server.py
│ ├── models
│ │ ├── __init__.py
│ │ └── memory.py
│ ├── server.py
│ ├── services
│ │ ├── __init__.py
│ │ └── memory_service.py
│ ├── storage
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── cloudflare.py
│ │ ├── factory.py
│ │ ├── http_client.py
│ │ ├── hybrid.py
│ │ └── sqlite_vec.py
│ ├── sync
│ │ ├── __init__.py
│ │ ├── exporter.py
│ │ ├── importer.py
│ │ └── litestream_config.py
│ ├── utils
│ │ ├── __init__.py
│ │ ├── cache_manager.py
│ │ ├── content_splitter.py
│ │ ├── db_utils.py
│ │ ├── debug.py
│ │ ├── document_processing.py
│ │ ├── gpu_detection.py
│ │ ├── hashing.py
│ │ ├── http_server_manager.py
│ │ ├── port_detection.py
│ │ ├── system_detection.py
│ │ └── time_parser.py
│ └── web
│ ├── __init__.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── analytics.py
│ │ ├── backup.py
│ │ ├── consolidation.py
│ │ ├── documents.py
│ │ ├── events.py
│ │ ├── health.py
│ │ ├── manage.py
│ │ ├── mcp.py
│ │ ├── memories.py
│ │ ├── search.py
│ │ └── sync.py
│ ├── app.py
│ ├── dependencies.py
│ ├── oauth
│ │ ├── __init__.py
│ │ ├── authorization.py
│ │ ├── discovery.py
│ │ ├── middleware.py
│ │ ├── models.py
│ │ ├── registration.py
│ │ └── storage.py
│ ├── sse.py
│ └── static
│ ├── app.js
│ ├── index.html
│ ├── README.md
│ ├── sse_test.html
│ └── style.css
├── start_http_debug.bat
├── start_http_server.sh
├── test_document.txt
├── test_version_checker.js
├── tests
│ ├── __init__.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── test_compact_types.py
│ │ └── test_operations.py
│ ├── bridge
│ │ ├── mock_responses.js
│ │ ├── package-lock.json
│ │ ├── package.json
│ │ └── test_http_mcp_bridge.js
│ ├── conftest.py
│ ├── consolidation
│ │ ├── __init__.py
│ │ ├── conftest.py
│ │ ├── test_associations.py
│ │ ├── test_clustering.py
│ │ ├── test_compression.py
│ │ ├── test_consolidator.py
│ │ ├── test_decay.py
│ │ └── test_forgetting.py
│ ├── contracts
│ │ └── api-specification.yml
│ ├── integration
│ │ ├── package-lock.json
│ │ ├── package.json
│ │ ├── test_api_key_fallback.py
│ │ ├── test_api_memories_chronological.py
│ │ ├── test_api_tag_time_search.py
│ │ ├── test_api_with_memory_service.py
│ │ ├── test_bridge_integration.js
│ │ ├── test_cli_interfaces.py
│ │ ├── test_cloudflare_connection.py
│ │ ├── test_concurrent_clients.py
│ │ ├── test_data_serialization_consistency.py
│ │ ├── test_http_server_startup.py
│ │ ├── test_mcp_memory.py
│ │ ├── test_mdns_integration.py
│ │ ├── test_oauth_basic_auth.py
│ │ ├── test_oauth_flow.py
│ │ ├── test_server_handlers.py
│ │ └── test_store_memory.py
│ ├── performance
│ │ ├── test_background_sync.py
│ │ └── test_hybrid_live.py
│ ├── README.md
│ ├── smithery
│ │ └── test_smithery.py
│ ├── sqlite
│ │ └── simple_sqlite_vec_test.py
│ ├── test_client.py
│ ├── test_content_splitting.py
│ ├── test_database.py
│ ├── test_hybrid_cloudflare_limits.py
│ ├── test_hybrid_storage.py
│ ├── test_memory_ops.py
│ ├── test_semantic_search.py
│ ├── test_sqlite_vec_storage.py
│ ├── test_time_parser.py
│ ├── test_timestamp_preservation.py
│ ├── timestamp
│ │ ├── test_hook_vs_manual_storage.py
│ │ ├── test_issue99_final_validation.py
│ │ ├── test_search_retrieval_inconsistency.py
│ │ ├── test_timestamp_issue.py
│ │ └── test_timestamp_simple.py
│ └── unit
│ ├── conftest.py
│ ├── test_cloudflare_storage.py
│ ├── test_csv_loader.py
│ ├── test_fastapi_dependencies.py
│ ├── test_import.py
│ ├── test_json_loader.py
│ ├── test_mdns_simple.py
│ ├── test_mdns.py
│ ├── test_memory_service.py
│ ├── test_memory.py
│ ├── test_semtools_loader.py
│ ├── test_storage_interface_compatibility.py
│ └── test_tag_time_filtering.py
├── tools
│ ├── docker
│ │ ├── DEPRECATED.md
│ │ ├── docker-compose.http.yml
│ │ ├── docker-compose.pythonpath.yml
│ │ ├── docker-compose.standalone.yml
│ │ ├── docker-compose.uv.yml
│ │ ├── docker-compose.yml
│ │ ├── docker-entrypoint-persistent.sh
│ │ ├── docker-entrypoint-unified.sh
│ │ ├── docker-entrypoint.sh
│ │ ├── Dockerfile
│ │ ├── Dockerfile.glama
│ │ ├── Dockerfile.slim
│ │ ├── README.md
│ │ └── test-docker-modes.sh
│ └── README.md
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.envnn#:
--------------------------------------------------------------------------------
```
1 |
```
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
```
1 | # Auto-resolve lock file conflicts and regenerate lock file
2 | uv.lock merge=uv-lock-merge
```
--------------------------------------------------------------------------------
/.env.sqlite.backup:
--------------------------------------------------------------------------------
```
1 | # SQLite-vec Configuration for MCP Memory Service (Backup)
2 | MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
3 | MCP_MEMORY_SQLITE_PATH=/home/hkr/.local/share/mcp-memory/primary_sqlite_vec.db
4 |
```
--------------------------------------------------------------------------------
/.pyscn/.gitignore:
--------------------------------------------------------------------------------
```
1 | # pyscn generated files
2 |
3 | # Analysis reports (HTML, JSON)
4 | reports/
5 |
6 | # Historical metrics tracking
7 | history/
8 |
9 | # Temporary analysis files
10 | *.tmp
11 | *.log
12 |
13 | # Keep directory structure
14 | !.gitignore
15 |
```
--------------------------------------------------------------------------------
/.mcp.json.template:
--------------------------------------------------------------------------------
```
1 | {
2 | "mcpServers": {
3 | "memory-service": {
4 | "type": "stdio",
5 | "command": "python",
6 | "args": ["scripts/run_memory_server.py"],
7 | "env": {
8 | "MCP_MEMORY_CHROMA_PATH": "{{USER_HOME}}/.mcp_memory_chroma",
9 | "LOG_LEVEL": "INFO",
10 | "MCP_TIMEOUT": "30000"
11 | }
12 | }
13 | }
14 | }
```
--------------------------------------------------------------------------------
/.mcp.json.backup:
--------------------------------------------------------------------------------
```
1 | {
2 | "mcpServers": {
3 | "memory-service": {
4 | "type": "stdio",
5 | "command": "python",
6 | "args": [
7 | "scripts/run_memory_server.py"
8 | ],
9 | "env": {
10 | "MCP_MEMORY_CHROMA_PATH": "/home/hkr/.mcp_memory_chroma",
11 | "LOG_LEVEL": "INFO",
12 | "MCP_TIMEOUT": "30000"
13 | }
14 | },
15 | "memory": {
16 | "command": "uv",
17 | "args": [
18 | "--directory",
19 | "/home/hkr/repositories/mcp-memory-service",
20 | "run",
21 | "memory"
22 | ],
23 | "env": {
24 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
25 | "MCP_MEMORY_SQLITE_PRAGMAS": "busy_timeout=15000,cache_size=20000",
26 | "LOG_LEVEL": "INFO"
27 | }
28 | }
29 | }
30 | }
```
--------------------------------------------------------------------------------
/.dockerignore:
--------------------------------------------------------------------------------
```
1 | # Virtual Environments
2 | .venv/
3 | venv/
4 | py310_venv/
5 | venv_py310/
6 | env/
7 | .env
8 | .Python
9 |
10 | # Python Cache Files
11 | __pycache__/
12 | *.py[cod]
13 | *$py.class
14 | *.so
15 | .pytest_cache/
16 | .tox/
17 | .coverage
18 | coverage.*
19 | .cache/
20 | .hypothesis/
21 |
22 | # Git Repository
23 | .git/
24 | .gitignore
25 |
26 | # Build Artifacts
27 | build/
28 | develop-eggs/
29 | dist/
30 | downloads/
31 | eggs/
32 | .eggs/
33 | lib/
34 | lib64/
35 | parts/
36 | sdist/
37 | var/
38 | wheels/
39 | *.egg-info/
40 | .installed.cfg
41 | *.egg
42 | __pypackages__/
43 |
44 | # Development Files
45 | *.log
46 | *.bak
47 | *.tmp
48 | *.old
49 | *.swp
50 | *.swo
51 | test_output.txt
52 | dxdiag_output.txt
53 | dxdiag.txt
54 | development_notes.md
55 | migration_*.log
56 | deploy_test*.sh
57 |
58 | # IDE and Editor Files
59 | .vscode/
60 | .idea/
61 | .codegpt/
62 |
63 | # OS Specific Files
64 | .DS_Store
65 | .AppleDouble
66 | .LSOverride
67 | Thumbs.db
68 | Desktop.ini
69 |
70 | # Database and Storage Directories
71 | chroma_db/
72 | .mcp_memory_chroma/
73 | .mcp_memory_sqlite/
74 | *.sqlite
75 | *.sqlite-*
76 | *.sqlite3
77 | backups/
78 |
79 | # Configuration Files (may contain sensitive data)
80 | claude_desktop_config_updated.json
81 | claude_config/
82 | .claude/
83 | .mcp.json
84 | CLAUDE_MEMORY.md
85 | *_reference_memories_*.json
86 |
87 | # Test Artifacts
88 | tests/test_db/
89 | /tmp/test_mcp*.py
90 | test_mcp*.py
91 | debug_mcp*.py
92 | *_test.py.old
93 | test_*.py.backup
94 | *.cover
95 | nosetests.xml
96 | coverage.xml
97 |
98 | # Temporary and Personal Files
99 | YOUR_PERSONALIZED_SETUP_GUIDE.md
100 | CLAUDE_PERSONALIZED.md
101 | *_old
102 | *_backup
103 |
104 | # Aider and AI Tools
105 | .aider.*
106 |
107 | # Documentation Build Artifacts
108 | docs/_build/
109 | docs/site/
110 |
111 | # Archive Directories
112 | archive/
```
--------------------------------------------------------------------------------
/.commit-message:
--------------------------------------------------------------------------------
```
1 | fix: address Gemini code review feedback (PR #209)
2 |
3 | CRITICAL FIXES:
4 | 1. Fix async/await issue in operations.py health() function
5 | - Changed get_storage() to await get_storage_async()
6 | - Ensures proper async execution throughout call stack
7 |
8 | 2. Fix hardcoded macOS path in client.py
9 | - Replaced ~/Library/Application Support with cross-platform get_base_directory()
10 | - Works on macOS, Linux, and Windows
11 |
12 | DOCUMENTATION IMPROVEMENTS:
13 | 3. Replace Unicode multiplication symbols (x) with ASCII (x)
14 | - Fixed 6 documentation files for better compatibility
15 | - Prevents encoding issues in terminals and editors
16 |
17 | 4. Replace absolute local paths with relative repo paths
18 | - Removed /Users/hkr/Documents/GitHub/mcp-memory-service/
19 | - Now uses relative paths (src/, docs/)
20 |
21 | RESOURCE MANAGEMENT:
22 | 5. Add explicit close() and close_async() methods
23 | - Proper resource cleanup for storage backends
24 | - Sync and async versions for different contexts
25 | - Exported in public API
26 |
27 | NEW FEATURES:
28 | 6. Write 5-minute migration guide
29 | - Located at docs/migration/code-execution-api-quick-start.md
30 | - Covers fresh install and upgrade paths
31 | - Includes troubleshooting and ROI calculator
32 |
33 | 7. Enable code execution by default in installer
34 | - Auto-detects Python path (python3 for Unix, python for Windows)
35 | - Adds codeExecution config to hooks
36 | - Updates both generate_basic_config() and generate_hooks_config_from_mcp()
37 | - Success messaging shows 75-90% token reduction benefits
38 |
39 | TESTING:
40 | - API tests pass (23/42 passing, 19 failures are pre-existing database duplicates)
41 | - Manual validation confirms health() works correctly
42 | - Cross-platform path handling verified
43 |
44 | FILES CHANGED:
45 | - src/mcp_memory_service/api/operations.py (async fix)
46 | - src/mcp_memory_service/api/client.py (paths + close methods)
47 | - src/mcp_memory_service/api/__init__.py (export close functions)
48 | - claude-hooks/install_hooks.py (code execution config)
49 | - claude-hooks/config.json (add codeExecution section)
50 | - docs/migration/code-execution-api-quick-start.md (NEW)
51 | - docs/api/* (Unicode + path fixes)
52 | - docs/research/* (Unicode + path fixes)
53 |
54 | Ready for PR #209 merge.
55 |
56 | Generated with Claude Code
57 |
58 | Co-Authored-By: Claude <[email protected]>
59 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 |
2 | # Aider files
3 | .aider.*
4 |
5 | # Private/sensitive documents
6 | docs/saas-monetization-strategy.md
7 |
8 | # Local memory exports (contain sensitive data)
9 | local_export*.json
10 |
11 | # Python
12 | __pycache__/
13 | *.py[cod]
14 | *$py.class
15 | *.so
16 |
17 | # Python environment & build artifacts
18 | .Python
19 | env/
20 | .venv/
21 | venv/
22 | py310_venv/
23 | venv_py310/
24 | .uv/
25 | build/
26 | develop-eggs/
27 | dist/
28 | downloads/
29 | eggs/
30 | .eggs/
31 | lib/
32 | lib64/
33 | !scripts/pr/lib/
34 | parts/
35 | sdist/
36 | var/
37 | wheels/
38 | *.egg-info/
39 | .installed.cfg
40 | *.egg
41 |
42 | # Python project tools
43 | pip-wheel-metadata/
44 | __pypackages__/
45 |
46 | # Virtual Environment activation files (redundant due to .venv/ but explicit if needed)
47 | .env
48 | .env.local
49 | .env.development
50 | .env.test
51 | .env.production
52 | # But include template files
53 | !.env.example
54 |
55 | # IDEs & Editors
56 | .idea/
57 | .vscode/
58 | *.swp
59 | *.swo
60 |
61 | # OS-specific files
62 | .DS_Store
63 | .AppleDouble
64 | .LSOverride
65 |
66 | # CodeGPT / Extensions
67 | .codegpt/
68 |
69 | # ChromaDB artifacts
70 | chroma_db/
71 | tests/test_db/chroma.sqlite3
72 |
73 | # SQLite-vec artifacts
74 | *.sqlite
75 | *.sqlite-*
76 | .mcp_memory_sqlite/
77 | .mcp_memory_chroma/
78 |
79 | # pyscn analysis artifacts (reports and history tracked in .pyscn/.gitignore)
80 | .pyscn/reports/
81 | .pyscn/history/
82 |
83 | # Project-specific artifacts
84 | backups/
85 | test_output.txt
86 | dxdiag_output.txt
87 | dxdiag.txt
88 | claude_desktop_config_updated.json
89 | claude_config/claude_desktop_config.json
90 |
91 | # Remove these if mistakenly included
92 | =1.0.0,
93 | =11.0.3
94 | =*.*.*
95 | **vX.Y.Z**
96 | **vX.Y.Z**:
97 | timestamp
98 | updated_at
99 |
100 | # Logs and debugging
101 | *.log
102 | *.bak
103 | *.tmp
104 | *.old
105 |
106 | # Test and development artifacts
107 | test_*.py.backup
108 | *_test.py.old
109 | development_notes.md
110 |
111 | # Temporary MCP test files
112 | /tmp/test_mcp*.py
113 | test_mcp*.py
114 | debug_mcp*.py
115 |
116 | # Migration artifacts
117 | migration_*.log
118 | deploy_test*.sh
119 |
120 | # Optional: VSCode debugging & Python caches
121 | *.coverage
122 | coverage.*
123 | .cache/
124 | .pytest_cache/
125 | .tox/
126 | nosetests.xml
127 | coverage.xml
128 | *.cover
129 | .hypothesis/
130 | claude_config/claude_desktop_config.json
131 | .claude/mcp_config.json
132 |
133 | # Personalized setup guides (generated locally)
134 | YOUR_PERSONALIZED_SETUP_GUIDE.md
135 | .mcp.json
136 |
137 | # Local memory service configuration (contains private endpoints/keys)
138 | CLAUDE_MEMORY.md
139 | *_reference_memories_*.json
140 |
141 | # Claude Code local settings (personal configurations)
142 | .claude/settings.local.json*
143 | scripts/.claude/settings.local.json*
144 |
145 | # Amp CLI Bridge (entire directory - user-specific working space)
146 | .claude/amp/
147 |
148 | # Personal files
149 | CLAUDE_PERSONALIZED.md
150 | CLAUDE.local.md
151 | SESSION_MEMORY_2025-08-11.md
152 |
153 | # Context crystallizer artifacts
154 | .context-crystallizer/
155 |
156 | # Git tools
157 | .git-rewrite/
158 |
159 | # Node.js dependencies and artifacts
160 | node_modules/
161 | npm-debug.log*
162 | yarn-debug.log*
163 | yarn-error.log*
164 | package-lock.json
165 | .npm
166 | .mcp.json.disabled
167 | data/
168 |
169 | # GitHub wiki clone (managed separately)
170 | .wiki/
171 |
172 | # Keep directory structure but ignore content
173 | !.claude/amp/prompts/pending/.gitkeep
174 | !.claude/amp/responses/ready/.gitkeep
175 | !.claude/amp/responses/consumed/.gitkeep
176 | .local/
177 |
178 | # Social media posts
179 | social-media/
180 |
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
1 | # Cloudflare Configuration for MCP Memory Service
2 | # ================================================
3 | # Copy this file to .env and replace with your actual credentials
4 | #
5 | # Setup Instructions:
6 | # 1. Copy this file: cp .env.example .env
7 | # 2. Create Cloudflare API Token at: https://dash.cloudflare.com/profile/api-tokens
8 | # 3. Replace placeholder values below with your actual credentials
9 | # 4. Never commit your .env file to git (it's already in .gitignore)
10 |
11 | # =============================================================================
12 | # REQUIRED: Cloudflare API Token
13 | # =============================================================================
14 | # Create at: https://dash.cloudflare.com/profile/api-tokens
15 | # Required permissions:
16 | # - Account: Cloudflare Workers:Edit
17 | # - Zone Resources: Include All zones
18 | # - Account Resources: Include All accounts
19 | #
20 | # IMPORTANT: Test your token with the account-scoped endpoint:
21 | # curl "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/tokens/verify" \
22 | # -H "Authorization: Bearer {YOUR_TOKEN}"
23 | #
24 | # DO NOT use the generic endpoint (will fail for scoped tokens):
25 | # curl "https://api.cloudflare.com/client/v4/user/tokens/verify" ❌
26 | CLOUDFLARE_API_TOKEN=your-cloudflare-api-token-here
27 |
28 | # =============================================================================
29 | # REQUIRED: Cloudflare Account ID
30 | # =============================================================================
31 | # Find in: Cloudflare Dashboard > Right sidebar under "Account ID"
32 | # Example: be0e35a26715043ef8df90253268c33f
33 | CLOUDFLARE_ACCOUNT_ID=your-account-id-here
34 |
35 | # =============================================================================
36 | # REQUIRED: D1 Database ID
37 | # =============================================================================
38 | # Create with: wrangler d1 create mcp-memory-database
39 | # Or find existing: wrangler d1 list
40 | # Example: f745e9b4-ba8e-4d47-b38f-12af91060d5a
41 | CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id-here
42 |
43 | # =============================================================================
44 | # REQUIRED: Vectorize Index Name
45 | # =============================================================================
46 | # Create with: wrangler vectorize create mcp-memory-index --dimensions=384
47 | # Or find existing: wrangler vectorize list
48 | # Example: mcp-memory-index
49 | CLOUDFLARE_VECTORIZE_INDEX=your-vectorize-index-name
50 |
51 | # =============================================================================
52 | # OPTIONAL: R2 Bucket for Large Content Storage
53 | # =============================================================================
54 | # Create with: wrangler r2 bucket create mcp-memory-content
55 | # Only needed if you plan to store large content (>1MB)
56 | # CLOUDFLARE_R2_BUCKET=mcp-memory-content
57 |
58 | # =============================================================================
59 | # STORAGE BACKEND CONFIGURATION
60 | # =============================================================================
61 | # Options: sqlite_vec | cloudflare | hybrid
62 | # - sqlite_vec: Fast local storage (development)
63 | # - cloudflare: Cloud storage with Cloudflare (production)
64 | # - hybrid: Best of both - local speed + cloud persistence (recommended)
65 | MCP_MEMORY_STORAGE_BACKEND=cloudflare
66 |
67 | # =============================================================================
68 | # OPTIONAL: Advanced Configuration
69 | # =============================================================================
70 |
71 | # Cloudflare embedding model (default is recommended)
72 | # CLOUDFLARE_EMBEDDING_MODEL=@cf/baai/bge-base-en-v1.5
73 |
74 | # Large content threshold for R2 storage (bytes)
75 | # CLOUDFLARE_LARGE_CONTENT_THRESHOLD=1048576
76 |
77 | # HTTP Interface (Web Dashboard)
78 | # MCP_HTTP_ENABLED=true
79 | # MCP_HTTP_PORT=8888
80 | # MCP_HTTPS_ENABLED=true
81 | # MCP_HTTPS_PORT=8443
82 |
83 | # OAuth 2.1 Authentication (for web interface)
84 | # MCP_OAUTH_ENABLED=false
85 |
86 | # Hybrid Backend Configuration (if using hybrid)
87 | # MCP_HYBRID_SYNC_INTERVAL=300 # Sync every 5 minutes
88 | # MCP_HYBRID_BATCH_SIZE=50 # Sync 50 operations at a time
89 | # MCP_HYBRID_SYNC_ON_STARTUP=true # Initial sync on startup
90 |
91 | # =============================================================================
92 | # TROUBLESHOOTING
93 | # =============================================================================
94 | # Common issues:
95 | # 1. "Invalid API Token" - Check token permissions and expiry
96 | # 2. "Database not found" - Verify D1 database ID is correct
97 | # 3. "Vectorize index not found" - Check index name and dimensions (384)
98 | # 4. "Account access denied" - Ensure API token has account permissions
99 | #
100 | # Documentation: https://github.com/doobidoo/mcp-memory-service/wiki
101 | # Support: https://github.com/doobidoo/mcp-memory-service/issues
```
--------------------------------------------------------------------------------
/tests/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP-MEMORY-SERVICE Tests
2 |
3 | This directory contains tests for the MCP-MEMORY-SERVICE project.
4 |
5 | ## Directory Structure
6 |
7 | - `integration/` - Integration tests between components
8 | - `unit/` - Unit tests for individual components
9 | - `performance/` - Performance benchmarks
10 |
11 | ## Running Tests
12 |
13 | ```bash
14 | # Run all tests
15 | pytest
16 |
17 | # Run specific test category
18 | pytest tests/unit/
19 | pytest tests/integration/
20 | pytest tests/performance/
21 | ```
22 |
```
--------------------------------------------------------------------------------
/archive/setup-development/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Development Files Archive
2 |
3 | This directory contains files used during the development and setup process:
4 |
5 | ## 📁 Archived Files
6 |
7 | - **`setup_consolidation_mdns.sh`** - Original manual startup script (superseded by systemd service)
8 | - **`test_service.sh`** - Debug script for troubleshooting service startup issues
9 | - **`STARTUP_SETUP_GUIDE.md`** - Original startup guide (superseded by COMPLETE_SETUP_GUIDE.md)
10 |
11 | ## 🔄 Superseded By
12 |
13 | These files were used during development but are now superseded by:
14 |
15 | - **Production Service**: `mcp-memory.service` + `service_control.sh`
16 | - **Complete Documentation**: `COMPLETE_SETUP_GUIDE.md`
17 | - **Quick Start**: `README_PRODUCTION.md`
18 |
19 | ## 🗂️ Purpose
20 |
21 | These files are kept for:
22 | - Historical reference
23 | - Debugging if needed
24 | - Understanding the development process
25 | - Potential future troubleshooting
26 |
27 | **Note**: Use the production files in the root directory for normal operation.
```
--------------------------------------------------------------------------------
/tools/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Development Tools and Utilities
2 |
3 | This directory contains development tools, build utilities, and deployment configurations for MCP Memory Service.
4 |
5 | ## Directory Structure
6 |
7 | ### `/build/` - Build Tools
8 | - `setup.py` - Python package build configuration
9 | - Build scripts and packaging utilities
10 |
11 | ### `/deployments/` - Deployment Tools
12 | - `cloudflare/` - Cloudflare Workers deployment configuration
13 | - Cloud platform deployment scripts and configurations
14 |
15 | ### `/docker/` - Docker Tools
16 | - Multiple Docker configurations and Dockerfiles
17 | - Docker Compose files for different deployment scenarios
18 | - Docker utility scripts and entrypoints
19 |
20 | ## Usage
21 |
22 | ### Build Tools
23 | ```bash
24 | # Build Python package
25 | cd tools/build
26 | python setup.py sdist bdist_wheel
27 | ```
28 |
29 | ### Docker Deployment
30 | ```bash
31 | # Use various Docker configurations
32 | cd tools/docker
33 | docker-compose -f docker-compose.yml up
34 | docker-compose -f docker-compose.standalone.yml up
35 | ```
36 |
37 | ### Cloudflare Workers
38 | ```bash
39 | # Deploy to Cloudflare Workers
40 | cd tools/deployments/cloudflare
41 | npm install
42 | wrangler deploy
43 | ```
44 |
45 | ## Related Documentation
46 |
47 | - [Docker Deployment Guide](../docs/deployment/docker.md) - Comprehensive Docker setup
48 | - [Installation Guide](../docs/installation/master-guide.md) - General installation
49 | - [Development Guide](../docs/technical/development.md) - Development setup
```
--------------------------------------------------------------------------------
/docs/assets/images/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Screenshots
2 |
3 | This directory contains screenshots and visual assets for the MCP Memory Service documentation.
4 |
5 | ## Dashboard Screenshots
6 |
7 | ### v3.3.0 Dashboard Features
8 |
9 | The modern dashboard includes:
10 |
11 | 
12 |
13 | **Key Features:**
14 | - **Modern Design**: Gradient backgrounds with professional card layout
15 | - **Live Statistics**: Real-time server metrics including:
16 | - Total memories count
17 | - Embedding model information
18 | - Server health status
19 | - Response time metrics
20 | - **Interactive Endpoints**: Organized API documentation with hover effects
21 | - **Tech Stack Badges**: Visual representation of FastAPI, SQLite-vec, PyTorch, etc.
22 | - **Responsive Layout**: Works on desktop and mobile devices
23 | - **Auto-Refresh**: Stats update every 30 seconds
24 |
25 | ## Access URLs
26 |
27 | - **Dashboard**: http://localhost:8000
28 | - **mDNS**: http://mcp-memory-service.local:8000
29 | - **API Docs**: http://localhost:8000/api/docs
30 | - **ReDoc**: http://localhost:8000/api/redoc
31 |
32 | ## Screenshot Instructions
33 |
34 | To capture the dashboard for documentation:
35 |
36 | 1. Ensure the HTTP server is running: `python scripts/run_http_server.py`
37 | 2. Wait for stats to load (shows actual memory count)
38 | 3. Take full-page screenshot at 1920x1080 resolution
39 | 4. Save as `dashboard-v3.3.0.png` in this directory
40 | 5. Update README.md references accordingly
41 |
42 | ## File Naming Convention
43 |
44 | - `dashboard-v{version}.png` - Main dashboard screenshots
45 | - `api-docs-v{version}.png` - API documentation screenshots
46 | - `mobile-v{version}.png` - Mobile responsive views
47 | - `feature-{name}-v{version}.png` - Specific feature screenshots
```
--------------------------------------------------------------------------------
/tools/docker/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Docker Setup for MCP Memory Service
2 |
3 | ## 🚀 Quick Start
4 |
5 | Choose your mode:
6 |
7 | ### MCP Protocol Mode (for Claude Desktop, VS Code)
8 | ```bash
9 | docker-compose up -d
10 | ```
11 |
12 | ### HTTP API Mode (for REST API, Web Dashboard)
13 | ```bash
14 | docker-compose -f docker-compose.http.yml up -d
15 | ```
16 |
17 | ## 📝 What's New (v5.0.4)
18 |
19 | Thanks to feedback from Joe Esposito, we've completely simplified the Docker setup:
20 |
21 | ### ✅ Fixed Issues
22 | - **PYTHONPATH** now correctly set to `/app/src`
23 | - **run_server.py** properly copied for HTTP mode
24 | - **Embedding models** pre-downloaded during build (no runtime failures)
25 |
26 | ### 🎯 Simplified Structure
27 | - **2 clear modes** instead of 4 confusing variants
28 | - **Unified entrypoint** that auto-detects mode
29 | - **Single Dockerfile** for all configurations
30 |
31 | ## 🔧 Configuration
32 |
33 | ### Environment Variables
34 |
35 | | Variable | Description | Default |
36 | |----------|-------------|---------|
37 | | `MCP_MODE` | Operation mode: `mcp` or `http` | `mcp` |
38 | | `MCP_API_KEY` | API key for HTTP mode | `your-secure-api-key-here` |
39 | | `HTTP_PORT` | Host port for HTTP mode | `8000` |
40 | | `LOG_LEVEL` | Logging level | `INFO` |
41 |
42 | ### Volume Mounts
43 |
44 | All data is stored in a single `./data` directory:
45 | - SQLite database: `./data/sqlite_vec.db`
46 | - Backups: `./data/backups/`
47 |
48 | ## 🧪 Testing
49 |
50 | Run the test script to verify both modes work:
51 | ```bash
52 | ./test-docker-modes.sh
53 | ```
54 |
55 | ## 📊 HTTP Mode Endpoints
56 |
57 | When running in HTTP mode:
58 | - **Dashboard**: http://localhost:8000/
59 | - **API Docs**: http://localhost:8000/api/docs
60 | - **Health Check**: http://localhost:8000/api/health
61 |
62 | ## 🔄 Migration from Old Setup
63 |
64 | If you were using the old Docker files:
65 |
66 | | Old File | New Alternative |
67 | |----------|-----------------|
68 | | `docker-compose.standalone.yml` | Use `docker-compose.http.yml` |
69 | | `docker-compose.uv.yml` | UV is now built-in |
70 | | `docker-compose.pythonpath.yml` | Fixed in main Dockerfile |
71 |
72 | See [DEPRECATED.md](./DEPRECATED.md) for details.
73 |
74 | ## 🐛 Troubleshooting
75 |
76 | ### Container exits immediately
77 | - For HTTP mode: Check logs with `docker-compose -f docker-compose.http.yml logs`
78 | - Ensure `MCP_MODE=http` is set in environment
79 |
80 | ### Cannot connect to HTTP endpoints
81 | - Verify container is running: `docker ps`
82 | - Check port mapping: `docker port <container_name>`
83 | - Test health: `curl http://localhost:8000/api/health`
84 |
85 | ### Embedding model errors
86 | - Models are pre-downloaded during build
87 | - If issues persist, rebuild: `docker-compose build --no-cache`
88 |
89 | ## 🙏 Credits
90 |
91 | Special thanks to **Joe Esposito** for identifying and helping fix the Docker setup issues!
```
--------------------------------------------------------------------------------
/examples/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Examples
2 |
3 | This directory contains example configurations, scripts, and setup utilities for deploying MCP Memory Service in various scenarios.
4 |
5 | ## Directory Structure
6 |
7 | ### `/config/` - Configuration Examples
8 | - Example Claude Desktop configurations
9 | - Template configuration files for different deployment scenarios
10 | - MCP server configuration samples
11 |
12 | ### `/setup/` - Setup Scripts and Utilities
13 | - Multi-client setup scripts
14 | - Automated configuration tools
15 | - Installation helpers
16 |
17 | ## Core Files
18 |
19 | ### `http-mcp-bridge.js`
20 | A Node.js script that bridges MCP JSON-RPC protocol to HTTP REST API calls. This allows MCP clients like Claude Desktop to connect to a remote HTTP server instead of running a local instance.
21 |
22 | **Usage:**
23 | 1. Configure your server endpoint and API key as environment variables
24 | 2. Use this script as the MCP server command in your client configuration
25 |
26 | ### `claude-desktop-http-config.json`
27 | Example Claude Desktop configuration for connecting to a remote MCP Memory Service HTTP server via the bridge script.
28 |
29 | **Setup:**
30 | 1. Update the path to `http-mcp-bridge.js`
31 | 2. Set your server endpoint URL
32 | 3. Add your API key (if authentication is enabled)
33 | 4. Copy this configuration to your Claude Desktop config file
34 |
35 | ### `codex-mcp-config.json`
36 | Example Codex configuration using `mcp-proxy` to bridge stdio to the service’s Streamable HTTP endpoint at `/mcp`.
37 |
38 | **Setup:**
39 | 1. Install the proxy: `pipx install mcp-proxy` (or `uv tool install mcp-proxy`)
40 | 2. Set server API key on the server: `export MCP_API_KEY=...`
41 | 3. Copy this file and adjust `your-server` and API key
42 | 4. Place it in Codex’s MCP config location (see Codex docs)
43 |
44 | Why proxy? Codex does not support HTTP transports natively and requires a stdio bridge.
45 |
46 | ## Quick Start
47 |
48 | ### 1. Server Setup
49 | ```bash
50 | # On your server machine
51 | cd mcp-memory-service
52 | python install.py --server-mode --storage-backend sqlite_vec
53 | export MCP_HTTP_HOST=0.0.0.0
54 | export MCP_API_KEY="your-secure-key"
55 | python scripts/run_http_server.py
56 | ```
57 |
58 | ### 2. Client Configuration
59 | ```bash
60 | # Update the bridge script path and server details
61 | cp examples/claude-desktop-http-config.json ~/.config/claude-desktop/
62 | ```
63 |
64 | ### 3. Test Connection
65 | ```bash
66 | # Test the HTTP API directly
67 | curl -H "Authorization: Bearer your-secure-key" \
68 | http://your-server:8000/api/health
69 | ```
70 |
71 | ## Advanced Usage
72 |
73 | - See the [Multi-Client Setup Guide](../docs/integration/multi-client.md) for Codex, Cursor, Qwen, and Gemini recipes.
74 | - For Cursor/Qwen/Gemini direct HTTP usage, prefer the Streamable HTTP endpoint: `http(s)://<host>:8000/mcp` with header `Authorization: Bearer <MCP_API_KEY>`.
75 |
```
--------------------------------------------------------------------------------
/docs/archive/obsolete-workflows/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Obsolete Workflows Archive
2 |
3 | This directory contains historical documentation of workflows that have been superseded by better, automated solutions.
4 |
5 | ## Contents
6 |
7 | ### `load_memory_context.md` (August 2025)
8 |
9 | **Original Purpose**: Manual prompt with curl commands to load memory context at Claude Code session start.
10 |
11 | **Why Obsolete**: Completely superseded by Natural Memory Triggers v7.1.3+ (September 2025).
12 |
13 | #### Evolution Timeline
14 |
15 | **Phase 1: Manual Loading (Aug 2025)** ❌ OBSOLETE
16 | ```bash
17 | # Users had to manually run curl commands and paste output
18 | curl -k -s -X POST https://server:8443/mcp \
19 | -H "Authorization: Bearer token" \
20 | -d '{"method": "tools/call", "params": {...}}'
21 | ```
22 | **Problems**: Manual, error-prone, required copy-paste, network configuration complexity
23 |
24 | **Phase 2: SessionStart Hooks (Aug-Sept 2025)** ✅ IMPROVED
25 | - Automatic memory retrieval at session start
26 | - Project detection and intelligent scoring
27 | - Git-aware context integration
28 |
29 | **Phase 3: Natural Memory Triggers (Sept 2025+)** ✅ PRODUCTION
30 | - 85%+ trigger accuracy with semantic pattern detection
31 | - Multi-tier performance optimization (50ms → 500ms tiers)
32 | - CLI management system for real-time configuration
33 | - Adaptive learning based on usage patterns
34 |
35 | **Phase 4: Team Collaboration (v7.0.0+)** ✅ NETWORK DISTRIBUTION
36 | - OAuth 2.1 Dynamic Client Registration
37 | - Claude Code HTTP transport
38 | - Zero-configuration team collaboration
39 | - Better than manual network sharing
40 |
41 | #### Current Solution
42 |
43 | Instead of manual prompts, users now get:
44 |
45 | ```bash
46 | # One-time installation
47 | cd claude-hooks && python install_hooks.py --natural-triggers
48 |
49 | # That's it! Automatic context injection from now on
50 | ```
51 |
52 | **Benefits**:
53 | - ✅ Zero manual steps per session
54 | - ✅ 85%+ trigger accuracy
55 | - ✅ Intelligent pattern detection
56 | - ✅ Multi-tier performance
57 | - ✅ Team collaboration via OAuth
58 |
59 | #### Historical Value
60 |
61 | This archive demonstrates:
62 | 1. **UX Evolution**: Manual → Semi-automatic → Fully automatic
63 | 2. **Problem Recognition**: Identifying pain points (manual commands)
64 | 3. **Iterative Improvement**: Each phase solved previous limitations
65 | 4. **User-Centric Design**: Continuously reducing friction
66 |
67 | #### Migration
68 |
69 | If you're still using manual prompts:
70 |
71 | **Old Approach** (manual):
72 | ```bash
73 | curl -k -s -X POST https://server:8443/mcp ... | jq -r '.result.content[0].text'
74 | ```
75 |
76 | **New Approach** (automatic):
77 | ```bash
78 | # Install once
79 | python claude-hooks/install_hooks.py --natural-triggers
80 |
81 | # Enjoy automatic context injection forever
82 | ```
83 |
84 | See: [Natural Memory Triggers Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)
85 |
86 | ---
87 |
88 | **Last Updated**: October 25, 2025
89 | **Status**: Archived for historical reference only
90 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/web/static/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Interactive Dashboard
2 |
3 | This directory contains the static assets for the interactive memory management dashboard.
4 |
5 | ## Files Overview
6 |
7 | - **`index.html`** - Main dashboard interface with complete UI structure
8 | - **`app.js`** - Frontend JavaScript application with API integration and real-time updates
9 | - **`style.css`** - Comprehensive CSS with responsive design and component styling
10 | - **`sse_test.html`** - Server-Sent Events testing interface (existing)
11 |
12 | ## Features Implemented
13 |
14 | ### 🎯 Core Dashboard
15 | - **Welcome overview** with memory statistics and quick actions
16 | - **Recent memories** display with click-to-view details
17 | - **Quick stats** showing total memories, recent activity, and tag counts
18 | - **Responsive design** that works on mobile, tablet, and desktop
19 |
20 | ### 🔍 Search & Browse
21 | - **Semantic search** with real-time suggestions
22 | - **Advanced filters** by tags, date range, and content type
23 | - **Grid/list view** toggles for different viewing preferences
24 | - **Search results** with relevance scoring and highlighting
25 |
26 | ### 📝 Memory Management
27 | - **Add new memories** with modal interface and auto-tagging
28 | - **View memory details** with full content, metadata, and tags
29 | - **Edit/delete operations** with confirmation and undo capabilities
30 | - **Bulk operations** for efficient memory organization
31 |
32 | ### ⚡ Real-time Features
33 | - **Server-Sent Events** integration for live updates
34 | - **Connection status** monitoring with reconnection logic
35 | - **Toast notifications** for user feedback
36 | - **Live statistics** updates without page refresh
37 |
38 | ### 🎨 User Experience
39 | - **Progressive disclosure** - simple by default, powerful when needed
40 | - **Keyboard shortcuts** - Ctrl+K for search, Ctrl+M for add memory
41 | - **Loading states** and error handling throughout
42 | - **Accessibility** features with proper ARIA labels and focus management
43 |
44 | ## Testing the Dashboard
45 |
46 | ### 1. Start the Server
47 | ```bash
48 | # With HTTPS (recommended)
49 | export MCP_HTTPS_ENABLED=true
50 | export MCP_HTTPS_PORT=8443
51 | python run_server.py
52 | ```
53 |
54 | ### 2. Access the Dashboard
55 | - **HTTPS**: https://localhost:8443/
56 | - **HTTP**: http://localhost:8000/
57 |
58 | ### 3. Test Core Functionality
59 | 1. **Search**: Use semantic queries and apply filters
60 | 2. **Add Memory**: Click "Add Memory" and create test content
61 | 3. **View Details**: Click memory cards to see full details
62 | 4. **Real-time Updates**: Open in multiple tabs to test SSE
63 | 5. **Keyboard Shortcuts**: Try Ctrl+K (search) and Ctrl+M (add)
64 |
65 | ## Technical Implementation
66 |
67 | - **Vanilla JavaScript** - No build process required
68 | - **CSS Grid + Flexbox** - Modern responsive layouts
69 | - **Server-Sent Events** - Real-time backend communication
70 | - **Progressive Enhancement** - Works without JavaScript for basics
71 | - **API Integration** - Full REST API connectivity with error handling
```
--------------------------------------------------------------------------------
/scripts/sync/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Database Synchronization Scripts
2 |
3 | This directory contains scripts for synchronizing SQLite-vec databases across multiple machines using JSON export/import and Litestream replication.
4 |
5 | ## Overview
6 |
7 | The synchronization system enables you to:
8 | - Export memories from one machine to JSON format
9 | - Import memories from multiple JSON files into a central database
10 | - Set up real-time replication using Litestream
11 | - Maintain consistent memory databases across multiple devices
12 |
13 | ## Scripts
14 |
15 | ### export_memories.py
16 |
17 | Export memories from a local SQLite-vec database to JSON format.
18 |
19 | **Usage:**
20 | ```bash
21 | # Basic export
22 | python export_memories.py
23 |
24 | # Export from specific database
25 | python export_memories.py --db-path /path/to/sqlite_vec.db
26 |
27 | # Export to specific file
28 | python export_memories.py --output my_export.json
29 |
30 | # Export with embedding vectors (large file size)
31 | python export_memories.py --include-embeddings
32 |
33 | # Export only specific tags
34 | python export_memories.py --filter-tags claude-code,architecture
35 | ```
36 |
37 | **Features:**
38 | - Preserves original timestamps and metadata
39 | - Adds source machine tracking
40 | - Supports tag filtering
41 | - Optional embedding vector export
42 | - Cross-platform compatibility
43 |
44 | ### import_memories.py
45 |
46 | Import memories from JSON export files into a central database.
47 |
48 | **Usage:**
49 | ```bash
50 | # Import single file
51 | python import_memories.py windows_export.json
52 |
53 | # Import multiple files
54 | python import_memories.py windows_export.json macbook_export.json
55 |
56 | # Dry run analysis
57 | python import_memories.py --dry-run exports/*.json
58 |
59 | # Import to specific database
60 | python import_memories.py --db-path /path/to/central.db exports/*.json
61 | ```
62 |
63 | **Features:**
64 | - Intelligent deduplication based on content hash
65 | - Preserves original timestamps
66 | - Adds source tracking tags
67 | - Conflict detection and resolution
68 | - Comprehensive import statistics
69 |
70 | ## Typical Workflow
71 |
72 | ### Phase 1: Initial Consolidation
73 |
74 | 1. **Export from each machine:**
75 | ```bash
76 | # On Windows PC
77 | python export_memories.py --output windows_memories.json
78 |
79 | # On MacBook
80 | python export_memories.py --output macbook_memories.json
81 | ```
82 |
83 | 2. **Transfer files to central server:**
84 | ```bash
85 | scp windows_memories.json central-server:/tmp/
86 | scp macbook_memories.json central-server:/tmp/
87 | ```
88 |
89 | 3. **Import on central server:**
90 | ```bash
91 | # Analyze first
92 | python import_memories.py --dry-run /tmp/*.json
93 |
94 | # Import for real
95 | python import_memories.py /tmp/windows_memories.json /tmp/macbook_memories.json
96 | ```
97 |
98 | ### Phase 2: Set up Litestream
99 |
100 | After consolidating all memories into the central database, set up Litestream for ongoing synchronization.
101 |
102 | ## JSON Export Format
103 |
104 | The export format preserves all memory data:
105 |
106 | ```json
107 | {
108 | "export_metadata": {
109 | "source_machine": "machine-name",
110 | "export_timestamp": "2025-08-12T10:30:00Z",
111 | "total_memories": 450,
112 | "database_path": "/path/to/sqlite_vec.db",
113 | "platform": "Windows",
114 | "exporter_version": "5.0.0"
115 | },
116 | "memories": [
117 | {
118 | "content": "Memory content here",
119 | "content_hash": "sha256hash",
120 | "tags": ["tag1", "tag2"],
121 | "created_at": 1673545200.0,
122 | "updated_at": 1673545200.0,
123 | "memory_type": "note",
124 | "metadata": {},
125 | "export_source": "machine-name"
126 | }
127 | ]
128 | }
129 | ```
130 |
131 | ## Deduplication Strategy
132 |
133 | Memories are deduplicated based on content hash:
134 | - Same content hash = duplicate (skipped)
135 | - Different content hash = unique (imported)
136 | - Original timestamps are preserved
137 | - Source machine tags are added for tracking
138 |
139 | ## Error Handling
140 |
141 | Both scripts include comprehensive error handling:
142 | - JSON format validation
143 | - Database connectivity checks
144 | - File existence verification
145 | - Transaction rollback on failures
146 | - Detailed error logging
147 |
148 | ## Performance Considerations
149 |
150 | - **Export**: ~1000 memories/second
151 | - **Import**: ~500 memories/second with deduplication
152 | - **File Size**: ~1KB per memory (without embeddings)
153 | - **Memory Usage**: Processes files in streaming fashion
154 |
155 | ## Troubleshooting
156 |
157 | ### Common Issues
158 |
159 | 1. **Database not found:**
160 | ```bash
161 | # Check default location
162 | python -c "from mcp_memory_service.config import get_storage_path; print(get_storage_path())"
163 | ```
164 |
165 | 2. **Permission errors:**
166 | ```bash
167 | # Ensure database directory is writable
168 | chmod 755 ~/.local/share/mcp-memory/
169 | ```
170 |
171 | 3. **JSON format errors:**
172 | ```bash
173 | # Validate JSON file
174 | python -m json.tool export.json > /dev/null
175 | ```
176 |
177 | ### Logging
178 |
179 | Enable verbose logging for debugging:
180 | ```bash
181 | python export_memories.py --verbose
182 | python import_memories.py --verbose
183 | ```
184 |
185 | ## Next Steps
186 |
187 | After using these scripts for initial consolidation:
188 |
189 | 1. Set up Litestream for real-time sync
190 | 2. Configure replica nodes
191 | 3. Implement monitoring and alerting
192 | 4. Schedule regular backups
193 |
194 | See the main documentation for complete Litestream setup instructions.
```
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Documentation
2 |
3 | Welcome to the comprehensive documentation for MCP Memory Service - a Model Context Protocol server that provides semantic memory and persistent storage capabilities for Claude Desktop and other MCP clients.
4 |
5 | ## Quick Start
6 |
7 | - **New Users**: Start with the [Installation Guide](installation/master-guide.md)
8 | - **Multi-Client Setup**: See [Multi-Client Integration](integration/multi-client.md)
9 | - **Docker Users**: Check out [Docker Deployment](deployment/docker.md)
10 | - **Troubleshooting**: Visit [General Troubleshooting](troubleshooting/general.md)
11 |
12 | ## Documentation Structure
13 |
14 | ### 📦 Installation & Setup
15 |
16 | - **[Master Installation Guide](installation/master-guide.md)** - Comprehensive installation instructions for all platforms
17 | - **[Platform-Specific Guides](platforms/)** - Detailed setup for specific operating systems
18 | - [macOS Intel](platforms/macos-intel.md) - Intel Mac setup (including legacy 2013-2017 models)
19 | - [Windows](platforms/windows.md) - Windows installation with CUDA/DirectML support
20 | - [Ubuntu](platforms/ubuntu.md) - Ubuntu setup for desktop and server
21 |
22 | ### 🔗 Integration & Connectivity
23 |
24 | - **[Multi-Client Setup](integration/multi-client.md)** - Share memory across multiple applications
25 | - **[Homebrew Integration](integration/homebrew.md)** - Use system-installed PyTorch via Homebrew
26 | - **[Claude Desktop Integration](guides/claude_integration.md)** - Connect with Claude Desktop
27 | - **[IDE Compatibility](ide-compatability.md)** - VS Code, Continue, and other IDE integrations
28 |
29 | ### 🚀 Deployment
30 |
31 | - **[Docker Deployment](deployment/docker.md)** - Containerized deployment with various configurations
32 | - **[Server Deployment](deployment/multi-client-server.md)** - Production server setups
33 | - **[Cloud Deployment](glama-deployment.md)** - Cloud platform deployment guides
34 |
35 | ### 📚 User Guides
36 |
37 | - **[MCP Protocol Enhancements](guides/mcp-enhancements.md)** - Resources, Prompts, and Progress Tracking (v4.1.0)
38 | - **[Storage Backends](guides/STORAGE_BACKENDS.md)** - ChromaDB vs SQLite-vec comparison and configuration
39 | - **[Migration Guide](guides/migration.md)** - Migrate between storage backends and versions
40 | - **[Scripts Reference](guides/scripts.md)** - Available utility scripts
41 | - **[Invocation Guide](guides/invocation_guide.md)** - Different ways to run the service
42 |
43 | ### 🎯 Tutorials & Examples
44 |
45 | - **[Data Analysis Examples](tutorials/data-analysis.md)** - Advanced data analysis with memory service
46 | - **[Advanced Techniques](tutorials/advanced-techniques.md)** - Power user techniques and patterns
47 | - **[Demo Session Walkthrough](tutorials/demo-session-walkthrough.md)** - Step-by-step usage examples
48 |
49 | ### 🔧 Maintenance & Administration
50 |
51 | - **[Memory Maintenance](maintenance/memory-maintenance.md)** - Database cleanup, optimization, and backup
52 | - **[Health Checks](implementation/health_checks.md)** - Monitoring and diagnostics
53 | - **[Performance Tuning](implementation/performance.md)** - Optimization techniques
54 |
55 | ### 📖 API Reference
56 |
57 | - **[Memory Metadata API](api/memory-metadata-api.md)** - Advanced metadata operations
58 | - **[Tag Standardization](api/tag-standardization.md)** - Tag schema and conventions
59 | - **[HTTP/SSE API](IMPLEMENTATION_PLAN_HTTP_SSE.md)** - Web API documentation for multi-client setups
60 |
61 | ### 🛠️ Development & Technical
62 |
63 | - **[Development Guide](technical/development.md)** - Contributing and development setup
64 | - **[Architecture Overview](development/multi-client-architecture.md)** - System architecture and design patterns
65 | - **[Technical Implementation](technical/)** - Deep dive into technical details
66 | - [Memory Migration](technical/memory-migration.md)
67 | - [Tag Storage](technical/tag-storage.md)
68 |
69 | ### 🔍 Troubleshooting
70 |
71 | - **[General Troubleshooting](troubleshooting/general.md)** - Common issues and solutions
72 | - **[Docker Issues](deployment/docker.md#troubleshooting)** - Docker-specific troubleshooting
73 | - **[Platform-Specific Issues](platforms/)** - Platform-specific troubleshooting sections
74 |
75 | ## Project Information
76 |
77 | ### About MCP Memory Service
78 |
79 | MCP Memory Service enables persistent, semantic memory for AI applications through the Model Context Protocol. It provides:
80 |
81 | - **Semantic Search**: Vector-based memory retrieval using sentence transformers
82 | - **Multiple Storage Backends**: ChromaDB for full features, SQLite-vec for lightweight deployments
83 | - **Multi-Client Support**: Shared memory across multiple applications
84 | - **Cross-Platform**: Support for macOS, Windows, and Linux
85 | - **Flexible Deployment**: Local installation, Docker containers, or cloud deployment
86 |
87 | ### Key Features
88 |
89 | - ✅ **Semantic Memory Storage**: Store and retrieve memories using natural language
90 | - ✅ **Multi-Client Access**: Share memories across Claude Desktop, VS Code, and other MCP clients
91 | - ✅ **Flexible Storage**: Choose between ChromaDB (full-featured) or SQLite-vec (lightweight)
92 | - ✅ **Cross-Platform**: Native support for macOS (Intel & Apple Silicon), Windows, and Linux
93 | - ✅ **Docker Ready**: Complete containerization support with multiple deployment options
94 | - ✅ **Hardware Optimized**: Automatic detection and optimization for available hardware (CUDA, MPS, DirectML)
95 | - ✅ **Production Ready**: HTTP/SSE API, authentication, monitoring, and scaling features
96 |
97 | ### Recent Updates
98 |
99 | - **v0.2.2+**: Enhanced multi-client support with automatic MCP application detection
100 | - **SQLite-vec Backend**: Lightweight alternative to ChromaDB for resource-constrained systems
101 | - **Homebrew Integration**: Native support for Homebrew-installed PyTorch on macOS
102 | - **Docker Improvements**: Fixed boot loops, added multiple deployment configurations
103 | - **HTTP/SSE API**: Real-time multi-client communication with Server-Sent Events
104 |
105 | ## Getting Help
106 |
107 | ### Quick Links
108 |
109 | - **Installation Issues**: Check the [Installation Guide](installation/master-guide.md) and platform-specific guides
110 | - **Configuration Problems**: See [Troubleshooting](troubleshooting/general.md)
111 | - **Multi-Client Setup**: Follow the [Multi-Client Guide](integration/multi-client.md)
112 | - **Performance Issues**: Review [Performance Tuning](implementation/performance.md)
113 |
114 | ### Support Resources
115 |
116 | - **GitHub Issues**: Report bugs and request features
117 | - **Documentation**: Comprehensive guides for all use cases
118 | - **Community**: Share experiences and get help from other users
119 |
120 | ### Contributing
121 |
122 | We welcome contributions! See the [Development Guide](technical/development.md) for information on:
123 |
124 | - Setting up a development environment
125 | - Running tests
126 | - Submitting pull requests
127 | - Code style and conventions
128 |
129 | ## Version History
130 |
131 | - **Latest**: Enhanced documentation organization, consolidated guides, improved navigation
132 | - **v0.2.2**: Multi-client improvements, SQLite-vec backend, Homebrew integration
133 | - **v0.2.1**: Docker deployment fixes, HTTP/SSE API enhancements
134 | - **v0.2.0**: Multi-client support, cross-platform compatibility improvements
135 |
136 | ---
137 |
138 | ## Navigation Tips
139 |
140 | - **📁 Folders**: Click on folder names to explore sections
141 | - **🔗 Links**: All internal links are relative and work offline
142 | - **📱 Mobile**: Documentation is mobile-friendly for on-the-go reference
143 | - **🔍 Search**: Use your browser's search (Ctrl/Cmd+F) to find specific topics
144 |
145 | **Happy memory-ing! 🧠✨**
```
--------------------------------------------------------------------------------
/claude_commands/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Commands for MCP Memory Service
2 |
3 | This directory contains conversational Claude Code commands that integrate memory functionality into your Claude Code workflow. These commands follow the CCPlugins pattern of markdown-based conversational instructions.
4 |
5 | ## Available Commands
6 |
7 | ### `/session-start` - Manual Session Initialization
8 | Display session memory context manually by running the session-start hook. **Windows Workaround**: Required for Windows users due to SessionStart hook bug (#160). Works on all platforms.
9 |
10 | **Usage:**
11 | ```bash
12 | claude /session-start
13 | ```
14 |
15 | **Why this exists:**
16 | - Windows users cannot use automatic SessionStart hooks (causes Claude Code to hang)
17 | - Provides same functionality as automatic session-start hook
18 | - Safe manual alternative that works on all platforms (Windows, macOS, Linux)
19 |
20 | **What it does:**
21 | - Loads relevant project memories at session start
22 | - Analyzes git history and recent changes
23 | - Displays categorized memory context (recent work, current problems, additional context)
24 |
25 | ### `/memory-store` - Store Current Context
26 | Store information in your MCP Memory Service with proper context and tagging. Automatically detects project context, applies relevant tags, and includes machine hostname for source tracking.
27 |
28 | **Usage:**
29 | ```bash
30 | claude /memory-store "Important architectural decision about database backend"
31 | claude /memory-store --tags "decision,architecture" "We chose SQLite-vec for performance"
32 | ```
33 |
34 | ### `/memory-recall` - Time-based Memory Retrieval
35 | Retrieve memories using natural language time expressions. Perfect for finding past conversations and decisions.
36 |
37 | **Usage:**
38 | ```bash
39 | claude /memory-recall "what did we decide about the database last week?"
40 | claude /memory-recall "yesterday's architectural discussions"
41 | ```
42 |
43 | ### `/memory-search` - Tag and Content Search
44 | Search through stored memories using tags, content keywords, and semantic similarity.
45 |
46 | **Usage:**
47 | ```bash
48 | claude /memory-search --tags "architecture,database"
49 | claude /memory-search "SQLite performance optimization"
50 | ```
51 |
52 | ### `/memory-context` - Session Context Integration
53 | Capture the current conversation and project context as a memory for future reference. Automatically includes machine source identification for multi-device workflows.
54 |
55 | **Usage:**
56 | ```bash
57 | claude /memory-context
58 | claude /memory-context --summary "Architecture planning session"
59 | ```
60 |
61 | ### `/memory-health` - Service Health Check
62 | Check the health and status of your MCP Memory Service, providing diagnostics and statistics.
63 |
64 | **Usage:**
65 | ```bash
66 | claude /memory-health
67 | claude /memory-health --detailed
68 | ```
69 |
70 | ## Installation
71 |
72 | ### Automatic Installation (Recommended)
73 |
74 | The commands can be installed automatically during the main MCP Memory Service installation:
75 |
76 | ```bash
77 | # Install with commands (will prompt if Claude Code CLI is detected)
78 | python install.py
79 |
80 | # Force install commands
81 | python install.py --install-claude-commands
82 |
83 | # Skip command installation prompt
84 | python install.py --skip-claude-commands-prompt
85 | ```
86 |
87 | ### Manual Installation
88 |
89 | You can also install the commands manually:
90 |
91 | ```bash
92 | # Install commands directly
93 | python scripts/claude_commands_utils.py
94 |
95 | # Test installation prerequisites
96 | python scripts/claude_commands_utils.py --test
97 |
98 | # Uninstall commands
99 | python scripts/claude_commands_utils.py --uninstall
100 | ```
101 |
102 | ## Requirements
103 |
104 | - **Claude Code CLI**: Must be installed and available in PATH
105 | - **MCP Memory Service**: Should be installed and configured
106 | - **File System Access**: Write access to `~/.claude/commands/` directory
107 |
108 | ## How It Works
109 |
110 | 1. **Command Files**: Each command is a markdown file with conversational instructions
111 | 2. **Claude Code Integration**: Commands are installed to `~/.claude/commands/`
112 | 3. **Service Connection**: Commands connect via mDNS discovery or direct HTTPS endpoints
113 | 4. **Context Awareness**: Commands understand your current project and session context
114 | 5. **API Integration**: Uses standard MCP Memory Service API endpoints for all operations
115 |
116 | ## Command Features
117 |
118 | - **Machine Source Tracking**: Automatic hostname tagging for multi-device memory filtering
119 | - **Conversational Interface**: Natural language interactions following CCPlugins pattern
120 | - **Context Detection**: Automatic project and session context recognition
121 | - **Smart Tagging**: Intelligent tag generation based on current work
122 | - **Auto-Save**: Immediate storage without confirmation prompts
123 | - **Flexible Configuration**: Supports both mDNS discovery and direct HTTPS endpoints
124 | - **API Compatibility**: Works with standard MCP Memory Service API endpoints
125 |
126 | ## Example Workflow
127 |
128 | ```bash
129 | # Start a development session (automatically tagged with machine hostname)
130 | claude /memory-context --summary "Starting work on mDNS integration"
131 |
132 | # Store important decisions (includes source:machine-name tag)
133 | claude /memory-store --tags "mDNS,architecture" "Decided to use zeroconf library for service discovery"
134 |
135 | # Continue development...
136 |
137 | # Later, recall what was decided
138 | claude /memory-recall "what did we decide about mDNS last week?"
139 |
140 | # Search for related information
141 | claude /memory-search --tags "mDNS,zeroconf"
142 |
143 | # Search memories from specific machine
144 | claude /memory-search --tags "source:laptop-work"
145 |
146 | # Check service health
147 | claude /memory-health
148 | ```
149 |
150 | ## Troubleshooting
151 |
152 | ### Commands Not Available
153 | - Ensure Claude Code CLI is installed: `claude --version`
154 | - Check if commands are installed: `ls ~/.claude/commands/memory-*.md`
155 | - Reinstall commands: `python scripts/claude_commands_utils.py`
156 |
157 | ### Service Connection Issues
158 | - **Service Health**: Check if service is accessible: `curl -k https://your-endpoint:8443/api/health`
159 | - **Comprehensive Diagnostics**: Use `claude /memory-health` for detailed service status
160 | - **Local Development**: Verify server can start: `python scripts/run_memory_server.py --help`
161 | - **Endpoint Configuration**: Verify API endpoints match your service deployment
162 |
163 | ### Permission Issues
164 | - Check directory permissions: `ls -la ~/.claude/commands/`
165 | - Ensure write access to the commands directory
166 | - Try running installation with appropriate permissions
167 |
168 | ## Configuration & API Compatibility
169 |
170 | These commands integrate with your MCP Memory Service through configurable endpoints:
171 |
172 | - **Flexible Connection**: Supports both mDNS auto-discovery and direct HTTPS endpoints
173 | - **Configurable Endpoints**: Template uses `memory.local:8443` but can be customized to your setup
174 | - **API Requirements**: Commands must use these standard API endpoints to function:
175 | - `POST /api/search` - Semantic similarity search
176 | - `POST /api/search/by-tag` - Tag-based search (AND/OR matching)
177 | - `POST /api/search/by-time` - Time-based natural language queries
178 | - `GET /api/memories` - List memories with pagination
179 | - `POST /api/memories` - Store new memories
180 | - `GET /api/health/detailed` - Service health diagnostics
181 | - **Backend Compatibility**: Works with both ChromaDB and SQLite-vec storage backends
182 | - **HTTPS Support**: Uses curl with `-k` flag for self-signed certificates
183 |
184 | **Important**: Commands are configurable but must maintain compatibility with the documented API endpoints to function properly. Users can customize server locations but not the API contract.
185 |
186 | ## Development
187 |
188 | The commands are implemented using:
189 |
190 | - **Markdown Format**: Conversational instructions in markdown files
191 | - **Python Utilities**: Installation and management scripts in `scripts/claude_commands_utils.py`
192 | - **Integration Logic**: Seamless installation via main `install.py` script
193 | - **Cross-Platform Support**: Works on Windows, macOS, and Linux
194 |
195 | For more information about the MCP Memory Service, see the main project documentation.
```
--------------------------------------------------------------------------------
/claude-hooks/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Memory Awareness Hooks
2 |
3 | Automatic memory awareness and intelligent context injection for Claude Code using the MCP Memory Service.
4 |
5 | ## Quick Start
6 |
7 | ```bash
8 | cd claude-hooks
9 |
10 | # Install Natural Memory Triggers v7.1.3 (recommended)
11 | python install_hooks.py --natural-triggers
12 |
13 | # OR install basic memory awareness hooks
14 | python install_hooks.py --basic
15 | ```
16 |
17 | > **Note**: The unified Python installer replaces all previous installers and provides cross-platform compatibility with enhanced features. See [MIGRATION.md](MIGRATION.md) for details.
18 |
19 | This installs hooks that automatically:
20 | - Load relevant project memories when Claude Code starts
21 | - Inject meaningful contextual information (no more generic fluff!)
22 | - Store session insights and decisions for future reference
23 | - Provide on-demand memory retrieval when you need it
24 |
25 | ## Components
26 |
27 | - **Core Hooks**: `session-start.js` (Hook v2.2), `session-end.js`, `memory-retrieval.js` - Smart memory management
28 | - **Utilities**: Project detection, quality-aware scoring, intelligent formatting, context shift detection
29 | - **Tests**: Comprehensive integration test suite (14 tests)
30 |
31 | ## Features
32 |
33 | ### 🎯 **NEW in v8.5.7**: SessionStart Hook Visibility Features
34 | Three complementary ways to view session memory context:
35 |
36 | 1. **Visible Summary Output** - Clean bordered console display at session start
37 | - Shows: project name, storage backend, memory count (with recent indicator), git context
38 | - Respects `cleanMode` configuration for minimal output
39 |
40 | 2. **Detailed Log File** - `~/.claude/last-session-context.txt`
41 | - Auto-generated on each session start
42 | - Contains: project details, storage backend, memory statistics, git analysis, top loaded memories
43 |
44 | 3. **Status Line Display** ⭐ - Always-visible status bar at bottom of terminal
45 | - Format: `🧠 8 (8 recent) memories | 📊 10 commits`
46 | - Displays static session memory context (set once at session start)
47 | - **Requires**: `jq` (JSON parser) and Claude Code statusLine configuration
48 | - **Platform**: Linux/macOS (Windows SessionStart hook broken - issue #160)
49 | - **Windows Workaround**: Use `/session-start` slash command for manual session initialization
50 |
51 | ### ✨ **Hook v2.2.0**: Enhanced Output Control
52 | - **Clean Output Mode**: Configurable verbosity levels for minimal or detailed output
53 | - **Smart Filtering**: Hide memory scoring details while keeping essential information
54 | - **Professional UX**: Removed noisy wrapper tags and improved ANSI formatting
55 | - **Granular Control**: Fine-tune what information is displayed during hook execution
56 |
57 | ### 🧠 **Previous Features (Project v6.7.0)**: Smart Memory Context
58 | - **Quality Content Extraction**: Extracts actual decisions/insights from session summaries instead of "implementation..." fluff
59 | - **Duplicate Filtering**: Automatically removes repetitive session summaries
60 | - **Smart Timing**: Only injects memories when contextually appropriate (no more mid-session disruptions)
61 | - **On-Demand Retrieval**: Manual memory refresh with `memory-retrieval.js` hook
62 |
63 | ### 🧠 **Core Features**
64 | - **Automatic Memory Injection**: Load relevant memories at session start with quality filtering
65 | - **Project Awareness**: Detect current project context and frameworks
66 | - **Memory Consolidation**: Store session outcomes and insights
67 | - **Intelligent Selection**: Quality-aware scoring that prioritizes meaningful content over just recency
68 |
69 | ## Installation
70 |
71 | ### Unified Installer (Recommended)
72 | ```bash
73 | cd claude-hooks
74 | python install_hooks.py # Installs all features
75 |
76 | # OR install specific features
77 | python install_hooks.py --basic # Basic memory hooks only
78 | python install_hooks.py --natural-triggers # Natural Memory Triggers only
79 | ```
80 |
81 | **Prerequisites:**
82 | - Python 3.10+
83 | - Node.js (for hooks execution)
84 | - **`jq`** (required for statusLine feature - displays memory context in Claude Code status bar)
85 | - macOS: `brew install jq`
86 | - Linux: `sudo apt install jq` (Ubuntu/Debian) or equivalent
87 | - Windows: `choco install jq` or download from https://jqlang.github.io/jq/
88 |
89 | ### Manual
90 | ```bash
91 | cp -r claude-hooks/* ~/.claude/hooks/
92 | chmod +x ~/.claude/hooks/statusline.sh # Make statusline executable (Unix only)
93 | # Edit ~/.claude/settings.json and ~/.claude/hooks/config.json
94 | ```
95 |
96 | ## Verification
97 |
98 | After installation:
99 | ```bash
100 | claude --debug hooks # Should show "Found 1 hook matchers in settings"
101 | cd ~/.claude/hooks && node tests/integration-test.js # Run 14 integration tests
102 | ```
103 |
104 | ## Configuration
105 |
106 | Edit `~/.claude/hooks/config.json`:
107 | ```json
108 | {
109 | "memoryService": {
110 | "endpoint": "https://your-server:8443",
111 | "apiKey": "your-api-key",
112 | "maxMemoriesPerSession": 8,
113 | "injectAfterCompacting": false
114 | },
115 | "memoryScoring": {
116 | "weights": {
117 | "timeDecay": 0.25,
118 | "tagRelevance": 0.35,
119 | "contentRelevance": 0.15,
120 | "contentQuality": 0.25
121 | }
122 | }
123 | }
124 | ```
125 |
126 | ### ⚙️ **Output Verbosity Control (Hook v2.2.0)**
127 | ```json
128 | {
129 | "output": {
130 | "verbose": true, // Show hook activity messages
131 | "showMemoryDetails": false, // Hide detailed memory scoring
132 | "showProjectDetails": true, // Show project detection info
133 | "showScoringDetails": false,// Hide scoring breakdowns
134 | "cleanMode": false // Ultra-minimal output mode
135 | }
136 | }
137 | ```
138 |
139 | **Verbosity Levels**:
140 | - **Normal** (`verbose: true`, others `false`): Shows essential information only
141 | - **Detailed** (`showMemoryDetails: true`): Include memory scoring details
142 | - **Clean** (`cleanMode: true`): Minimal output, only success/error messages
143 | - **Silent** (`verbose: false`): Hook works silently in background
144 |
145 | ### ⚙️ **Previous Configuration Options (Project v6.7.0)**
146 | - `injectAfterCompacting`: Controls whether to inject memories after compacting events (default: `false`)
147 | - `contentQuality`: New scoring weight for content quality assessment (filters generic summaries)
148 | - Enhanced memory filtering automatically removes "implementation..." fluff
149 |
150 | ## Usage
151 |
152 | Once installed, hooks work automatically:
153 | - **Session start**: Load relevant project memories
154 | - **Session end**: Store insights and decisions
155 | - No manual intervention required
156 |
157 | ## Troubleshooting
158 |
159 | ### Quick Fixes
160 | - **Hooks not detected**: `ls ~/.claude/settings.json` → Reinstall if missing
161 | - **JSON parse errors**: Update to latest version (includes Python dict conversion)
162 | - **Connection failed**: Check `curl -k https://your-endpoint:8443/api/health`
163 | - **Wrong directory**: Move `~/.claude-code/hooks/*` to `~/.claude/hooks/`
164 |
165 | ### Debug Mode
166 | ```bash
167 | claude --debug hooks # Shows hook execution details
168 | node ~/.claude/hooks/core/session-start.js # Test individual hooks
169 | ```
170 |
171 | ### Windows-Specific Issues
172 |
173 | #### Path Configuration
174 | - **Directory Structure**: Hooks should be installed to `%USERPROFILE%\.claude\hooks\`
175 | - **JSON Path Format**: Use forward slashes in settings.json: `"command": "node C:/Users/username/.claude/hooks/core/session-start.js"`
176 | - **Avoid Backslashes**: Windows backslashes in JSON need escaping: `"C:\\\\Users\\\\..."` (prefer forward slashes instead)
177 |
178 | #### Settings Configuration Example
179 | ```json
180 | {
181 | "hooks": [
182 | {
183 | "pattern": "session-start",
184 | "command": "node C:/Users/your-username/.claude/hooks/core/session-start.js"
185 | }
186 | ]
187 | }
188 | ```
189 |
190 | #### Common Fixes
191 | - **Wrong Path Format**: If you see `session-start-wrapper.bat` errors, update your settings.json to use the Node.js script directly
192 | - **Legacy Directory**: If using old `.claude-code` directory, move contents to `.claude` directory
193 | - **Permission Issues**: Run installation scripts as Administrator if needed
194 |
195 | ## Changelog
196 |
197 | ### Hook v2.2.0 (2025-01-25) - Enhanced Output Control
198 | **🎯 Focus**: Professional UX and configurable verbosity
199 |
200 | **New Features**:
201 | - **Output Verbosity Control**: Granular configuration for hook output levels
202 | - **Clean Mode**: Ultra-minimal output option for distraction-free usage
203 | - **Smart Filtering**: Hide memory scoring details while preserving essential information
204 |
205 | **Improvements**:
206 | - **Removed Noise**: Eliminated `<session-start-hook>` wrapper tags and verbose logging
207 | - **Enhanced ANSI**: Improved color consistency and formatting throughout
208 | - **Better Defaults**: Less verbose output by default while maintaining functionality
209 |
210 | **Configuration**:
211 | - Added `output` section with `verbose`, `showMemoryDetails`, `showProjectDetails`, `cleanMode` options
212 | - Backwards compatible - existing configurations work without changes
213 | - Self-documenting configuration with clear field names
214 |
215 | ### Hook v2.1.0 - Smart Memory Integration
216 | - Advanced memory scoring and quality assessment
217 | - Enhanced context injection with deduplication
218 | - Improved project detection and context awareness
219 |
220 | ### Project v6.7.0 - Smart Memory Context
221 | - Quality content extraction and duplicate filtering
222 | - Smart timing and context shift detection
223 | - On-demand memory retrieval capabilities
224 |
225 | ## Documentation
226 |
227 | For comprehensive documentation including detailed troubleshooting, advanced configuration, and development guides, see:
228 |
229 | **[📖 Memory Awareness Hooks - Detailed Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Awareness-Hooks-Detailed-Guide)**
230 |
231 | This guide covers:
232 | - Advanced installation methods and configuration options
233 | - Comprehensive troubleshooting with solutions
234 | - Custom hook development and architecture diagrams
235 | - Memory service integration and testing frameworks
```
--------------------------------------------------------------------------------
/scripts/maintenance/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Maintenance Scripts
2 |
3 | This directory contains maintenance and diagnostic scripts for the MCP Memory Service database.
4 |
5 | ## Quick Reference
6 |
7 | | Script | Purpose | Performance | Use Case |
8 | |--------|---------|-------------|----------|
9 | | [`check_memory_types.py`](#check_memory_typespy-new) | Display type distribution | <1s | Quick health check, pre/post-consolidation validation |
10 | | [`consolidate_memory_types.py`](#consolidate_memory_typespy-new) | Consolidate fragmented types | ~5s for 1000 updates | Type taxonomy cleanup, reduce fragmentation |
11 | | [`regenerate_embeddings.py`](#regenerate_embeddingspy) | Regenerate all embeddings | ~5min for 2600 memories | After cosine migration or embedding corruption |
12 | | [`fast_cleanup_duplicates.sh`](#fast_cleanup_duplicatessh) | Fast duplicate removal | <5s for 100+ duplicates | Bulk duplicate cleanup |
13 | | [`find_all_duplicates.py`](#find_all_duplicatespy) | Detect near-duplicates | <2s for 2000 memories | Duplicate detection and analysis |
14 | | [`find_duplicates.py`](#find_duplicatespy) | API-based duplicate finder | Slow (~90s/duplicate) | Detailed duplicate analysis via API |
15 | | [`repair_sqlite_vec_embeddings.py`](#repair_sqlite_vec_embeddingspy) | Fix embedding corruption | Varies | Repair corrupted embeddings |
16 | | [`repair_zero_embeddings.py`](#repair_zero_embeddingspy) | Fix zero-valued embeddings | Varies | Repair zero embeddings |
17 | | [`cleanup_corrupted_encoding.py`](#cleanup_corrupted_encodingpy) | Fix encoding issues | Varies | Repair encoding corruption |
18 |
19 | ## Detailed Documentation
20 |
21 | ### `check_memory_types.py` 🆕
22 |
23 | **Purpose**: Quick diagnostic tool to display memory type distribution in the database.
24 |
25 | **When to Use**:
26 | - Before running consolidation to see what needs cleanup
27 | - After consolidation to verify results
28 | - Regular health checks to monitor type fragmentation
29 | - When investigating memory organization issues
30 |
31 | **Usage**:
32 | ```bash
33 | # Display type distribution (Windows)
34 | python scripts/maintenance/check_memory_types.py
35 |
36 | # On macOS/Linux, update the database path in the script first
37 | ```
38 |
39 | **Output Example**:
40 | ```
41 | Memory Type Distribution
42 | ============================================================
43 | Total memories: 1,978
44 | Unique types: 128
45 |
46 | Memory Type Count %
47 | ------------------------------------------------------------
48 | note 609 30.8%
49 | session 89 4.5%
50 | fix 67 3.4%
51 | milestone 60 3.0%
52 | reference 45 2.3%
53 | ...
54 | ```
55 |
56 | **Performance**: < 1 second for any database size (read-only SQL query)
57 |
58 | **Features**:
59 | - Shows top 30 types by frequency
60 | - Displays total memory count and unique type count
61 | - Identifies NULL/empty types as "(empty/NULL)"
62 | - Percentage calculation for easy analysis
63 | - Zero risk (read-only operation)
64 |
65 | **Workflow Integration**:
66 | 1. Run `check_memory_types.py` to identify fragmentation
67 | 2. If types > 150, consider running consolidation
68 | 3. Run `consolidate_memory_types.py --dry-run` to preview
69 | 4. Execute `consolidate_memory_types.py` to clean up
70 | 5. Run `check_memory_types.py` again to verify improvement
71 |
72 | ### `consolidate_memory_types.py` 🆕
73 |
74 | **Purpose**: Consolidates fragmented memory types into a standardized 24-type taxonomy.
75 |
76 | **When to Use**:
77 | - Type fragmentation (e.g., `bug-fix`, `bugfix`, `technical-fix` all coexisting)
78 | - Many types with only 1-2 memories
79 | - Inconsistent naming across similar concepts
80 | - After importing memories from external sources
81 | - Monthly maintenance to prevent type proliferation
82 |
83 | **Usage**:
84 | ```bash
85 | # Preview changes (safe, read-only)
86 | python scripts/maintenance/consolidate_memory_types.py --dry-run
87 |
88 | # Execute consolidation
89 | python scripts/maintenance/consolidate_memory_types.py
90 |
91 | # Use custom mapping configuration
92 | python scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json
93 | ```
94 |
95 | **Performance**: ~5 seconds for 1,000 memory updates (Nov 2025 real-world test: 1,049 updates in 5s)
96 |
97 | **Safety Features**:
98 | - ✅ Automatic timestamped backup before execution
99 | - ✅ Dry-run mode shows preview without changes
100 | - ✅ Transaction safety (atomic with rollback on error)
101 | - ✅ Database lock detection (prevents concurrent access)
102 | - ✅ HTTP server warning (recommends stopping before execution)
103 | - ✅ Disk space verification (needs 2x database size)
104 | - ✅ Backup verification (size and existence checks)
105 |
106 | **Standard 24-Type Taxonomy**:
107 |
108 | **Content Types:** `note`, `reference`, `document`, `guide`
109 | **Activity Types:** `session`, `implementation`, `analysis`, `troubleshooting`, `test`
110 | **Artifact Types:** `fix`, `feature`, `release`, `deployment`
111 | **Progress Types:** `milestone`, `status`
112 | **Infrastructure Types:** `configuration`, `infrastructure`, `process`, `security`, `architecture`
113 | **Other Types:** `documentation`, `solution`, `achievement`, `technical`
114 |
115 | **Example Consolidations**:
116 | - NULL/empty → `note`
117 | - `bug-fix`, `bugfix`, `technical-fix` → `fix`
118 | - `session-summary`, `session-checkpoint` → `session`
119 | - `project-milestone`, `development-milestone` → `milestone`
120 | - All `technical-*` → base type (remove prefix)
121 | - All `project-*` → base type (remove prefix)
122 |
123 | **Typical Results** (from production database, Nov 2025):
124 | ```
125 | Before: 342 unique types, 609 NULL/empty, fragmented naming
126 | After: 128 unique types (63% reduction), all valid types
127 | Updated: 1,049 memories (59% of database)
128 | Time: ~5 seconds
129 | ```
130 |
131 | **Configuration**:
132 |
133 | Edit `consolidation_mappings.json` to customize behavior:
134 | ```json
135 | {
136 | "mappings": {
137 | "old-type-name": "new-type-name",
138 | "bug-fix": "fix",
139 | "technical-solution": "solution"
140 | }
141 | }
142 | ```
143 |
144 | **Prerequisites**:
145 | ```bash
146 | # 1. Stop HTTP server
147 | systemctl --user stop mcp-memory-http.service
148 |
149 | # 2. Disconnect MCP clients (Claude Code: /mcp command)
150 |
151 | # 3. Verify disk space (need 2x database size)
152 | df -h ~/.local/share/mcp-memory/
153 | ```
154 |
155 | **Recovery**:
156 | ```bash
157 | # If something goes wrong, restore from automatic backup
158 | cp ~/.local/share/mcp-memory/sqlite_vec.db.backup-TIMESTAMP ~/.local/share/mcp-memory/sqlite_vec.db
159 |
160 | # Verify restoration
161 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*), COUNT(DISTINCT memory_type) FROM memories;"
162 | ```
163 |
164 | **Notes**:
165 | - Creates timestamped backup automatically (e.g., `sqlite_vec.db.backup-20251101-202042`)
166 | - No data loss - only type reassignment
167 | - Safe to run multiple times (idempotent for same mappings)
168 | - Comprehensive reporting shows before/after statistics
169 | - See `consolidation_mappings.json` for full mapping list
170 |
171 | **Maintenance Schedule**:
172 | - Run `--dry-run` monthly to check fragmentation
173 | - Execute when unique types exceed 150
174 | - Review custom mappings quarterly
175 |
176 | ---
177 |
178 | ### `regenerate_embeddings.py`
179 |
180 | **Purpose**: Regenerates embeddings for all memories in the database after schema migrations or corruption.
181 |
182 | **When to Use**:
183 | - After cosine distance migration
184 | - When embeddings table is dropped but memories are preserved
185 | - After embedding corruption detected
186 |
187 | **Usage**:
188 | ```bash
189 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/regenerate_embeddings.py
190 | ```
191 |
192 | **Performance**: ~5 minutes for 2600 memories with all-MiniLM-L6-v2 model
193 |
194 | **Notes**:
195 | - Uses configured storage backend (hybrid, cloudflare, or sqlite_vec)
196 | - Creates embeddings using sentence-transformers model
197 | - Shows progress every 100 memories
198 | - Safe to run multiple times (idempotent)
199 |
200 | ---
201 |
202 | ### `fast_cleanup_duplicates.sh`
203 |
204 | **Purpose**: Fast duplicate removal using direct SQL access instead of API calls.
205 |
206 | **When to Use**:
207 | - Bulk duplicate cleanup after detecting duplicates
208 | - When API-based deletion is too slow (>1min per duplicate)
209 | - Production cleanup without extended downtime
210 |
211 | **Usage**:
212 | ```bash
213 | bash scripts/maintenance/fast_cleanup_duplicates.sh
214 | ```
215 |
216 | **Performance**: <5 seconds for 100+ duplicates
217 |
218 | **How It Works**:
219 | 1. Stops HTTP server to avoid database locking
220 | 2. Uses direct SQL DELETE with timestamp normalization
221 | 3. Keeps newest copy of each duplicate group
222 | 4. Restarts HTTP server automatically
223 |
224 | **Warnings**:
225 | - ⚠️ Requires systemd HTTP server setup (`mcp-memory-http.service`)
226 | - ⚠️ Brief service interruption during cleanup
227 | - ⚠️ Direct database access bypasses Cloudflare sync (background sync handles it later)
228 |
229 | ---
230 |
231 | ### `find_all_duplicates.py`
232 |
233 | **Purpose**: Fast duplicate detection using content normalization and hash comparison.
234 |
235 | **When to Use**:
236 | - Regular duplicate audits
237 | - Before running cleanup operations
238 | - Investigating duplicate memory issues
239 |
240 | **Usage**:
241 | ```bash
242 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_all_duplicates.py
243 | ```
244 |
245 | **Performance**: <2 seconds for 2000 memories
246 |
247 | **Detection Method**:
248 | - Normalizes content by removing timestamps (dates, ISO timestamps)
249 | - Groups memories by MD5 hash of normalized content
250 | - Reports duplicate groups with counts
251 |
252 | **Output**:
253 | ```
254 | Found 23 groups of duplicates
255 | Total memories to delete: 115
256 | Total memories after cleanup: 1601
257 | ```
258 |
259 | ---
260 |
261 | ### `find_duplicates.py`
262 |
263 | **Purpose**: Comprehensive duplicate detection via HTTP API with detailed analysis.
264 |
265 | **When to Use**:
266 | - Need detailed duplicate analysis with full metadata
267 | - API-based workflow required
268 | - Integration with external tools
269 |
270 | **Usage**:
271 | ```bash
272 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_duplicates.py
273 | ```
274 |
275 | **Performance**: Slow (~90 seconds per duplicate deletion)
276 |
277 | **Features**:
278 | - Loads configuration from Claude hooks config
279 | - Supports self-signed SSL certificates
280 | - Pagination support for large datasets
281 | - Detailed duplicate grouping and reporting
282 |
283 | **Notes**:
284 | - 15K script with comprehensive error handling
285 | - Useful for API integration scenarios
286 | - Slower than `find_all_duplicates.py` due to network overhead
287 |
288 | ---
289 |
290 | ### `repair_sqlite_vec_embeddings.py`
291 |
292 | **Purpose**: Repairs corrupted embeddings in the sqlite-vec virtual table.
293 |
294 | **When to Use**:
295 | - Embedding corruption detected
296 | - vec0 extension errors
297 | - Database integrity issues
298 |
299 | **Usage**:
300 | ```bash
301 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/repair_sqlite_vec_embeddings.py
302 | ```
303 |
304 | **Warnings**:
305 | - ⚠️ Requires vec0 extension to be properly installed
306 | - ⚠️ May drop and recreate embeddings table
307 |
308 | ---
309 |
310 | ### `repair_zero_embeddings.py`
311 |
312 | **Purpose**: Detects and fixes memories with zero-valued embeddings.
313 |
314 | **When to Use**:
315 | - Search results showing 0% similarity scores
316 | - After embedding regeneration failures
317 | - Embedding quality issues
318 |
319 | **Usage**:
320 | ```bash
321 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/repair_zero_embeddings.py
322 | ```
323 |
324 | ---
325 |
326 | ### `cleanup_corrupted_encoding.py`
327 |
328 | **Purpose**: Fixes encoding corruption issues in memory content.
329 |
330 | **When to Use**:
331 | - UTF-8 encoding errors
332 | - Display issues with special characters
333 | - After data migration from different encoding
334 |
335 | **Usage**:
336 | ```bash
337 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/cleanup_corrupted_encoding.py
338 | ```
339 |
340 | ---
341 |
342 | ## Best Practices
343 |
344 | ### Before Running Maintenance Scripts
345 |
346 | 1. **Backup your database**:
347 | ```bash
348 | cp ~/.local/share/mcp-memory/sqlite_vec.db ~/.local/share/mcp-memory/sqlite_vec.db.backup
349 | ```
350 |
351 | 2. **Check memory count**:
352 | ```bash
353 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*) FROM memories"
354 | ```
355 |
356 | 3. **Stop HTTP server if needed** (for direct database access):
357 | ```bash
358 | systemctl --user stop mcp-memory-http.service
359 | ```
360 |
361 | ### After Running Maintenance Scripts
362 |
363 | 1. **Verify results**:
364 | ```bash
365 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*) FROM memories"
366 | ```
367 |
368 | 2. **Check for duplicates**:
369 | ```bash
370 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_all_duplicates.py
371 | ```
372 |
373 | 3. **Restart HTTP server**:
374 | ```bash
375 | systemctl --user start mcp-memory-http.service
376 | ```
377 |
378 | 4. **Test search functionality**:
379 | ```bash
380 | curl -s "http://127.0.0.1:8000/api/health"
381 | ```
382 |
383 | ### Performance Comparison
384 |
385 | | Operation | API-based | Direct SQL | Speedup |
386 | |-----------|-----------|------------|---------|
387 | | Delete 1 duplicate | ~90 seconds | ~0.05 seconds | **1800x faster** |
388 | | Delete 100 duplicates | ~2.5 hours | <5 seconds | **1800x faster** |
389 | | Find duplicates | ~30 seconds | <2 seconds | **15x faster** |
390 |
391 | **Recommendation**: Use direct SQL scripts (`fast_cleanup_duplicates.sh`, `find_all_duplicates.py`) for production maintenance. API-based scripts are useful for integration and detailed analysis.
392 |
393 | ## Troubleshooting
394 |
395 | ### "Database is locked"
396 |
397 | **Cause**: HTTP server or MCP server has open connection
398 |
399 | **Solution**:
400 | ```bash
401 | # Stop HTTP server
402 | systemctl --user stop mcp-memory-http.service
403 |
404 | # Disconnect MCP server in Claude Code
405 | # Type: /mcp
406 |
407 | # Run maintenance script
408 | bash scripts/maintenance/fast_cleanup_duplicates.sh
409 |
410 | # Restart services
411 | systemctl --user start mcp-memory-http.service
412 | ```
413 |
414 | ### "No such module: vec0"
415 |
416 | **Cause**: Python sqlite3 module doesn't load vec0 extension automatically
417 |
418 | **Solution**: Use scripts that work with the vec0-enabled environment:
419 | - ✅ Use: `fast_cleanup_duplicates.sh` (bash wrapper with Python)
420 | - ✅ Use: `/venv/bin/python` with proper storage backend
421 | - ❌ Avoid: Direct `sqlite3` Python module for virtual table operations
422 |
423 | ### Slow API Performance
424 |
425 | **Cause**: Hybrid backend syncs each operation to Cloudflare
426 |
427 | **Solution**: Use direct SQL scripts for bulk operations:
428 | ```bash
429 | bash scripts/maintenance/fast_cleanup_duplicates.sh # NOT Python API scripts
430 | ```
431 |
432 | ## Related Documentation
433 |
434 | - [Database Schema](../../docs/database-schema.md) - sqlite-vec table structure
435 | - [Storage Backends](../../CLAUDE.md#storage-backends) - Hybrid, Cloudflare, SQLite-vec
436 | - [Troubleshooting](../../docs/troubleshooting.md) - Common issues and solutions
437 |
438 | ## Contributing
439 |
440 | When adding new maintenance scripts:
441 |
442 | 1. Add comprehensive docstring explaining purpose and usage
443 | 2. Include progress indicators for long-running operations
444 | 3. Add error handling and validation
445 | 4. Document in this README with performance characteristics
446 | 5. Test with both sqlite_vec and hybrid backends
447 |
```
--------------------------------------------------------------------------------
/scripts/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Scripts
2 |
3 | This directory contains organized utility scripts for maintaining, managing, and operating the MCP Memory Service. Scripts are categorized by function for easy navigation and maintenance.
4 |
5 | ## 📁 Directory Structure
6 |
7 | ```
8 | scripts/
9 | ├── backup/ # Backup and restore operations
10 | ├── database/ # Database analysis and health monitoring
11 | ├── development/ # Development tools and debugging utilities
12 | ├── installation/ # Setup and installation scripts
13 | ├── linux/ # Linux service management shortcuts (v7.5.1+)
14 | ├── maintenance/ # Database cleanup and repair operations
15 | ├── migration/ # Data migration and schema updates
16 | ├── server/ # Server runtime and operational scripts
17 | ├── service/ # Service management and deployment
18 | ├── sync/ # Backend synchronization utilities
19 | ├── testing/ # Test scripts and validation
20 | ├── utils/ # General utility scripts and wrappers
21 | ├── validation/ # Configuration and system validation
22 | ├── run/ # Runtime execution scripts
23 | ├── archive/ # Deprecated scripts (kept for reference)
24 | └── README.md # This file
25 | ```
26 |
27 | ## 🚀 Quick Reference
28 |
29 | ### Essential Daily Operations
30 | ```bash
31 | # Service Management
32 | ./service/memory_service_manager.sh status # Check service status
33 | ./service/memory_service_manager.sh start-cloudflare # Start with Cloudflare backend
34 |
35 | # Backend Synchronization
36 | ./sync/claude_sync_commands.py status # Check sync status
37 | ./sync/claude_sync_commands.py backup # Backup Cloudflare → SQLite
38 | ./sync/claude_sync_commands.py sync # Bidirectional sync
39 | ./sync/sync_now.py --verbose # Manual on-demand hybrid sync (v7.5.1+)
40 |
41 | # Configuration Validation
42 | ./validation/validate_configuration_complete.py # Comprehensive config validation
43 | ./validation/diagnose_backend_config.py # Cloudflare backend diagnostics
44 | ./validation/verify_environment.py # Check environment setup
45 |
46 | # Database Health
47 | ./database/simple_timestamp_check.py # Quick health check
48 | ./database/db_health_check.py # Comprehensive health analysis
49 | ```
50 |
51 | ## 📂 Detailed Directory Guide
52 |
53 | ### 🔄 **sync/** - Backend Synchronization
54 | Essential for managing dual-backend setups and data synchronization.
55 |
56 | #### Cloudflare Hybrid Sync (Cloud Backend)
57 | | Script | Purpose | Quick Usage |
58 | |--------|---------|-------------|
59 | | `sync_memory_backends.py` | Core bidirectional sync engine | `python sync/sync_memory_backends.py --status` |
60 | | `claude_sync_commands.py` | User-friendly sync wrapper | `python sync/claude_sync_commands.py backup` |
61 | | `sync_now.py` | Manual on-demand hybrid sync (v7.5.1+) | `python sync/sync_now.py --verbose` |
62 | | `export_memories.py` | Export memories to JSON | `python sync/export_memories.py` |
63 | | `import_memories.py` | Import memories from JSON | `python sync/import_memories.py data.json` |
64 |
65 | **Key Features:**
66 | - ✅ Bidirectional Cloudflare ↔ SQLite synchronization
67 | - ✅ Intelligent deduplication using content hashing
68 | - ✅ Dry-run mode for safe testing
69 | - ✅ Comprehensive status reporting
70 |
71 | #### Litestream Sync (Local Network HTTP API)
72 | Located in `sync/litestream/` - Git-like staging workflow for syncing to central SQLite-vec HTTP API server.
73 |
74 | | Script | Purpose | Quick Usage |
75 | |--------|---------|-------------|
76 | | `memory_sync.sh` | Main sync orchestrator (stash → pull → apply → push) | `./sync/litestream/memory_sync.sh sync` |
77 | | `push_to_remote.sh` | Push staged changes to remote API | `./sync/litestream/push_to_remote.sh` |
78 | | `pull_remote_changes.sh` | Pull latest from remote | `./sync/litestream/pull_remote_changes.sh` |
79 | | `stash_local_changes.sh` | Stash local changes to staging | `./sync/litestream/stash_local_changes.sh` |
80 | | `apply_local_changes.sh` | Apply staged changes locally | `./sync/litestream/apply_local_changes.sh` |
81 | | `setup_local_litestream.sh` | Initialize local Litestream setup | `./sync/litestream/setup_local_litestream.sh` |
82 | | `setup_remote_litestream.sh` | Setup remote API server | `./sync/litestream/setup_remote_litestream.sh` |
83 |
84 | **Key Features:**
85 | - ✅ Git-like staging database workflow
86 | - ✅ Conflict detection and resolution
87 | - ✅ Multi-device local network synchronization
88 | - ✅ Sync to central HTTP API (e.g., `https://narrowbox.local:8443/api/memories`)
89 | - ✅ macOS launchd service for automatic replication
90 |
91 | **Note:** Litestream sync (local network) is separate from Cloudflare hybrid sync (cloud backend)
92 |
93 | ### 🛠️ **service/** - Service Management
94 | Linux service management for production deployments.
95 |
96 | | Script | Purpose | Quick Usage |
97 | |--------|---------|-------------|
98 | | `memory_service_manager.sh` | Complete service lifecycle management | `./service/memory_service_manager.sh start-cloudflare` |
99 | | `service_control.sh` | Basic service control operations | `./service/service_control.sh restart` |
100 | | `service_utils.py` | Service utility functions | Used by other service scripts |
101 | | `deploy_dual_services.sh` | Deploy dual-backend architecture | `./service/deploy_dual_services.sh` |
102 | | `update_service.sh` | Update running service | `./service/update_service.sh` |
103 |
104 | **Key Features:**
105 | - ✅ Dual-backend configuration management
106 | - ✅ Environment file handling (.env, .env.sqlite)
107 | - ✅ Service health monitoring
108 | - ✅ Integrated sync operations
109 |
110 | ### ✅ **validation/** - Configuration & System Validation
111 | Ensure proper setup and configuration.
112 |
113 | | Script | Purpose | Quick Usage |
114 | |--------|---------|-------------|
115 | | `validate_configuration_complete.py` | Comprehensive config validation | `python validation/validate_configuration_complete.py` |
116 | | `diagnose_backend_config.py` | Cloudflare backend diagnostics | `python validation/diagnose_backend_config.py` |
117 | | `validate_memories.py` | Memory data validation | `python validation/validate_memories.py` |
118 | | `validate_migration.py` | Migration validation | `python validation/validate_migration.py` |
119 | | `verify_environment.py` | Environment setup checker | `python validation/verify_environment.py` |
120 | | `verify_pytorch_windows.py` | PyTorch Windows validation | `python validation/verify_pytorch_windows.py` |
121 | | `verify_torch.py` | PyTorch installation check | `python validation/verify_torch.py` |
122 | | `check_documentation_links.py` | Documentation link validator | `python validation/check_documentation_links.py` |
123 |
124 | **Key Features:**
125 | - ✅ Claude Code global configuration validation
126 | - ✅ Cloudflare credentials verification
127 | - ✅ Environment conflict detection
128 | - ✅ Comprehensive error reporting with solutions
129 |
130 | ### 🗄️ **database/** - Database Analysis & Health
131 | Monitor and analyze database health and performance.
132 |
133 | | Script | Purpose | Quick Usage |
134 | |--------|---------|-------------|
135 | | `simple_timestamp_check.py` | Quick timestamp health check | `python database/simple_timestamp_check.py` |
136 | | `db_health_check.py` | Comprehensive health analysis | `python database/db_health_check.py` |
137 | | `analyze_sqlite_vec_db.py` | Detailed SQLite-vec analysis | `python database/analyze_sqlite_vec_db.py` |
138 | | `check_sqlite_vec_status.py` | SQLite-vec status checker | `python database/check_sqlite_vec_status.py` |
139 |
140 | **Exit Codes (for CI/CD):**
141 | - `0` - Excellent/Good health
142 | - `1` - Warning status
143 | - `2` - Critical issues
144 | - `3` - Analysis failed
145 |
146 | ### 🧹 **maintenance/** - Database Cleanup & Repair
147 | Scripts for maintaining database integrity and performance.
148 |
149 | | Script | Purpose | Quick Usage |
150 | |--------|---------|-------------|
151 | | `find_duplicates.py` | Find and remove duplicate memories | `python maintenance/find_duplicates.py --execute` |
152 | | `cleanup_corrupted_encoding.py` | Fix corrupted emoji encoding | `python maintenance/cleanup_corrupted_encoding.py --execute` |
153 | | `repair_memories.py` | Repair corrupted memory entries | `python maintenance/repair_memories.py` |
154 | | `cleanup_memories.py` | General memory cleanup | `python maintenance/cleanup_memories.py` |
155 | | `repair_sqlite_vec_embeddings.py` | Fix embedding inconsistencies | `python maintenance/repair_sqlite_vec_embeddings.py` |
156 | | `repair_zero_embeddings.py` | Fix zero/null embeddings | `python maintenance/repair_zero_embeddings.py` |
157 |
158 | **Safety Features:**
159 | - ✅ Dry-run mode available for all scripts
160 | - ✅ Comprehensive backup recommendations
161 | - ✅ Detailed reporting of changes
162 |
163 | ### 💾 **backup/** - Backup & Restore Operations
164 | Data protection and recovery operations.
165 |
166 | | Script | Purpose | Quick Usage |
167 | |--------|---------|-------------|
168 | | `backup_memories.py` | Create memory backups | `python backup/backup_memories.py` |
169 | | `restore_memories.py` | Restore from backups | `python backup/restore_memories.py backup.json` |
170 | | `backup_sqlite_vec.sh` | SQLite-vec database backup | `./backup/backup_sqlite_vec.sh` |
171 | | `export_distributable_memories.sh` | Create distributable exports | `./backup/export_distributable_memories.sh` |
172 |
173 | ### 🔄 **migration/** - Data Migration & Schema Updates
174 | Handle database migrations and data transformations.
175 |
176 | | Script | Purpose | Quick Usage |
177 | |--------|---------|-------------|
178 | | `migrate_to_cloudflare.py` | Migrate to Cloudflare backend | `python migration/migrate_to_cloudflare.py` |
179 | | `migrate_chroma_to_sqlite.py` | ChromaDB → SQLite migration | `python migration/migrate_chroma_to_sqlite.py` |
180 | | `migrate_sqlite_vec_embeddings.py` | Update embedding format | `python migration/migrate_sqlite_vec_embeddings.py` |
181 | | `migrate_timestamps.py` | Fix timestamp issues | `python migration/migrate_timestamps.py` |
182 | | `cleanup_mcp_timestamps.py` | Clean timestamp proliferation | `python migration/cleanup_mcp_timestamps.py` |
183 | | `verify_mcp_timestamps.py` | Verify timestamp consistency | `python migration/verify_mcp_timestamps.py` |
184 |
185 | ### 🏠 **installation/** - Setup & Installation
186 | Platform-specific installation and setup scripts.
187 |
188 | | Script | Purpose | Quick Usage |
189 | |--------|---------|-------------|
190 | | `install.py` | Platform-aware installer with backend selection | `python installation/install.py --storage-backend hybrid` |
191 | | `install_linux_service.py` | Linux service installation | `python installation/install_linux_service.py` |
192 | | `install_macos_service.py` | macOS service setup | `python installation/install_macos_service.py` |
193 | | `install_windows_service.py` | Windows service installation | `python installation/install_windows_service.py` |
194 | | `install_uv.py` | UV package manager installation | `python installation/install_uv.py` |
195 | | `setup_cloudflare_resources.py` | Cloudflare resource setup | `python installation/setup_cloudflare_resources.py` |
196 | | `setup_claude_mcp.sh` | Claude MCP configuration | `./installation/setup_claude_mcp.sh` |
197 | | `setup_backup_cron.sh` | Automated backup scheduling | `./installation/setup_backup_cron.sh` |
198 |
199 | ### 🐧 **linux/** - Linux Service Management Shortcuts
200 | Quick service management wrappers for Linux systemd deployments (v7.5.1+).
201 |
202 | | Script | Purpose | Quick Usage |
203 | |--------|---------|-------------|
204 | | `service_status.sh` | Check systemd service status | `./linux/service_status.sh` |
205 | | `start_service.sh` | Start mcp-memory service | `./linux/start_service.sh` |
206 | | `stop_service.sh` | Stop mcp-memory service | `./linux/stop_service.sh` |
207 | | `view_logs.sh` | View service logs | `./linux/view_logs.sh` |
208 | | `uninstall_service.sh` | Remove systemd service | `./linux/uninstall_service.sh` |
209 |
210 | **Key Features:**
211 | - ✅ Simple wrappers for systemd service management
212 | - ✅ User-level service control (~/.config/systemd/user/)
213 | - ✅ Quick status and log viewing
214 | - ✅ Clean uninstall capabilities
215 |
216 | ### 🖥️ **server/** - Server Runtime & Operations
217 | Scripts for running and managing the memory server.
218 |
219 | | Script | Purpose | Quick Usage |
220 | |--------|---------|-------------|
221 | | `run_memory_server.py` | Start memory server | `python server/run_memory_server.py` |
222 | | `run_http_server.py` | Start HTTP API server | `python server/run_http_server.py` |
223 | | `check_server_health.py` | Health check endpoint | `python server/check_server_health.py` |
224 | | `memory_offline.py` | Offline memory operations | `python server/memory_offline.py` |
225 | | `preload_models.py` | Pre-load ML models | `python server/preload_models.py` |
226 |
227 | ### 🧪 **testing/** - Test Scripts & Validation
228 | Comprehensive testing and validation scripts.
229 |
230 | | Script | Purpose | Quick Usage |
231 | |--------|---------|-------------|
232 | | `run_complete_test.py` | Complete system test | `python testing/run_complete_test.py` |
233 | | `test_memory_api.py` | API functionality tests | `python testing/test_memory_api.py` |
234 | | `test_cloudflare_backend.py` | Cloudflare backend tests | `python testing/test_cloudflare_backend.py` |
235 | | `test_sqlite_vec_embeddings.py` | Embedding system tests | `python testing/test_sqlite_vec_embeddings.py` |
236 | | `simple_test.py` | Basic functionality test | `python testing/simple_test.py` |
237 |
238 | ### 🔧 **utils/** - General Utilities
239 | Helper scripts and utility functions.
240 |
241 | | Script | Purpose | Quick Usage |
242 | |--------|---------|-------------|
243 | | `claude_commands_utils.py` | Claude command utilities | Used by Claude Code hooks |
244 | | `query_memories.py` | Direct memory querying | `python utils/query_memories.py "search term"` |
245 | | `memory_wrapper_uv.py` | UV package manager wrapper | Used by other scripts |
246 | | `generate_personalized_claude_md.sh` | Generate custom CLAUDE.md | `./utils/generate_personalized_claude_md.sh` |
247 |
248 | ### 🛠️ **development/** - Development Tools
249 | Tools for developers and debugging.
250 |
251 | | Script | Purpose | Quick Usage |
252 | |--------|---------|-------------|
253 | | `setup-git-merge-drivers.sh` | Configure git merge drivers | `./development/setup-git-merge-drivers.sh` |
254 | | `fix_mdns.sh` | Fix mDNS issues | `./development/fix_mdns.sh` |
255 | | `uv-lock-merge.sh` | Handle UV lock file merges | `./development/uv-lock-merge.sh` |
256 | | `find_orphaned_files.py` | Find orphaned database files | `python development/find_orphaned_files.py` |
257 |
258 | ## 🎯 Common Use Cases
259 |
260 | ### Initial Setup
261 | ```bash
262 | # 1. Validate environment
263 | python validation/verify_environment.py
264 |
265 | # 2. Install appropriate service
266 | python installation/install_linux_service.py
267 |
268 | # 3. Validate configuration
269 | python validation/validate_config.py
270 |
271 | # 4. Start service
272 | ./service/memory_service_manager.sh start-cloudflare
273 | ```
274 |
275 | ### Daily Operations
276 | ```bash
277 | # Check overall health
278 | ./service/memory_service_manager.sh status
279 | python database/simple_timestamp_check.py
280 |
281 | # Sync backends
282 | python sync/claude_sync_commands.py sync
283 |
284 | # Backup
285 | python sync/claude_sync_commands.py backup
286 | ```
287 |
288 | ### Troubleshooting
289 | ```bash
290 | # Validate configuration
291 | python validation/validate_config.py
292 |
293 | # Check database health
294 | python database/db_health_check.py
295 |
296 | # Fix common issues
297 | python maintenance/find_duplicates.py --execute
298 | python maintenance/cleanup_corrupted_encoding.py --execute
299 | ```
300 |
301 | ### Migration & Upgrades
302 | ```bash
303 | # Before migration - backup
304 | python backup/backup_memories.py
305 |
306 | # Migrate to new backend
307 | python migration/migrate_to_cloudflare.py
308 |
309 | # Verify migration
310 | python validation/validate_memories.py
311 | ```
312 |
313 | ## 🚨 Safety Guidelines
314 |
315 | ### Before Running Maintenance Scripts
316 | 1. **Always backup first**: `python backup/backup_memories.py`
317 | 2. **Use dry-run mode**: Most scripts support `--dry-run` or similar
318 | 3. **Test with small datasets** when possible
319 | 4. **Check database health**: `python database/simple_timestamp_check.py`
320 |
321 | ### Script Execution Order
322 | 1. **Validation** scripts first (check environment)
323 | 2. **Backup** before any data modifications
324 | 3. **Maintenance** operations (cleanup, repair)
325 | 4. **Verification** after changes
326 | 5. **Service restart** if needed
327 |
328 | ## 🔗 Integration with Documentation
329 |
330 | This scripts directory integrates with:
331 | - **CLAUDE.md**: Essential commands for Claude Code users
332 | - **AGENTS.md**: Agent development and release process
333 | - **Wiki**: Detailed setup and troubleshooting guides
334 | - **GitHub Actions**: CI/CD pipeline integration
335 |
336 | ## 📝 Adding New Scripts
337 |
338 | When adding new scripts:
339 | 1. **Choose appropriate category** based on primary function
340 | 2. **Follow naming conventions**: `snake_case.py` or `kebab-case.sh`
341 | 3. **Include proper documentation** in script headers
342 | 4. **Add safety mechanisms** for data-modifying operations
343 | 5. **Update this README** with script description
344 | 6. **Test with multiple backends** (SQLite-vec, Cloudflare)
345 |
346 | ## 🆘 Getting Help
347 |
348 | - **Configuration issues**: Run `python validation/validate_config.py`
349 | - **Database problems**: Run `python database/db_health_check.py`
350 | - **Documentation links**: Run `python validation/check_documentation_links.py`
351 | - **General health**: Run `./service/memory_service_manager.sh status`
352 |
353 | For complex issues, check the [project wiki](https://github.com/doobidoo/mcp-memory-service/wiki) or create an issue with the output from relevant diagnostic scripts.
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service
2 |
3 | [](https://opensource.org/licenses/Apache-2.0)
4 | [](https://pypi.org/project/mcp-memory-service/)
5 | [](https://pypi.org/project/mcp-memory-service/)
6 | [](https://github.com/doobidoo/mcp-memory-service/actions/workflows/main.yml)
7 | [](https://pypi.org/project/mcp-memory-service/)
8 | [](https://github.com/doobidoo/mcp-memory-service/commits/main)
9 | [](https://github.com/doobidoo/mcp-memory-service/stargazers)
10 | [](https://github.com/doobidoo/mcp-memory-service#-in-production)
11 |
12 | [](https://claude.ai)
13 | [](https://cursor.sh)
14 | [](https://modelcontextprotocol.io/)
15 | [](https://github.com/doobidoo/mcp-memory-service/wiki)
16 | [](https://github.com/doobidoo/mcp-memory-service/pkgs/container/mcp-memory-service)
17 | [](https://github.com/doobidoo/mcp-memory-service/issues)
18 | [](https://deepwiki.com/doobidoo/mcp-memory-service)
19 |
20 | **Production-ready MCP memory service** with **zero database locks**, **hybrid backend** (fast local + cloud sync), and **intelligent memory search** for **AI assistants**. Features **v8.9.0 auto-configuration** for multi-client access, **5ms local reads** with background Cloudflare sync, **Natural Memory Triggers** with 85%+ accuracy, and **OAuth 2.1 team collaboration**. Works with **Claude Desktop, VS Code, Cursor, Continue, and 13+ AI applications**.
21 |
22 | <img width="240" alt="MCP Memory Service" src="https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555" />
23 |
24 | ## 🚀 Quick Start (2 minutes)
25 |
26 | ### 🆕 Latest Release: **v8.42.0** (Nov 27, 2025)
27 |
28 | **Memory Awareness Enhancements**
29 |
30 | - 👁️ **Visible Memory Injection** - Users now see top 3 memories at session start with relevance scores, age, and tags
31 | - 🎯 **Quality Session Summaries** - Raised quality thresholds (200 char min, 0.5 confidence) to prevent generic boilerplate
32 | - 🤖 **LLM-Powered Summarization** - Optional Gemini CLI integration for intelligent session analysis
33 | - 🧹 **Database Quality** - Cleaned 167 generic summaries (3352 → 3185 memories)
34 |
35 | **Previous Releases**:
36 | - **v8.41.2** - Hook Installer Utility File Deployment (ALL 14 utilities copied, future-proof glob pattern)
37 | - **v8.41.1** - Context Formatter Memory Sorting (recency sorting within categories, newest first)
38 | - **v8.41.0** - Session Start Hook Reliability Improvements (error suppression, clean output, memory filtering, classification fixes)
39 | - **v8.40.0** - Session Start Version Display (automatic version comparison, PyPI status labels)
40 | - **v8.39.1** - Dashboard Analytics Bug Fixes: Three critical fixes (top tags filtering, recent activity display, storage report fields)
41 | - **v8.39.0** - Performance Optimization: Storage-layer date-range filtering (10x faster analytics, 97% data transfer reduction)
42 | - **v8.38.1** - Critical Hotfix: HTTP MCP JSON-RPC 2.0 compliance fix (Claude Code/Desktop connection failures resolved)
43 | - **v8.38.0** - Code Quality: Phase 2b COMPLETE (~176-186 lines duplicate code eliminated, 10 consolidations)
44 | - **v8.37.0** - Code Quality: Phase 2a COMPLETE (5 duplicate high-complexity functions eliminated)
45 | - **v8.36.1** - Critical Hotfix: HTTP server startup crash fix (forward reference error in analytics.py)
46 | - **v8.36.0** - Code Quality: Phase 2 COMPLETE (100% of target achieved, -39 complexity points)
47 | - **v8.35.0** - Code Quality: Phase 2 Batch 1 (install.py, cloudflare.py, -15 complexity points)
48 | - **v8.34.0** - Code Quality: Phase 2 Complexity Reduction (analytics.py refactored, 11 → 6-7 complexity)
49 | - **v8.33.0** - Critical Installation Bug Fix + Code Quality Improvements (dead code cleanup, automatic MCP setup)
50 | - **v8.32.0** - Code Quality Excellence: pyscn Static Analysis Integration (multi-layer QA workflow)
51 | - **v8.31.0** - Revolutionary Batch Update Performance (21,428x faster memory consolidation)
52 | - **v8.30.0** - Analytics Intelligence: Adaptive Charts & Critical Data Fixes (accurate trend visualization)
53 | - **v8.28.1** - Critical HTTP MCP Transport JSON-RPC 2.0 Compliance Fix (Claude Code compatibility)
54 | - **v8.28.0** - Cloudflare AND/OR Tag Filtering (unified search API, 3-5x faster hybrid sync)
55 | - **v8.27.1** - Critical Hotfix: Timestamp Regression (created_at preservation during metadata sync)
56 | - **v8.26.0** - Revolutionary MCP Performance (534,628x faster tools, 90%+ cache hit rate)
57 | - **v8.25.0** - Hybrid Backend Drift Detection (automatic metadata sync, bidirectional awareness)
58 | - **v8.24.4** - Code Quality Improvements from Gemini Code Assist (regex sanitization, DOM caching)
59 | - **v8.24.3** - Test Coverage & Release Agent Improvements (tag+time filtering tests, version history fix)
60 | - **v8.24.2** - CI/CD Workflow Fixes (bash errexit handling, exit code capture)
61 | - **v8.24.1** - Test Infrastructure Improvements (27 test failures resolved, 63% → 71% pass rate)
62 | - **v8.24.0** - PyPI Publishing Enabled (automated package publishing via GitHub Actions)
63 | - **v8.23.1** - Stale Virtual Environment Prevention System (6-layer developer protection)
64 | - **v8.23.0** - Consolidation Scheduler via Code Execution API (88% token reduction)
65 |
66 | **📖 Full Details**: [CHANGELOG.md](CHANGELOG.md#8222---2025-11-09) | [All Releases](https://github.com/doobidoo/mcp-memory-service/releases)
67 |
68 | ---
69 |
70 | ```bash
71 | # One-command installation with auto-configuration
72 | git clone https://github.com/doobidoo/mcp-memory-service.git
73 | cd mcp-memory-service && python install.py
74 |
75 | # Choose option 4 (Hybrid - RECOMMENDED) when prompted
76 | # Installer automatically configures:
77 | # ✅ SQLite pragmas for concurrent access
78 | # ✅ Cloudflare credentials for cloud sync
79 | # ✅ Claude Desktop integration
80 |
81 | # Done! Fast local + cloud sync with zero database locks
82 | ```
83 |
84 | ### PyPI Installation (Simplest)
85 |
86 | **Install from PyPI:**
87 | ```bash
88 | # Install latest version from PyPI
89 | pip install mcp-memory-service
90 |
91 | # Or with uv (faster)
92 | uv pip install mcp-memory-service
93 | ```
94 |
95 | **Then configure Claude Desktop** by adding to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
96 | ```json
97 | {
98 | "mcpServers": {
99 | "memory": {
100 | "command": "memory",
101 | "args": ["server"],
102 | "env": {
103 | "MCP_MEMORY_STORAGE_BACKEND": "hybrid"
104 | }
105 | }
106 | }
107 | }
108 | ```
109 |
110 | For advanced configuration with the interactive installer, clone the repo and run `python scripts/installation/install.py`.
111 |
112 | ### Developer Setup (Contributing)
113 |
114 | **For development and contributing**, use editable install to ensure source code changes take effect immediately:
115 |
116 | ```bash
117 | # Clone repository
118 | git clone https://github.com/doobidoo/mcp-memory-service.git
119 | cd mcp-memory-service
120 |
121 | # Create and activate virtual environment
122 | python -m venv venv
123 | source venv/bin/activate # On Windows: venv\Scripts\activate
124 |
125 | # CRITICAL: Editable install (code changes take effect immediately)
126 | pip install -e .
127 |
128 | # Verify editable mode (should show source directory, not site-packages)
129 | pip show mcp-memory-service | grep Location
130 | # Expected: Location: /path/to/mcp-memory-service/src
131 |
132 | # Start development server
133 | uv run memory server
134 | ```
135 |
136 | **⚠️ Important**: Editable install (`-e` flag) ensures MCP servers load from source code, not stale `site-packages`. Without this, source changes won't be reflected until you reinstall the package.
137 |
138 | **Version Mismatch Check:**
139 | ```bash
140 | # Verify installed version matches source code
141 | python scripts/validation/check_dev_setup.py
142 | ```
143 |
144 | See [CLAUDE.md](CLAUDE.md#development-setup-critical) for complete development guidelines.
145 |
146 | ### Traditional Setup Options
147 |
148 | **Universal Installer (Most Compatible):**
149 | ```bash
150 | # Clone and install with automatic platform detection
151 | git clone https://github.com/doobidoo/mcp-memory-service.git
152 | cd mcp-memory-service
153 |
154 | # Lightweight installation (SQLite-vec with ONNX embeddings - recommended)
155 | python install.py
156 |
157 | # Add full ML capabilities (torch + sentence-transformers for advanced features)
158 | python install.py --with-ml
159 |
160 | # Install with hybrid backend (SQLite-vec + Cloudflare sync)
161 | python install.py --storage-backend hybrid
162 | ```
163 |
164 | **📝 Installation Options Explained:**
165 | - **Default (recommended)**: Lightweight SQLite-vec with ONNX embeddings - fast, works offline, <100MB dependencies
166 | - **`--with-ml`**: Adds PyTorch + sentence-transformers for advanced ML features - heavier but more capable
167 | - **`--storage-backend hybrid`**: Hybrid backend with SQLite-vec + Cloudflare sync - best for multi-device access
168 |
169 | **Docker (Fastest):**
170 | ```bash
171 | # For MCP protocol (Claude Desktop)
172 | docker-compose up -d
173 |
174 | # For HTTP API + OAuth (Team Collaboration)
175 | docker-compose -f docker-compose.http.yml up -d
176 | ```
177 |
178 | **Smithery (Claude Desktop):**
179 | ```bash
180 | # Auto-install for Claude Desktop
181 | npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
182 | ```
183 |
184 | ## ⚠️ v6.17.0+ Script Migration Notice
185 |
186 | **Updating from an older version?** Scripts have been reorganized for better maintainability:
187 | - **Recommended**: Use `python -m mcp_memory_service.server` in your Claude Desktop config (no path dependencies!)
188 | - **Alternative 1**: Use `uv run memory server` with UV tooling
189 | - **Alternative 2**: Update path from `scripts/run_memory_server.py` to `scripts/server/run_memory_server.py`
190 | - **Backward compatible**: Old path still works with a migration notice
191 |
192 | ## ⚠️ First-Time Setup Expectations
193 |
194 | On your first run, you'll see some warnings that are **completely normal**:
195 |
196 | - **"WARNING: Failed to load from cache: No snapshots directory"** - The service is checking for cached models (first-time setup)
197 | - **"WARNING: Using TRANSFORMERS_CACHE is deprecated"** - Informational warning, doesn't affect functionality
198 | - **Model download in progress** - The service automatically downloads a ~25MB embedding model (takes 1-2 minutes)
199 |
200 | These warnings disappear after the first successful run. The service is working correctly! For details, see our [First-Time Setup Guide](docs/first-time-setup.md).
201 |
202 | ### 🐍 Python 3.13 Compatibility Note
203 |
204 | **sqlite-vec** may not have pre-built wheels for Python 3.13 yet. If installation fails:
205 | - The installer will automatically try multiple installation methods
206 | - Consider using Python 3.12 for the smoothest experience: `brew install [email protected]`
207 | - Alternative: Use Cloudflare backend with `--storage-backend cloudflare`
208 | - See [Troubleshooting Guide](docs/troubleshooting/general.md#python-313-sqlite-vec-issues) for details
209 |
210 | ### 🍎 macOS SQLite Extension Support
211 |
212 | **macOS users** may encounter `enable_load_extension` errors with sqlite-vec:
213 | - **System Python** on macOS lacks SQLite extension support by default
214 | - **Solution**: Use Homebrew Python: `brew install python && rehash`
215 | - **Alternative**: Use pyenv: `PYTHON_CONFIGURE_OPTS='--enable-loadable-sqlite-extensions' pyenv install 3.12.0`
216 | - **Fallback**: Use Cloudflare or Hybrid backend: `--storage-backend cloudflare` or `--storage-backend hybrid`
217 | - See [Troubleshooting Guide](docs/troubleshooting/general.md#macos-sqlite-extension-issues) for details
218 |
219 | ## 🎯 Memory Awareness in Action
220 |
221 | **Intelligent Context Injection** - See how the memory service automatically surfaces relevant information at session start:
222 |
223 | <img src="docs/assets/images/memory-awareness-hooks-example.png" alt="Memory Awareness Hooks in Action" width="100%" />
224 |
225 | **What you're seeing:**
226 | - 🧠 **Automatic memory injection** - 8 relevant memories found from 2,526 total
227 | - 📂 **Smart categorization** - Recent Work, Current Problems, Additional Context
228 | - 📊 **Git-aware analysis** - Recent commits and keywords automatically extracted
229 | - 🎯 **Relevance scoring** - Top memories scored at 100% (today), 89% (8d ago), 84% (today)
230 | - ⚡ **Fast retrieval** - SQLite-vec backend with 5ms read performance
231 | - 🔄 **Background sync** - Hybrid backend syncing to Cloudflare
232 |
233 | **Result**: Claude starts every session with full project context - no manual prompting needed.
234 |
235 | ## 📚 Complete Documentation
236 |
237 | **👉 Visit our comprehensive [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) for detailed guides:**
238 |
239 | ### 🧠 v7.1.3 Natural Memory Triggers (Latest)
240 | - **[Natural Memory Triggers v7.1.3 Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)** - Intelligent automatic memory awareness
241 | - ✅ **85%+ trigger accuracy** with semantic pattern detection
242 | - ✅ **Multi-tier performance** (50ms instant → 150ms fast → 500ms intensive)
243 | - ✅ **CLI management system** for real-time configuration
244 | - ✅ **Git-aware context** integration for enhanced relevance
245 | - ✅ **Zero-restart installation** with dynamic hook loading
246 |
247 | ### 🆕 v7.0.0 OAuth & Team Collaboration
248 | - **[🔐 OAuth 2.1 Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/OAuth-2.1-Setup-Guide)** - **NEW!** Complete OAuth 2.1 Dynamic Client Registration guide
249 | - **[🔗 Integration Guide](https://github.com/doobidoo/mcp-memory-service/wiki/03-Integration-Guide)** - Claude Desktop, **Claude Code HTTP transport**, VS Code, and more
250 | - **[🛡️ Advanced Configuration](https://github.com/doobidoo/mcp-memory-service/wiki/04-Advanced-Configuration)** - **Updated!** OAuth security, enterprise features
251 |
252 | ### 🧬 v8.23.0+ Memory Consolidation
253 | - **[📊 Memory Consolidation System Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Consolidation-System-Guide)** - **NEW!** Automated memory maintenance with real-world performance metrics
254 | - ✅ **Dream-inspired consolidation** (decay scoring, association discovery, compression, archival)
255 | - ✅ **24/7 automatic scheduling** (daily/weekly/monthly via HTTP server)
256 | - ✅ **Token-efficient Code Execution API** (90% token reduction vs MCP tools)
257 | - ✅ **Real-world performance data** (4-6 min for 2,495 memories with hybrid backend)
258 | - ✅ **Three manual trigger methods** (HTTP API, MCP tools, Python API)
259 |
260 | ### 🚀 Setup & Installation
261 | - **[📋 Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** - Complete installation for all platforms and use cases
262 | - **[🖥️ Platform Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/02-Platform-Setup-Guide)** - Windows, macOS, and Linux optimizations
263 | - **[⚡ Performance Optimization](https://github.com/doobidoo/mcp-memory-service/wiki/05-Performance-Optimization)** - Speed up queries, optimize resources, scaling
264 |
265 | ### 🧠 Advanced Topics
266 | - **[👨💻 Development Reference](https://github.com/doobidoo/mcp-memory-service/wiki/06-Development-Reference)** - Claude Code hooks, API reference, debugging
267 | - **[🔧 Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)** - **Updated!** OAuth troubleshooting + common issues
268 | - **[❓ FAQ](https://github.com/doobidoo/mcp-memory-service/wiki/08-FAQ)** - Frequently asked questions
269 | - **[📝 Examples](https://github.com/doobidoo/mcp-memory-service/wiki/09-Examples)** - Practical code examples and workflows
270 |
271 | ### 📂 Internal Documentation
272 | - **[📊 Repository Statistics](docs/statistics/REPOSITORY_STATISTICS.md)** - 10 months of development metrics, activity patterns, and insights
273 | - **[🏗️ Architecture Specs](docs/architecture/)** - Search enhancement specifications and design documents
274 | - **[👩💻 Development Docs](docs/development/)** - AI agent instructions, release checklist, refactoring notes
275 | - **[🚀 Deployment Guides](docs/deployment/)** - Docker, dual-service, and production deployment
276 | - **[📚 Additional Guides](docs/guides/)** - Storage backends, migration, mDNS discovery
277 |
278 | ## ✨ Key Features
279 |
280 | ### 🏆 **Production-Ready Reliability** 🆕 v8.9.0
281 | - **Hybrid Backend** - Fast 5ms local SQLite + background Cloudflare sync (RECOMMENDED default)
282 | - Zero user-facing latency for cloud operations
283 | - Automatic multi-device synchronization
284 | - Graceful offline operation
285 | - **Zero Database Locks** - Concurrent HTTP + MCP server access works flawlessly
286 | - Auto-configured SQLite pragmas (`busy_timeout=15000,cache_size=20000`)
287 | - WAL mode with proper multi-client coordination
288 | - Tested: 5/5 concurrent writes succeeded with no errors
289 | - **Auto-Configuration** - Installer handles everything
290 | - SQLite pragmas for concurrent access
291 | - Cloudflare credentials with connection testing
292 | - Claude Desktop integration with hybrid backend
293 | - Graceful fallback to sqlite_vec if cloud setup fails
294 |
295 | ### 📄 **Document Ingestion System** v8.6.0
296 | - **Interactive Web UI** - Drag-and-drop document upload with real-time progress
297 | - **Multiple Formats** - PDF, TXT, MD, JSON with intelligent chunking
298 | - **Document Viewer** - Browse chunks, view metadata, search content
299 | - **Smart Tagging** - Automatic tagging with length validation (max 100 chars)
300 | - **Optional semtools** - Enhanced PDF/DOCX/PPTX parsing with LlamaParse
301 | - **Security Hardened** - Path traversal protection, XSS prevention, input validation
302 | - **7 New Endpoints** - Complete REST API for document management
303 |
304 | ### 🔐 **Enterprise Authentication & Team Collaboration**
305 | - **OAuth 2.1 Dynamic Client Registration** - RFC 7591 & RFC 8414 compliant
306 | - **Claude Code HTTP Transport** - Zero-configuration team collaboration
307 | - **JWT Authentication** - Enterprise-grade security with scope validation
308 | - **Auto-Discovery Endpoints** - Seamless client registration and authorization
309 | - **Multi-Auth Support** - OAuth + API keys + optional anonymous access
310 |
311 | ### 🧠 **Intelligent Memory Management**
312 | - **Semantic search** with vector embeddings
313 | - **Natural language time queries** ("yesterday", "last week")
314 | - **Tag-based organization** with smart categorization
315 | - **Memory consolidation** with dream-inspired algorithms
316 | - **Document-aware search** - Query across uploaded documents and manual memories
317 |
318 | ### 🔗 **Universal Compatibility**
319 | - **Claude Desktop** - Native MCP integration
320 | - **Claude Code** - **HTTP transport** + Memory-aware development with hooks
321 | - 🪟 **Windows Support**: `/session-start` command for manual session initialization (workaround for issue #160)
322 | - 🍎 **macOS/Linux**: Full automatic SessionStart hooks + slash command
323 | - **VS Code, Cursor, Continue** - IDE extensions
324 | - **13+ AI applications** - REST API compatibility
325 |
326 | ### 💾 **Flexible Storage**
327 | - **Hybrid** 🌟 (RECOMMENDED) - Fast local SQLite + background Cloudflare sync (v8.9.0 default)
328 | - 5ms local reads with zero user-facing latency
329 | - Multi-device synchronization
330 | - Zero database locks with auto-configured pragmas
331 | - Automatic backups and cloud persistence
332 | - **SQLite-vec** - Local-only storage (lightweight ONNX embeddings, 5ms reads)
333 | - Good for single-user offline use
334 | - No cloud dependencies
335 | - **Cloudflare** - Cloud-only storage (global edge distribution with D1 + Vectorize)
336 | - Network-dependent performance
337 |
338 | > **Note**: All heavy ML dependencies (PyTorch, sentence-transformers) are now optional to dramatically reduce build times and image sizes. SQLite-vec uses lightweight ONNX embeddings by default. Install with `--with-ml` for full ML capabilities.
339 |
340 | ### 🚀 **Production Ready**
341 | - **Cross-platform** - Windows, macOS, Linux
342 | - **Service installation** - Auto-start background operation
343 | - **HTTPS/SSL** - Secure connections with OAuth 2.1
344 | - **Docker support** - Easy deployment with team collaboration
345 | - **Interactive Dashboard** - Web UI at http://127.0.0.1:8888/ for complete management
346 |
347 | ## 💡 Basic Usage
348 |
349 | ### 📄 **Document Ingestion** (v8.6.0+)
350 | ```bash
351 | # Start server with web interface
352 | uv run memory server --http
353 |
354 | # Access interactive dashboard
355 | open http://127.0.0.1:8888/
356 |
357 | # Upload documents via CLI
358 | curl -X POST http://127.0.0.1:8888/api/documents/upload \
359 | -F "[email protected]" \
360 | -F "tags=documentation,reference"
361 |
362 | # Search document content
363 | curl -X POST http://127.0.0.1:8888/api/search \
364 | -H "Content-Type: application/json" \
365 | -d '{"query": "authentication flow", "limit": 10}'
366 | ```
367 |
368 | ### 🔗 **Team Collaboration with OAuth** (v7.0.0+)
369 | ```bash
370 | # Start OAuth-enabled server for team collaboration
371 | export MCP_OAUTH_ENABLED=true
372 | uv run memory server --http
373 |
374 | # Claude Code team members connect via HTTP transport
375 | claude mcp add --transport http memory-service http://your-server:8000/mcp
376 | # → Automatic OAuth discovery, registration, and authentication
377 | ```
378 |
379 | ### 🧠 **Memory Operations**
380 | ```bash
381 | # Store a memory
382 | uv run memory store "Fixed race condition in authentication by adding mutex locks"
383 |
384 | # Search for relevant memories
385 | uv run memory recall "authentication race condition"
386 |
387 | # Search by tags
388 | uv run memory search --tags python debugging
389 |
390 | # Check system health (shows OAuth status)
391 | uv run memory health
392 | ```
393 |
394 | ## 🔧 Configuration
395 |
396 | ### Claude Desktop Integration
397 | **Recommended approach** - Add to your Claude Desktop config (`~/.claude/config.json`):
398 |
399 | ```json
400 | {
401 | "mcpServers": {
402 | "memory": {
403 | "command": "python",
404 | "args": ["-m", "mcp_memory_service.server"],
405 | "env": {
406 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
407 | }
408 | }
409 | }
410 | }
411 | ```
412 |
413 | **Alternative approaches:**
414 | ```json
415 | // Option 1: UV tooling (if using UV)
416 | {
417 | "mcpServers": {
418 | "memory": {
419 | "command": "uv",
420 | "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
421 | "env": {
422 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
423 | }
424 | }
425 | }
426 | }
427 |
428 | // Option 2: Direct script path (v6.17.0+)
429 | {
430 | "mcpServers": {
431 | "memory": {
432 | "command": "python",
433 | "args": ["/path/to/mcp-memory-service/scripts/server/run_memory_server.py"],
434 | "env": {
435 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
436 | }
437 | }
438 | }
439 | }
440 | ```
441 |
442 | ### Environment Variables
443 |
444 | **Hybrid Backend (v8.9.0+ RECOMMENDED):**
445 | ```bash
446 | # Hybrid backend with auto-configured pragmas
447 | export MCP_MEMORY_STORAGE_BACKEND=hybrid
448 | export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"
449 |
450 | # Cloudflare credentials (required for hybrid)
451 | export CLOUDFLARE_API_TOKEN="your-token"
452 | export CLOUDFLARE_ACCOUNT_ID="your-account"
453 | export CLOUDFLARE_D1_DATABASE_ID="your-db-id"
454 | export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index"
455 |
456 | # Enable HTTP API
457 | export MCP_HTTP_ENABLED=true
458 | export MCP_HTTP_PORT=8000
459 |
460 | # Security
461 | export MCP_API_KEY="your-secure-key"
462 | ```
463 |
464 | **SQLite-vec Only (Local):**
465 | ```bash
466 | # Local-only storage
467 | export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
468 | export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"
469 | ```
470 |
471 | ## 🏗️ Architecture
472 |
473 | ```
474 | ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
475 | │ AI Clients │ │ MCP Memory │ │ Storage Backend │
476 | │ │ │ Service v8.9 │ │ │
477 | │ • Claude Desktop│◄──►│ • MCP Protocol │◄──►│ • Hybrid 🌟 │
478 | │ • Claude Code │ │ • HTTP Transport│ │ (5ms local + │
479 | │ (HTTP/OAuth) │ │ • OAuth 2.1 Auth│ │ cloud sync) │
480 | │ • VS Code │ │ • Memory Store │ │ • SQLite-vec │
481 | │ • Cursor │ │ • Semantic │ │ • Cloudflare │
482 | │ • 13+ AI Apps │ │ Search │ │ │
483 | │ • Web Dashboard │ │ • Doc Ingestion │ │ Zero DB Locks ✅│
484 | │ (Port 8888) │ │ • Zero DB Locks │ │ Auto-Config ✅ │
485 | └─────────────────┘ └─────────────────┘ └─────────────────┘
486 | ```
487 |
488 | ## 🛠️ Development
489 |
490 | ### Project Structure
491 | ```
492 | mcp-memory-service/
493 | ├── src/mcp_memory_service/ # Core application
494 | │ ├── models/ # Data models
495 | │ ├── storage/ # Storage backends
496 | │ ├── web/ # HTTP API & dashboard
497 | │ └── server.py # MCP server
498 | ├── scripts/ # Utilities & installation
499 | ├── tests/ # Test suite
500 | └── tools/docker/ # Docker configuration
501 | ```
502 |
503 | ### Contributing
504 | 1. Fork the repository
505 | 2. Create a feature branch
506 | 3. Make your changes with tests
507 | 4. Submit a pull request
508 |
509 | See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
510 |
511 | ## 🆘 Support
512 |
513 | - **📖 Documentation**: [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) - Comprehensive guides
514 | - **🐛 Bug Reports**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)
515 | - **💬 Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)
516 | - **🔧 Troubleshooting**: [Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)
517 | - **✅ Configuration Validator**: Run `python scripts/validation/validate_configuration_complete.py` to check your setup
518 | - **🔄 Backend Sync Tools**: See [scripts/README.md](scripts/README.md#backend-synchronization) for Cloudflare↔SQLite sync
519 |
520 | ## 📊 In Production
521 |
522 | **Real-world metrics from active deployments:**
523 | - **1700+ memories** stored and actively used across teams
524 | - **5ms local reads** with hybrid backend (v8.9.0)
525 | - **Zero database locks** with concurrent HTTP + MCP access (v8.9.0)
526 | - Tested: 5/5 concurrent writes succeeded
527 | - Auto-configured pragmas prevent lock errors
528 | - **<500ms response time** for semantic search (local & HTTP transport)
529 | - **65% token reduction** in Claude Code sessions with OAuth collaboration
530 | - **96.7% faster** context setup (15min → 30sec)
531 | - **100% knowledge retention** across sessions and team members
532 | - **Zero-configuration** setup success rate: **98.5%** (OAuth + hybrid backend)
533 |
534 | ## 🏆 Recognition
535 |
536 | - [](https://smithery.ai/server/@doobidoo/mcp-memory-service) **Verified MCP Server**
537 | - [](https://glama.ai/mcp/servers/bzvl3lz34o) **Featured AI Tool**
538 | - **Production-tested** across 13+ AI applications
539 | - **Community-driven** with real-world feedback and improvements
540 |
541 | ## 📄 License
542 |
543 | Apache License 2.0 - see [LICENSE](LICENSE) for details.
544 |
545 | ---
546 |
547 | **Ready to supercharge your AI workflow?** 🚀
548 |
549 | 👉 **[Start with our Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** or explore the **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** for comprehensive documentation.
550 |
551 | *Transform your AI conversations into persistent, searchable knowledge that grows with you.*
```
--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service - Agent Guidelines
2 |
3 | ## Available Agents
4 |
5 | ### amp-bridge
6 | **Purpose**: Leverage Amp CLI capabilities (research, code analysis, web search) without consuming Claude Code credits.
7 |
8 | **Usage**: `Use @agent-amp-bridge to research XYZ`
9 |
10 | **How it works**:
11 | 1. Agent creates concise prompt in `.claude/amp/prompts/pending/{uuid}.json`
12 | 2. Shows you command: `amp @{prompt-file}`
13 | 3. You run command in your authenticated Amp session (free tier)
14 | 4. Amp writes response to `.claude/amp/responses/ready/{uuid}.json`
15 | 5. Agent detects, reads, and presents results
16 |
17 | **Key principle**: Agent creates SHORT, focused prompts (2-4 sentences) to conserve Amp credits.
18 |
19 | **Example**:
20 | - ❌ Bad: "Research TypeScript 5.0 in detail covering: 1. Const params... 2. Decorators... 3. Export modifiers..."
21 | - ✅ Good: "Research TypeScript 5.0's key new features with brief code examples."
22 |
23 | ## Build/Lint/Test Commands
24 | - **Run all tests**: `pytest tests/`
25 | - **Run single test**: `pytest tests/test_filename.py::test_function_name -v`
26 | - **Run specific test class**: `pytest tests/test_filename.py::TestClass -v`
27 | - **Run with markers**: `pytest -m "unit or integration"`
28 | - **Server startup**: `uv run memory server`
29 | - **Install dependencies**: `python scripts/installation/install.py`
30 |
31 | ## Architecture & Codebase Structure
32 | - **Main package**: `src/mcp_memory_service/` - Core MCP server implementation
33 | - **Storage backends**: `storage/` (SQLite-Vec, Cloudflare, Hybrid) implementing abstract `MemoryStorage` class
34 | - **Web interface**: `web/` - FastAPI dashboard with real-time updates via SSE
35 | - **MCP protocol**: `server.py` - Model Context Protocol implementation with async handlers
36 | - **Memory consolidation**: `consolidation/` - Autonomous memory management and deduplication
37 | - **Document ingestion**: `ingestion/` - PDF/DOCX/PPTX loaders with optional semtools integration
38 | - **CLI tools**: `cli/` - Command-line interface for server management
39 |
40 | ## Code Style Guidelines
41 | - **Imports**: Absolute imports preferred, conditional imports for optional dependencies
42 | - **Types**: Python 3.10+ type hints throughout, TypedDict for MCP responses
43 | - **Async/await**: All I/O operations use async/await pattern
44 | - **Naming**: snake_case for functions/variables, PascalCase for classes, SCREAMING_SNAKE_CASE for constants
45 | - **Error handling**: Try/except blocks with specific exceptions, logging for debugging
46 | - **Memory types**: Use 24 core types from taxonomy (note, reference, session, implementation, etc.)
47 | - **Documentation**: NumPy-style docstrings, CLAUDE.md for project conventions
48 |
49 | ## Development Rules (from CLAUDE.md)
50 | - Follow MCP protocol specification for tool schemas and responses
51 | - Implement storage backends extending abstract base class
52 | - Use semantic commit messages with conventional commit format
53 | - Test both OAuth enabled/disabled modes for web interface
54 | - Validate search endpoints: semantic, tag-based, time-based queries
55 |
```
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | We as members, contributors, and leaders pledge to make participation in our
6 | community a harassment-free experience for everyone, regardless of age, body
7 | size, visible or invisible disability, ethnicity, sex characteristics, gender
8 | identity and expression, level of experience, education, socio-economic status,
9 | nationality, personal appearance, race, caste, color, religion, or sexual
10 | identity and orientation.
11 |
12 | We pledge to act and interact in ways that contribute to an open, welcoming,
13 | diverse, inclusive, and healthy community.
14 |
15 | ## Our Standards
16 |
17 | Examples of behavior that contributes to a positive environment for our
18 | community include:
19 |
20 | * Demonstrating empathy and kindness toward other people
21 | * Being respectful of differing opinions, viewpoints, and experiences
22 | * Giving and gracefully accepting constructive feedback
23 | * Accepting responsibility and apologizing to those affected by our mistakes,
24 | and learning from the experience
25 | * Focusing on what is best not just for us as individuals, but for the overall
26 | community
27 |
28 | Examples of unacceptable behavior include:
29 |
30 | * The use of sexualized language or imagery, and sexual attention or advances of
31 | any kind
32 | * Trolling, insulting or derogatory comments, and personal or political attacks
33 | * Public or private harassment
34 | * Publishing others' private information, such as a physical or email address,
35 | without their explicit permission
36 | * Other conduct which could reasonably be considered inappropriate in a
37 | professional setting
38 |
39 | ## Enforcement Responsibilities
40 |
41 | Community leaders are responsible for clarifying and enforcing our standards of
42 | acceptable behavior and will take appropriate and fair corrective action in
43 | response to any behavior that they deem inappropriate, threatening, offensive,
44 | or harmful.
45 |
46 | Community leaders have the right and responsibility to remove, edit, or reject
47 | comments, commits, code, wiki edits, issues, and other contributions that are
48 | not aligned to this Code of Conduct, and will communicate reasons for moderation
49 | decisions when appropriate.
50 |
51 | ## Scope
52 |
53 | This Code of Conduct applies within all community spaces, and also applies when
54 | an individual is officially representing the community in public spaces.
55 | Examples of representing our community include using an official e-mail address,
56 | posting via an official social media account, or acting as an appointed
57 | representative at an online or offline event.
58 |
59 | ## Enforcement
60 |
61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
62 | reported to the community leaders responsible for enforcement via:
63 |
64 | * **GitHub Issues**: For public concerns that warrant community discussion
65 | * **GitHub Discussions**: For questions about community standards
66 | * **Direct Contact**: For sensitive matters, contact the project maintainers directly
67 |
68 | All complaints will be reviewed and investigated promptly and fairly.
69 |
70 | All community leaders are obligated to respect the privacy and security of the
71 | reporter of any incident.
72 |
73 | ## Enforcement Guidelines
74 |
75 | Community leaders will follow these Community Impact Guidelines in determining
76 | the consequences for any action they deem in violation of this Code of Conduct:
77 |
78 | ### 1. Correction
79 |
80 | **Community Impact**: Use of inappropriate language or other behavior deemed
81 | unprofessional or unwelcome in the community.
82 |
83 | **Consequence**: A private, written warning from community leaders, providing
84 | clarity around the nature of the violation and an explanation of why the
85 | behavior was inappropriate. A public apology may be requested.
86 |
87 | ### 2. Warning
88 |
89 | **Community Impact**: A violation through a single incident or series of
90 | actions.
91 |
92 | **Consequence**: A warning with consequences for continued behavior. No
93 | interaction with the people involved, including unsolicited interaction with
94 | those enforcing the Code of Conduct, for a specified period of time. This
95 | includes avoiding interactions in community spaces as well as external channels
96 | like social media. Violating these terms may lead to a temporary or permanent
97 | ban.
98 |
99 | ### 3. Temporary Ban
100 |
101 | **Community Impact**: A serious violation of community standards, including
102 | sustained inappropriate behavior.
103 |
104 | **Consequence**: A temporary ban from any sort of interaction or public
105 | communication with the community for a specified period of time. No public or
106 | private interaction with the people involved, including unsolicited interaction
107 | with those enforcing the Code of Conduct, is allowed during this period.
108 | Violating these terms may lead to a permanent ban.
109 |
110 | ### 4. Permanent Ban
111 |
112 | **Community Impact**: Demonstrating a pattern of violation of community
113 | standards, including sustained inappropriate behavior, harassment of an
114 | individual, or aggression toward or disparagement of classes of individuals.
115 |
116 | **Consequence**: A permanent ban from any sort of public interaction within the
117 | community.
118 |
119 | ## Attribution
120 |
121 | This Code of Conduct is adapted from the [Contributor Covenant][homepage],
122 | version 2.1, available at
123 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
124 |
125 | Community Impact Guidelines were inspired by
126 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
127 |
128 | For answers to common questions about this code of conduct, see the FAQ at
129 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
130 | [https://www.contributor-covenant.org/translations][translations].
131 |
132 | [homepage]: https://www.contributor-covenant.org
133 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
134 | [Mozilla CoC]: https://github.com/mozilla/diversity
135 | [FAQ]: https://www.contributor-covenant.org/faq
136 | [translations]: https://www.contributor-covenant.org/translations
137 |
```
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
```markdown
1 | # Security Policy
2 |
3 | ## Supported Versions
4 |
5 | We actively maintain and provide security updates for the following versions of MCP Memory Service:
6 |
7 | | Version | Supported | Notes |
8 | | ------- | ------------------ | ----- |
9 | | 8.x.x | :white_check_mark: | Current stable release - full support |
10 | | 7.x.x | :white_check_mark: | Previous stable - security fixes only |
11 | | < 7.0 | :x: | No longer supported |
12 |
13 | ## Reporting a Vulnerability
14 |
15 | We take the security of MCP Memory Service seriously. If you discover a security vulnerability, please report it responsibly.
16 |
17 | ### How to Report
18 |
19 | **For sensitive security issues**, please use one of these private reporting methods:
20 |
21 | 1. **GitHub Security Advisory** (Preferred):
22 | - Navigate to the [Security Advisories](https://github.com/doobidoo/mcp-memory-service/security/advisories) page
23 | - Click "Report a vulnerability"
24 | - Provide detailed information about the vulnerability
25 |
26 | 2. **Direct Contact**:
27 | - Open a GitHub Discussion with `[SECURITY]` prefix for initial contact
28 | - We'll provide a secure communication channel for details
29 |
30 | **For non-sensitive security concerns**, you may open a regular GitHub issue.
31 |
32 | ### What to Include
33 |
34 | When reporting a vulnerability, please include:
35 |
36 | 1. **Description**: Clear description of the vulnerability
37 | 2. **Impact**: Potential security impact and affected versions
38 | 3. **Reproduction**: Step-by-step instructions to reproduce the issue
39 | 4. **Environment**:
40 | - Python version
41 | - Operating system
42 | - Storage backend (SQLite-vec, Cloudflare, Hybrid)
43 | - Installation method (pip, Docker, source)
44 | 5. **Proof of Concept**: Code or commands demonstrating the vulnerability (if applicable)
45 | 6. **Suggested Fix**: Any ideas for fixing the issue (optional)
46 |
47 | ### Response Timeline
48 |
49 | We aim to respond to security reports according to the following timeline:
50 |
51 | - **Acknowledgment**: Within 48 hours of report
52 | - **Initial Assessment**: Within 5 business days
53 | - **Status Updates**: Weekly until resolved
54 | - **Fix Development**: 7-14 days for high-severity issues
55 | - **Patch Release**: As soon as fix is validated and tested
56 | - **Public Disclosure**: After patch is released (coordinated with reporter)
57 |
58 | ### Severity Classification
59 |
60 | We use the following severity levels to prioritize security issues:
61 |
62 | **Critical** 🔴
63 | - Remote code execution
64 | - Authentication bypass
65 | - Data exfiltration from other users' memories
66 | - Complete system compromise
67 |
68 | **High** 🟠
69 | - Privilege escalation
70 | - SQL injection
71 | - Cross-site scripting (XSS) in dashboard
72 | - Denial of service affecting all users
73 |
74 | **Medium** 🟡
75 | - Information disclosure (limited scope)
76 | - Cross-site request forgery (CSRF)
77 | - Local file access vulnerabilities
78 | - Resource exhaustion (single user)
79 |
80 | **Low** 🟢
81 | - Timing attacks
82 | - Security configuration issues
83 | - Low-impact information leaks
84 |
85 | ## Security Best Practices
86 |
87 | ### For Users
88 |
89 | 1. **Keep Updated**: Always use the latest stable version
90 | 2. **Secure Configuration**:
91 | - Use strong API keys (`openssl rand -base64 32`)
92 | - Enable HTTPS for HTTP server mode
93 | - Restrict network access to localhost unless needed
94 | 3. **Credential Management**:
95 | - Never commit `.env` files with credentials
96 | - Use environment variables for sensitive data
97 | - Rotate Cloudflare API tokens regularly
98 | 4. **Authentication**: Enable OAuth 2.1 for multi-user deployments
99 | 5. **Monitoring**: Review logs for suspicious activity
100 | 6. **Backups**: Regularly backup your memory database
101 |
102 | ### For Contributors
103 |
104 | 1. **Dependency Security**:
105 | - Review dependency updates for known vulnerabilities
106 | - Use `pip-audit` to scan for security issues
107 | - Keep dependencies up to date
108 | 2. **Input Validation**:
109 | - Sanitize all user input
110 | - Use parameterized queries (no string concatenation)
111 | - Validate file uploads and document ingestion
112 | 3. **Authentication & Authorization**:
113 | - Use secure session management
114 | - Implement proper access controls
115 | - Follow OAuth 2.1 security best practices
116 | 4. **Sensitive Data**:
117 | - Never log API keys, tokens, or passwords
118 | - Encrypt sensitive data at rest (user responsibility)
119 | - Use secure random number generation
120 | 5. **Code Review**: All PRs must pass security review before merge
121 |
122 | ## Known Security Considerations
123 |
124 | ### SQLite-vec Backend
125 | - **Local File Access**: Database file should have appropriate permissions (600)
126 | - **Concurrent Access**: Use proper locking to prevent corruption
127 | - **Backup Encryption**: User responsibility to encrypt backups
128 |
129 | ### Cloudflare Backend
130 | - **API Token Security**: Tokens have full account access - guard carefully
131 | - **Rate Limiting**: Cloudflare enforces rate limits (10k requests/min)
132 | - **Data Residency**: Data stored in Cloudflare's network per your account settings
133 |
134 | ### Hybrid Backend
135 | - **Synchronization**: Ensure secure sync between local and cloud storage
136 | - **Credential Exposure**: Both SQLite and Cloudflare credentials needed
137 |
138 | ### Web Dashboard
139 | - **HTTPS Recommended**: Use HTTPS in production environments
140 | - **XSS Protection**: All user input is escaped before rendering
141 | - **CSRF Protection**: Implement for state-changing operations
142 | - **Session Security**: Enable secure cookies in production
143 |
144 | ### MCP Protocol
145 | - **Local Access Only**: MCP server typically runs locally via stdin/stdout
146 | - **Process Isolation**: Each client gets isolated server process
147 | - **No Network Exposure**: By default, MCP mode has no network attack surface
148 |
149 | ## Security Updates
150 |
151 | Security patches are released as:
152 | - **Patch versions** (8.x.Y) for low/medium severity
153 | - **Minor versions** (8.X.0) for high severity requiring API changes
154 | - **Out-of-band releases** for critical vulnerabilities
155 |
156 | Security advisories are published at:
157 | - [GitHub Security Advisories](https://github.com/doobidoo/mcp-memory-service/security/advisories)
158 | - [CHANGELOG.md](CHANGELOG.md) with `[SECURITY]` tag
159 | - Release notes for affected versions
160 |
161 | ## Disclosure Policy
162 |
163 | We follow **coordinated disclosure**:
164 |
165 | 1. Vulnerability reported privately
166 | 2. We confirm and develop a fix
167 | 3. Security advisory drafted (private)
168 | 4. Patch released with security note
169 | 5. Public disclosure 7 days after patch release
170 | 6. Reporter credited (if desired)
171 |
172 | We appreciate security researchers following responsible disclosure practices and will acknowledge contributors in our security advisories.
173 |
174 | ## Security Hall of Fame
175 |
176 | We recognize security researchers who help make MCP Memory Service more secure:
177 |
178 | <!-- Security contributors will be listed here -->
179 | *No security vulnerabilities have been publicly disclosed to date.*
180 |
181 | ## Contact
182 |
183 | For security concerns that don't fit the above categories:
184 | - **General Security Questions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)
185 | - **Project Security**: See reporting instructions above
186 |
187 | ---
188 |
189 | **Last Updated**: November 2025
190 | **Policy Version**: 1.0
191 |
```