This is page 37 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
--------------------------------------------------------------------------------
/claude-hooks/install_hooks.py:
--------------------------------------------------------------------------------
```python
1 | #!/usr/bin/env python3
2 | """
3 | Unified Claude Code Memory Awareness Hooks Installer
4 | ====================================================
5 |
6 | Cross-platform installer for Claude Code memory awareness hooks with support for:
7 | - Basic memory awareness hooks (session-start, session-end)
8 | - Natural Memory Triggers v7.1.3 (intelligent automatic memory awareness)
9 | - Mid-conversation hooks for real-time memory injection
10 | - Performance optimization and CLI management tools
11 | - Smart MCP detection and DRY configuration
12 |
13 | Replaces multiple platform-specific installers with a single Python solution.
14 | Implements DRY principle by detecting and reusing existing Claude Code MCP configurations.
15 |
16 | Version: Dynamically synced with main project version
17 | """
18 |
19 | import os
20 | import sys
21 | import json
22 | import shutil
23 | import platform
24 | import argparse
25 | import subprocess
26 | from pathlib import Path
27 | from typing import Dict, List, Optional, Tuple
28 |
29 | # Dynamic version detection from main project
30 | def get_project_version() -> str:
31 | """Get version dynamically from main project."""
32 | try:
33 | # Add the src directory to the path to import version
34 | src_path = Path(__file__).parent.parent / "src"
35 | if str(src_path) not in sys.path:
36 | sys.path.insert(0, str(src_path))
37 |
38 | from mcp_memory_service import __version__
39 | return __version__
40 | except ImportError:
41 | # Fallback for standalone installations
42 | return "7.2.0"
43 |
44 |
45 | class Colors:
46 | """ANSI color codes for terminal output."""
47 | GREEN = '\033[0;32m'
48 | YELLOW = '\033[1;33m'
49 | RED = '\033[0;31m'
50 | BLUE = '\033[0;34m'
51 | CYAN = '\033[0;36m'
52 | NC = '\033[0m' # No Color
53 |
54 |
55 | class HookInstaller:
56 | """Unified hook installer for all platforms and feature levels."""
57 |
58 | # Environment type constants
59 | CLAUDE_CODE_ENV = "claude-code"
60 | STANDALONE_ENV = "standalone"
61 |
62 | def __init__(self):
63 | self.script_dir = Path(__file__).parent.absolute()
64 | self.platform_name = platform.system().lower()
65 | self.claude_hooks_dir = self._detect_claude_hooks_directory()
66 | self.backup_dir = None
67 |
68 | def _detect_claude_hooks_directory(self) -> Path:
69 | """Detect the Claude Code hooks directory across platforms."""
70 | home = Path.home()
71 |
72 | # Primary paths by platform
73 | primary_paths = {
74 | 'windows': [
75 | home / 'AppData' / 'Roaming' / 'Claude' / 'hooks',
76 | home / '.claude' / 'hooks'
77 | ],
78 | 'darwin': [ # macOS
79 | home / '.claude' / 'hooks',
80 | home / 'Library' / 'Application Support' / 'Claude' / 'hooks'
81 | ],
82 | 'linux': [
83 | home / '.claude' / 'hooks',
84 | home / '.config' / 'claude' / 'hooks'
85 | ]
86 | }
87 |
88 | # Check platform-specific paths first
89 | platform_paths = primary_paths.get(self.platform_name, primary_paths['linux'])
90 |
91 | for path in platform_paths:
92 | if path.exists():
93 | return path
94 |
95 | # Check if Claude Code CLI can tell us the location
96 | try:
97 | result = subprocess.run(['claude', '--help'],
98 | capture_output=True, text=True, timeout=5)
99 | # Look for hooks directory info in help output
100 | # This is a placeholder - actual Claude CLI might not provide this
101 | except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
102 | pass
103 |
104 | # Default to standard location
105 | return home / '.claude' / 'hooks'
106 |
107 | def info(self, message: str) -> None:
108 | """Print info message."""
109 | print(f"{Colors.GREEN}[INFO]{Colors.NC} {message}")
110 |
111 | def warn(self, message: str) -> None:
112 | """Print warning message."""
113 | print(f"{Colors.YELLOW}[WARN]{Colors.NC} {message}")
114 |
115 | def error(self, message: str) -> None:
116 | """Print error message."""
117 | print(f"{Colors.RED}[ERROR]{Colors.NC} {message}")
118 |
119 | def success(self, message: str) -> None:
120 | """Print success message."""
121 | print(f"{Colors.BLUE}[SUCCESS]{Colors.NC} {message}")
122 |
123 | def header(self, message: str) -> None:
124 | """Print header message."""
125 | print(f"\n{Colors.CYAN}{'=' * 60}{Colors.NC}")
126 | print(f"{Colors.CYAN} {message}{Colors.NC}")
127 | print(f"{Colors.CYAN}{'=' * 60}{Colors.NC}\n")
128 |
129 | def check_prerequisites(self) -> bool:
130 | """Check system prerequisites for hook installation."""
131 | self.info("Checking prerequisites...")
132 |
133 | all_good = True
134 |
135 | # Check Claude Code CLI
136 | try:
137 | result = subprocess.run(['claude', '--version'],
138 | capture_output=True, text=True, timeout=5)
139 | if result.returncode == 0:
140 | self.success(f"Claude Code CLI found: {result.stdout.strip()}")
141 | else:
142 | self.warn("Claude Code CLI found but version check failed")
143 | except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
144 | self.warn("Claude Code CLI not found in PATH")
145 | self.info("You can still install hooks, but some features may not work")
146 |
147 | # Check Node.js
148 | try:
149 | result = subprocess.run(['node', '--version'],
150 | capture_output=True, text=True, timeout=5)
151 | if result.returncode == 0:
152 | version = result.stdout.strip()
153 | major_version = int(version.replace('v', '').split('.')[0])
154 | if major_version >= 14:
155 | self.success(f"Node.js found: {version} (compatible)")
156 | else:
157 | self.error(f"Node.js {version} found, but version 14+ required")
158 | all_good = False
159 | else:
160 | self.error("Node.js found but version check failed")
161 | all_good = False
162 | except (subprocess.SubprocessError, FileNotFoundError, subprocess.TimeoutExpired):
163 | self.error("Node.js not found - required for hook execution")
164 | self.info("Please install Node.js 14+ from https://nodejs.org/")
165 | all_good = False
166 |
167 | # Check Python version
168 | if sys.version_info < (3, 7):
169 | self.error(f"Python {sys.version} found, but Python 3.7+ required")
170 | all_good = False
171 | else:
172 | self.success(f"Python {sys.version_info.major}.{sys.version_info.minor} found (compatible)")
173 |
174 | return all_good
175 |
176 | def detect_claude_mcp_configuration(self) -> Optional[Dict]:
177 | """Detect existing Claude Code MCP memory server configuration."""
178 | self.info("Detecting existing Claude Code MCP configuration...")
179 |
180 | try:
181 | # Check if memory server is configured in Claude Code
182 | result = subprocess.run(['claude', 'mcp', 'get', 'memory'],
183 | capture_output=True, text=True, timeout=10)
184 |
185 | if result.returncode == 0:
186 | # Parse the output to extract configuration details
187 | config_info = self._parse_mcp_get_output(result.stdout)
188 | if config_info:
189 | self.success(f"Found existing memory server: {config_info.get('command', 'Unknown')}")
190 | self.success(f"Status: {config_info.get('status', 'Unknown')}")
191 | self.success(f"Type: {config_info.get('type', 'Unknown')}")
192 | return config_info
193 | else:
194 | self.warn("Memory server found but configuration could not be parsed")
195 | else:
196 | self.info("No existing memory server found in Claude Code MCP configuration")
197 |
198 | except subprocess.TimeoutExpired:
199 | self.warn("Claude MCP command timed out")
200 | except FileNotFoundError:
201 | self.warn("Claude Code CLI not found - cannot detect existing MCP configuration")
202 | except Exception as e:
203 | self.warn(f"Failed to detect MCP configuration: {e}")
204 |
205 | return None
206 |
207 | def _parse_mcp_get_output(self, output: str) -> Optional[Dict]:
208 | """Parse the output of 'claude mcp get memory' command."""
209 | config = {}
210 |
211 | try:
212 | lines = output.strip().split('\n')
213 | for line in lines:
214 | line = line.strip()
215 | if line.startswith('Status:'):
216 | config['status'] = line.replace('Status:', '').strip()
217 | elif line.startswith('Type:'):
218 | config['type'] = line.replace('Type:', '').strip()
219 | elif line.startswith('Command:'):
220 | config['command'] = line.replace('Command:', '').strip()
221 | elif line.startswith('Scope:'):
222 | config['scope'] = line.replace('Scope:', '').strip()
223 | elif line.startswith('Environment:'):
224 | config['environment'] = line.replace('Environment:', '').strip()
225 |
226 | # Only return config if we found essential information
227 | if 'command' in config and 'status' in config:
228 | return config
229 |
230 | except Exception as e:
231 | self.warn(f"Failed to parse MCP output: {e}")
232 |
233 | return None
234 |
235 | def detect_environment_type(self) -> str:
236 | """Detect if running in Claude Code vs standalone environment."""
237 | self.info("Detecting environment type...")
238 |
239 | # Check for Claude Code MCP server (indicates Claude Code is active)
240 | mcp_config = self.detect_claude_mcp_configuration()
241 |
242 | if mcp_config and 'Connected' in mcp_config.get('status', ''):
243 | self.success("Claude Code environment detected (MCP server active)")
244 | return self.CLAUDE_CODE_ENV
245 | else:
246 | self.success("Standalone environment detected (no active MCP server)")
247 | return self.STANDALONE_ENV
248 |
249 | def _detect_python_path(self) -> str:
250 | """Detect the appropriate Python executable path for the current platform.
251 |
252 | Returns:
253 | str: Python executable name/path ('python3' for Unix, 'python' for Windows)
254 | """
255 | import sys
256 | import platform
257 |
258 | # Check Python version (must be 3.10+)
259 | if sys.version_info < (3, 10):
260 | self.warn(f"Python {sys.version_info.major}.{sys.version_info.minor} detected - code execution requires 3.10+")
261 |
262 | # Platform-specific Python path
263 | if platform.system() == 'Windows':
264 | return 'python'
265 | else:
266 | return 'python3'
267 |
268 | def configure_protocol_for_environment(self, env_type: str) -> Dict:
269 | """Configure optimal protocol based on detected environment."""
270 | # Data-driven configuration map
271 | config_map = {
272 | self.CLAUDE_CODE_ENV: {
273 | "protocol": "http",
274 | "preferredProtocol": "http",
275 | "fallbackEnabled": True,
276 | "reason": "Claude Code environment - using HTTP to avoid MCP conflicts",
277 | "log_title": "📋 Protocol Configuration: HTTP (recommended for Claude Code)",
278 | "log_reason": "Avoids MCP server conflicts when Claude Code is active"
279 | },
280 | self.STANDALONE_ENV: {
281 | "protocol": "auto",
282 | "preferredProtocol": "mcp",
283 | "fallbackEnabled": True,
284 | "reason": "Standalone environment - MCP preferred for performance",
285 | "log_title": "📋 Protocol Configuration: Auto (MCP preferred)",
286 | "log_reason": "MCP provides best performance in standalone scenarios"
287 | }
288 | }
289 |
290 | # Get configuration for environment type (default to standalone if unknown)
291 | config = config_map.get(env_type, config_map[self.STANDALONE_ENV])
292 |
293 | # Log the configuration
294 | self.info(config["log_title"])
295 | self.info(f" Reason: {config['log_reason']}")
296 |
297 | # Return only the protocol configuration (excluding logging fields)
298 | return {
299 | "protocol": config["protocol"],
300 | "preferredProtocol": config["preferredProtocol"],
301 | "fallbackEnabled": config["fallbackEnabled"],
302 | "reason": config["reason"]
303 | }
304 |
305 | def validate_mcp_prerequisites(self, detected_config: Optional[Dict] = None) -> Tuple[bool, List[str]]:
306 | """Validate that MCP memory service is properly configured."""
307 | issues = []
308 |
309 | if not detected_config:
310 | detected_config = self.detect_claude_mcp_configuration()
311 |
312 | if not detected_config:
313 | issues.append("No memory server found in Claude Code MCP configuration")
314 | return False, issues
315 |
316 | # Check if server is connected
317 | status = detected_config.get('status', '')
318 | if '✓ Connected' not in status and 'Connected' not in status:
319 | issues.append(f"Memory server is not connected. Status: {status}")
320 |
321 | # Validate command format
322 | command = detected_config.get('command', '')
323 | if not command:
324 | issues.append("Memory server command is empty")
325 | elif 'mcp_memory_service' not in command:
326 | issues.append(f"Unexpected memory server command: {command}")
327 |
328 | # Check server type
329 | server_type = detected_config.get('type', '')
330 | if server_type not in ['stdio', 'http']:
331 | issues.append(f"Unsupported server type: {server_type}")
332 |
333 | return len(issues) == 0, issues
334 |
335 | def generate_hooks_config_from_mcp(self, detected_config: Dict, env_type: str = "standalone") -> Dict:
336 | """Generate hooks configuration based on detected Claude Code MCP setup.
337 |
338 | Args:
339 | detected_config: Dictionary containing detected MCP configuration
340 | env_type: Environment type ('claude-code' or 'standalone'), defaults to 'standalone'
341 |
342 | Returns:
343 | Dictionary containing complete hooks configuration
344 | """
345 | command = detected_config.get('command', '')
346 | server_type = detected_config.get('type', 'stdio')
347 |
348 | # Get environment-appropriate protocol configuration
349 | protocol_config = self.configure_protocol_for_environment(env_type)
350 |
351 | if server_type == 'stdio':
352 | # For stdio servers, we'll reference the existing server
353 | mcp_config = {
354 | "useExistingServer": True,
355 | "serverName": "memory",
356 | "connectionTimeout": 5000,
357 | "toolCallTimeout": 10000
358 | }
359 | else:
360 | # For HTTP servers, extract endpoint information
361 | mcp_config = {
362 | "useExistingServer": True,
363 | "serverName": "memory",
364 | "connectionTimeout": 5000,
365 | "toolCallTimeout": 10000
366 | }
367 |
368 | # Detect Python path based on platform
369 | python_path = self._detect_python_path()
370 |
371 | config = {
372 | "codeExecution": {
373 | "enabled": True,
374 | "timeout": 8000,
375 | "fallbackToMCP": True,
376 | "enableMetrics": True,
377 | "pythonPath": python_path
378 | },
379 | "memoryService": {
380 | "protocol": protocol_config["protocol"],
381 | "preferredProtocol": protocol_config["preferredProtocol"],
382 | "fallbackEnabled": protocol_config["fallbackEnabled"],
383 | "http": {
384 | "endpoint": "https://localhost:8443",
385 | "apiKey": "auto-detect",
386 | "healthCheckTimeout": 3000,
387 | "useDetailedHealthCheck": True
388 | },
389 | "mcp": mcp_config,
390 | "defaultTags": ["claude-code", "auto-generated"],
391 | "maxMemoriesPerSession": 8,
392 | "enableSessionConsolidation": True,
393 | "injectAfterCompacting": False,
394 | "recentFirstMode": True,
395 | "recentMemoryRatio": 0.6,
396 | "recentTimeWindow": "last-week",
397 | "fallbackTimeWindow": "last-month",
398 | "showStorageSource": True,
399 | "sourceDisplayMode": "brief"
400 | }
401 | }
402 |
403 | return config
404 |
405 | def generate_basic_config(self, env_type: str = "standalone") -> Dict:
406 | """Generate basic configuration when no template is available.
407 |
408 | Args:
409 | env_type: Environment type ('claude-code' or 'standalone'), defaults to 'standalone'
410 |
411 | Returns:
412 | Dictionary containing basic hooks configuration
413 | """
414 | # Get environment-appropriate protocol configuration
415 | protocol_config = self.configure_protocol_for_environment(env_type)
416 |
417 | # Detect Python path based on platform
418 | python_path = self._detect_python_path()
419 |
420 | return {
421 | "codeExecution": {
422 | "enabled": True,
423 | "timeout": 8000,
424 | "fallbackToMCP": True,
425 | "enableMetrics": True,
426 | "pythonPath": python_path
427 | },
428 | "memoryService": {
429 | "protocol": protocol_config["protocol"],
430 | "preferredProtocol": protocol_config["preferredProtocol"],
431 | "fallbackEnabled": protocol_config["fallbackEnabled"],
432 | "http": {
433 | "endpoint": "https://localhost:8443",
434 | "apiKey": "auto-detect",
435 | "healthCheckTimeout": 3000,
436 | "useDetailedHealthCheck": True
437 | },
438 | "mcp": {
439 | "serverCommand": ["uv", "run", "python", "-m", "mcp_memory_service.server"],
440 | "serverWorkingDir": str(self.script_dir.parent),
441 | "connectionTimeout": 5000,
442 | "toolCallTimeout": 10000
443 | },
444 | "defaultTags": ["claude-code", "auto-generated"],
445 | "maxMemoriesPerSession": 8,
446 | "enableSessionConsolidation": True,
447 | "injectAfterCompacting": False,
448 | "recentFirstMode": True,
449 | "recentMemoryRatio": 0.6,
450 | "recentTimeWindow": "last-week",
451 | "fallbackTimeWindow": "last-month",
452 | "showStorageSource": True,
453 | "sourceDisplayMode": "brief"
454 | },
455 | "projectDetection": {
456 | "gitRepository": True,
457 | "packageFiles": ["package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml"],
458 | "frameworkDetection": True,
459 | "languageDetection": True,
460 | "confidenceThreshold": 0.3
461 | },
462 | "output": {
463 | "verbose": True,
464 | "showMemoryDetails": True,
465 | "showProjectDetails": True,
466 | "cleanMode": False
467 | }
468 | }
469 |
470 | def enhance_config_for_natural_triggers(self, config: Dict) -> Dict:
471 | """Enhance configuration with Natural Memory Triggers settings."""
472 | # Add natural triggers configuration
473 | config["naturalTriggers"] = {
474 | "enabled": True,
475 | "triggerThreshold": 0.6,
476 | "cooldownPeriod": 30000,
477 | "maxMemoriesPerTrigger": 5
478 | }
479 |
480 | # Add performance configuration
481 | config["performance"] = {
482 | "defaultProfile": "balanced",
483 | "enableMonitoring": True,
484 | "autoAdjust": True,
485 | "profiles": {
486 | "speed_focused": {
487 | "maxLatency": 100,
488 | "enabledTiers": ["instant"],
489 | "backgroundProcessing": False,
490 | "degradeThreshold": 200,
491 | "description": "Fastest response, minimal memory awareness"
492 | },
493 | "balanced": {
494 | "maxLatency": 200,
495 | "enabledTiers": ["instant", "fast"],
496 | "backgroundProcessing": True,
497 | "degradeThreshold": 400,
498 | "description": "Moderate latency, smart memory triggers"
499 | },
500 | "memory_aware": {
501 | "maxLatency": 500,
502 | "enabledTiers": ["instant", "fast", "intensive"],
503 | "backgroundProcessing": True,
504 | "degradeThreshold": 1000,
505 | "description": "Full memory awareness, accept higher latency"
506 | }
507 | }
508 | }
509 |
510 | # Add other advanced settings
511 | config["gitAnalysis"] = {
512 | "enabled": True,
513 | "commitLookback": 14,
514 | "maxCommits": 20,
515 | "includeChangelog": True,
516 | "maxGitMemories": 3,
517 | "gitContextWeight": 1.2
518 | }
519 |
520 | return config
521 |
522 | def create_backup(self) -> None:
523 | """Create backup of existing hooks installation."""
524 | if not self.claude_hooks_dir.exists():
525 | self.info("No existing hooks installation found - no backup needed")
526 | return
527 |
528 | timestamp = subprocess.run(['date', '+%Y%m%d-%H%M%S'],
529 | capture_output=True, text=True).stdout.strip()
530 | if not timestamp: # Fallback for Windows
531 | import datetime
532 | timestamp = datetime.datetime.now().strftime('%Y%m%d-%H%M%S')
533 |
534 | self.backup_dir = self.claude_hooks_dir.parent / f"hooks-backup-{timestamp}"
535 |
536 | try:
537 | shutil.copytree(self.claude_hooks_dir, self.backup_dir)
538 | self.success(f"Backup created: {self.backup_dir}")
539 | except Exception as e:
540 | self.warn(f"Failed to create backup: {e}")
541 | self.warn("Continuing without backup...")
542 |
543 | def install_basic_hooks(self) -> bool:
544 | """Install basic memory awareness hooks."""
545 | self.info("Installing basic memory awareness hooks...")
546 |
547 | try:
548 | # Create necessary directories
549 | (self.claude_hooks_dir / "core").mkdir(parents=True, exist_ok=True)
550 | (self.claude_hooks_dir / "utilities").mkdir(parents=True, exist_ok=True)
551 | (self.claude_hooks_dir / "tests").mkdir(parents=True, exist_ok=True)
552 |
553 | # Core hooks
554 | core_files = [
555 | "session-start.js",
556 | "session-end.js",
557 | "memory-retrieval.js",
558 | "topic-change.js"
559 | ]
560 |
561 | for file in core_files:
562 | src = self.script_dir / "core" / file
563 | dst = self.claude_hooks_dir / "core" / file
564 | if src.exists():
565 | shutil.copy2(src, dst)
566 | else:
567 | self.warn(f"Core file not found: {file}")
568 |
569 | # Copy ALL utility files to ensure updates are deployed
570 | # This prevents stale versions when files are updated in the repo
571 | utilities_dir = self.script_dir / "utilities"
572 | if utilities_dir.exists():
573 | utility_count = 0
574 | for utility_file in utilities_dir.glob("*.js"):
575 | dst = self.claude_hooks_dir / "utilities" / utility_file.name
576 | shutil.copy2(utility_file, dst)
577 | utility_count += 1
578 | self.success(f"Copied {utility_count} utility files")
579 | else:
580 | self.warn("Utilities directory not found")
581 |
582 | # Tests
583 | test_files = ["integration-test.js"]
584 | for file in test_files:
585 | src = self.script_dir / "tests" / file
586 | dst = self.claude_hooks_dir / "tests" / file
587 | if src.exists():
588 | shutil.copy2(src, dst)
589 |
590 | # Documentation
591 | readme_src = self.script_dir / "README.md"
592 | if readme_src.exists():
593 | shutil.copy2(readme_src, self.claude_hooks_dir / "README.md")
594 |
595 | # StatusLine script (v8.5.7+)
596 | statusline_src = self.script_dir / "statusline.sh"
597 | if statusline_src.exists():
598 | statusline_dst = self.claude_hooks_dir / "statusline.sh"
599 | shutil.copy2(statusline_src, statusline_dst)
600 | # Make executable on Unix-like systems
601 | if self.platform_name != 'windows':
602 | os.chmod(statusline_dst, 0o755)
603 | self.success("StatusLine script installed")
604 |
605 | # Check for jq dependency
606 | jq_available = shutil.which('jq') is not None
607 | if jq_available:
608 | self.success("✓ jq is installed (required for statusLine)")
609 | else:
610 | self.warn("⚠ jq not found - statusLine requires jq for JSON parsing")
611 | self.info(" Install jq:")
612 | if self.platform_name == 'darwin':
613 | self.info(" macOS: brew install jq")
614 | elif self.platform_name == 'linux':
615 | self.info(" Linux: sudo apt install jq (or equivalent)")
616 | elif self.platform_name == 'windows':
617 | self.info(" Windows: choco install jq (or download from https://jqlang.github.io/jq/)")
618 |
619 | self.success("Basic hooks installed successfully")
620 | return True
621 |
622 | except Exception as e:
623 | self.error(f"Failed to install basic hooks: {e}")
624 | return False
625 |
626 | def install_natural_triggers(self) -> bool:
627 | """Install Natural Memory Triggers v7.1.3 components."""
628 | self.info("Installing Natural Memory Triggers v7.1.3...")
629 |
630 | try:
631 | # Ensure directories exist
632 | (self.claude_hooks_dir / "core").mkdir(parents=True, exist_ok=True)
633 | (self.claude_hooks_dir / "utilities").mkdir(parents=True, exist_ok=True)
634 |
635 | # Mid-conversation hook
636 | mid_conv_src = self.script_dir / "core" / "mid-conversation.js"
637 | if mid_conv_src.exists():
638 | shutil.copy2(mid_conv_src, self.claude_hooks_dir / "core" / "mid-conversation.js")
639 | self.success("Installed mid-conversation hooks")
640 | else:
641 | self.warn("Mid-conversation hook not found")
642 |
643 | # CRITICAL: Copy ALL utility files to ensure updates are deployed
644 | # This prevents the issue where updated files like memory-scorer.js don't get copied
645 | utilities_dir = self.script_dir / "utilities"
646 | if utilities_dir.exists():
647 | utility_count = 0
648 | for utility_file in utilities_dir.glob("*.js"):
649 | dst = self.claude_hooks_dir / "utilities" / utility_file.name
650 | shutil.copy2(utility_file, dst)
651 | utility_count += 1
652 | self.success(f"Copied {utility_count} utility files (ensuring all updates are deployed)")
653 | else:
654 | self.warn("Utilities directory not found")
655 |
656 | # CLI management tools
657 | cli_tools = [
658 | "memory-mode-controller.js",
659 | "debug-pattern-test.js"
660 | ]
661 |
662 | for file in cli_tools:
663 | src = self.script_dir / file
664 | dst = self.claude_hooks_dir / file
665 | if src.exists():
666 | shutil.copy2(src, dst)
667 |
668 | # Test files
669 | test_files = [
670 | "test-natural-triggers.js",
671 | "test-mcp-hook.js",
672 | "test-dual-protocol-hook.js"
673 | ]
674 |
675 | for file in test_files:
676 | src = self.script_dir / file
677 | dst = self.claude_hooks_dir / file
678 | if src.exists():
679 | shutil.copy2(src, dst)
680 |
681 | self.success("Natural Memory Triggers v7.1.3 installed successfully")
682 | return True
683 |
684 | except Exception as e:
685 | self.error(f"Failed to install Natural Memory Triggers: {e}")
686 | return False
687 |
688 | def install_configuration(self, install_natural_triggers: bool = False, detected_mcp: Optional[Dict] = None, env_type: str = "standalone") -> bool:
689 | """Install or update configuration files.
690 |
691 | Args:
692 | install_natural_triggers: Whether to include Natural Memory Triggers configuration
693 | detected_mcp: Optional detected MCP configuration to use
694 | env_type: Environment type ('claude-code' or 'standalone'), defaults to 'standalone'
695 |
696 | Returns:
697 | True if installation successful, False otherwise
698 | """
699 | self.info("Installing configuration...")
700 |
701 | try:
702 | # Install template configuration
703 | template_src = self.script_dir / "config.template.json"
704 | template_dst = self.claude_hooks_dir / "config.template.json"
705 | if template_src.exists():
706 | shutil.copy2(template_src, template_dst)
707 |
708 | # Install main configuration
709 | config_src = self.script_dir / "config.json"
710 | config_dst = self.claude_hooks_dir / "config.json"
711 |
712 | if config_dst.exists():
713 | # Backup existing config
714 | backup_config = config_dst.with_suffix('.json.backup')
715 | shutil.copy2(config_dst, backup_config)
716 | self.info("Existing configuration backed up")
717 |
718 | # Generate configuration based on detected MCP or fallback to template
719 | try:
720 | if detected_mcp:
721 | # Use smart configuration generation for existing MCP
722 | config = self.generate_hooks_config_from_mcp(detected_mcp, env_type)
723 | self.success("Generated configuration based on detected MCP setup")
724 | elif config_src.exists():
725 | # Use template configuration and update paths
726 | with open(config_src, 'r') as f:
727 | config = json.load(f)
728 |
729 | # Update server working directory path for independent setup
730 | if 'memoryService' in config and 'mcp' in config['memoryService']:
731 | config['memoryService']['mcp']['serverWorkingDir'] = str(self.script_dir.parent)
732 |
733 | self.success("Generated configuration using template with updated paths")
734 | else:
735 | # Generate basic configuration
736 | config = self.generate_basic_config(env_type)
737 | self.success("Generated basic configuration")
738 |
739 | # Add additional configuration based on installation options
740 | if install_natural_triggers:
741 | config = self.enhance_config_for_natural_triggers(config)
742 |
743 | # Write the final configuration
744 | with open(config_dst, 'w') as f:
745 | json.dump(config, f, indent=2)
746 |
747 | self.success("Configuration installed successfully")
748 |
749 | except Exception as e:
750 | self.warn(f"Failed to generate configuration: {e}")
751 | # Fallback to template copy if available
752 | if config_src.exists():
753 | shutil.copy2(config_src, config_dst)
754 | self.warn("Fell back to template configuration")
755 |
756 | return True
757 |
758 | except Exception as e:
759 | self.error(f"Failed to install configuration: {e}")
760 | return False
761 |
762 | def configure_claude_settings(self, install_mid_conversation: bool = False) -> bool:
763 | """Configure Claude Code settings.json for hook integration."""
764 | self.info("Configuring Claude Code settings...")
765 |
766 | try:
767 | # Determine settings path based on platform
768 | home = Path.home()
769 | if self.platform_name == 'windows':
770 | settings_dir = home / 'AppData' / 'Roaming' / 'Claude'
771 | else:
772 | settings_dir = home / '.claude'
773 |
774 | settings_dir.mkdir(parents=True, exist_ok=True)
775 | settings_file = settings_dir / 'settings.json'
776 |
777 | # Windows-specific warning for SessionStart hooks (issue #160)
778 | skip_session_start = False
779 | if self.platform_name == 'windows':
780 | self.warn("⚠️ Windows Platform Detected - SessionStart Hook Limitation")
781 | self.warn("SessionStart hooks cause Claude Code to hang on Windows (issue #160)")
782 | self.warn("Workaround: Use '/session-start' slash command instead")
783 | self.info("Skipping SessionStart hook configuration for Windows")
784 | self.info("See: https://github.com/doobidoo/mcp-memory-service/issues/160")
785 | skip_session_start = True
786 |
787 | # Create hook configuration
788 | hook_config = {
789 | "hooks": {}
790 | }
791 |
792 | # Add SessionStart only on non-Windows platforms
793 | if not skip_session_start:
794 | hook_config["hooks"]["SessionStart"] = [
795 | {
796 | "hooks": [
797 | {
798 | "type": "command",
799 | "command": f'node "{self.claude_hooks_dir}/core/session-start.js"',
800 | "timeout": 10
801 | }
802 | ]
803 | }
804 | ]
805 |
806 | # SessionEnd works on all platforms
807 | hook_config["hooks"]["SessionEnd"] = [
808 | {
809 | "hooks": [
810 | {
811 | "type": "command",
812 | "command": f'node "{self.claude_hooks_dir}/core/session-end.js"',
813 | "timeout": 15
814 | }
815 | ]
816 | }
817 | ]
818 |
819 | # Add mid-conversation hook if Natural Memory Triggers are installed
820 | if install_mid_conversation:
821 | hook_config["hooks"]["UserPromptSubmit"] = [
822 | {
823 | "hooks": [
824 | {
825 | "type": "command",
826 | "command": f'node "{self.claude_hooks_dir}/core/mid-conversation.js"',
827 | "timeout": 8
828 | }
829 | ]
830 | }
831 | ]
832 |
833 | # Add statusLine configuration for v8.5.7+ (Unix/Linux/macOS only - requires bash)
834 | statusline_script = self.claude_hooks_dir / 'statusline.sh'
835 | if statusline_script.exists() and self.platform_name != 'windows':
836 | hook_config["statusLine"] = {
837 | "type": "command",
838 | "command": str(statusline_script),
839 | "padding": 0
840 | }
841 | self.info("Added statusLine configuration for memory awareness display")
842 | elif statusline_script.exists() and self.platform_name == 'windows':
843 | self.info("Skipping statusLine (requires bash - not available on Windows)")
844 |
845 | # Handle existing settings with intelligent merging
846 | final_config = hook_config
847 | if settings_file.exists():
848 | # Backup existing settings
849 | backup_settings = settings_file.with_suffix('.json.backup')
850 | shutil.copy2(settings_file, backup_settings)
851 | self.info("Existing settings.json backed up")
852 |
853 | try:
854 | # Load existing settings
855 | with open(settings_file, 'r') as f:
856 | existing_settings = json.load(f)
857 |
858 | # Intelligent merging: preserve existing hooks while adding/updating memory awareness hooks
859 | if 'hooks' not in existing_settings:
860 | existing_settings['hooks'] = {}
861 |
862 | # Check for conflicts and merge intelligently
863 | memory_hook_types = {'SessionStart', 'SessionEnd', 'UserPromptSubmit'}
864 | conflicts = []
865 |
866 | for hook_type in memory_hook_types:
867 | if hook_type in existing_settings['hooks'] and hook_type in hook_config['hooks']:
868 | # Check if existing hook is different from our memory awareness hook
869 | existing_commands = [
870 | hook.get('command', '') for hooks_group in existing_settings['hooks'][hook_type]
871 | for hook in hooks_group.get('hooks', [])
872 | ]
873 | memory_commands = [
874 | hook.get('command', '') for hooks_group in hook_config['hooks'][hook_type]
875 | for hook in hooks_group.get('hooks', [])
876 | ]
877 |
878 | # Check if any existing command contains memory hook
879 | is_memory_hook = any('session-start.js' in cmd or 'session-end.js' in cmd or 'mid-conversation.js' in cmd
880 | for cmd in existing_commands)
881 |
882 | if not is_memory_hook:
883 | conflicts.append(hook_type)
884 |
885 | if conflicts:
886 | self.warn(f"Found existing non-memory hooks for: {', '.join(conflicts)}")
887 | self.warn("Memory awareness hooks will be added alongside existing hooks")
888 |
889 | # Add memory hooks alongside existing ones
890 | for hook_type in hook_config['hooks']:
891 | if hook_type in existing_settings['hooks']:
892 | existing_settings['hooks'][hook_type].extend(hook_config['hooks'][hook_type])
893 | else:
894 | existing_settings['hooks'][hook_type] = hook_config['hooks'][hook_type]
895 | else:
896 | # No conflicts, safe to update memory awareness hooks
897 | existing_settings['hooks'].update(hook_config['hooks'])
898 | self.info("Updated memory awareness hooks without conflicts")
899 |
900 | final_config = existing_settings
901 | self.success("Settings merged intelligently, preserving existing configuration")
902 |
903 | except json.JSONDecodeError as e:
904 | self.warn(f"Existing settings.json invalid, using backup and creating new: {e}")
905 | final_config = hook_config
906 | except Exception as e:
907 | self.warn(f"Error merging settings, creating new configuration: {e}")
908 | final_config = hook_config
909 |
910 | # Write final configuration
911 | with open(settings_file, 'w') as f:
912 | json.dump(final_config, f, indent=2)
913 |
914 | self.success("Claude Code settings configured successfully")
915 | return True
916 |
917 | except Exception as e:
918 | self.error(f"Failed to configure Claude Code settings: {e}")
919 | return False
920 |
921 | def run_tests(self, test_natural_triggers: bool = False) -> bool:
922 | """Run hook tests to verify installation."""
923 | self.info("Running installation tests...")
924 |
925 | success = True
926 |
927 | # Check required files exist
928 | required_files = [
929 | "core/session-start.js",
930 | "core/session-end.js",
931 | "utilities/project-detector.js",
932 | "utilities/memory-scorer.js",
933 | "utilities/context-formatter.js",
934 | "config.json"
935 | ]
936 |
937 | if test_natural_triggers:
938 | required_files.extend([
939 | "core/mid-conversation.js",
940 | "utilities/adaptive-pattern-detector.js",
941 | "utilities/performance-manager.js",
942 | "utilities/mcp-client.js"
943 | ])
944 |
945 | missing_files = []
946 | for file in required_files:
947 | if not (self.claude_hooks_dir / file).exists():
948 | missing_files.append(file)
949 |
950 | if missing_files:
951 | self.error("Installation incomplete - missing files:")
952 | for file in missing_files:
953 | self.error(f" - {file}")
954 | success = False
955 | else:
956 | self.success("All required files installed correctly")
957 |
958 | # Test Node.js execution
959 | test_script = self.claude_hooks_dir / "core" / "session-start.js"
960 | if test_script.exists():
961 | try:
962 | result = subprocess.run(['node', '--check', str(test_script)],
963 | capture_output=True, text=True, timeout=10)
964 | if result.returncode == 0:
965 | self.success("Hook JavaScript syntax validation passed")
966 | else:
967 | self.error(f"Hook JavaScript syntax validation failed: {result.stderr}")
968 | success = False
969 | except Exception as e:
970 | self.warn(f"Could not validate JavaScript syntax: {e}")
971 |
972 | # Run integration tests if available
973 | integration_test = self.claude_hooks_dir / "tests" / "integration-test.js"
974 | if integration_test.exists():
975 | try:
976 | self.info("Running integration tests...")
977 | result = subprocess.run(['node', str(integration_test)],
978 | capture_output=True, text=True,
979 | timeout=30, cwd=str(self.claude_hooks_dir))
980 | if result.returncode == 0:
981 | self.success("Integration tests passed")
982 | else:
983 | self.warn("Some integration tests failed - check configuration")
984 | if result.stdout:
985 | self.info(f"Test output: {result.stdout}")
986 | except Exception as e:
987 | self.warn(f"Could not run integration tests: {e}")
988 |
989 | # Run Natural Memory Triggers tests if applicable
990 | if test_natural_triggers:
991 | natural_test = self.claude_hooks_dir / "test-natural-triggers.js"
992 | if natural_test.exists():
993 | try:
994 | self.info("Running Natural Memory Triggers tests...")
995 | result = subprocess.run(['node', str(natural_test)],
996 | capture_output=True, text=True,
997 | timeout=30, cwd=str(self.claude_hooks_dir))
998 | if result.returncode == 0:
999 | self.success("Natural Memory Triggers tests passed")
1000 | else:
1001 | self.warn("Some Natural Memory Triggers tests failed")
1002 | except Exception as e:
1003 | self.warn(f"Could not run Natural Memory Triggers tests: {e}")
1004 |
1005 | return success
1006 |
1007 | def _cleanup_empty_directories(self) -> None:
1008 | """Remove empty directories after uninstall."""
1009 | try:
1010 | # Directories to check for cleanup (in reverse order to handle nested structure)
1011 | directories_to_check = [
1012 | self.claude_hooks_dir / "core",
1013 | self.claude_hooks_dir / "utilities",
1014 | self.claude_hooks_dir / "tests"
1015 | ]
1016 |
1017 | for directory in directories_to_check:
1018 | if directory.exists() and directory.is_dir():
1019 | try:
1020 | # Check if directory is empty (no files, only empty subdirectories allowed)
1021 | items = list(directory.iterdir())
1022 | if not items:
1023 | # Directory is completely empty
1024 | directory.rmdir()
1025 | self.info(f"Removed empty directory: {directory.name}/")
1026 | else:
1027 | # Check if it only contains empty subdirectories
1028 | all_empty = True
1029 | for item in items:
1030 | if item.is_file():
1031 | all_empty = False
1032 | break
1033 | elif item.is_dir() and list(item.iterdir()):
1034 | all_empty = False
1035 | break
1036 |
1037 | if all_empty:
1038 | # Remove empty subdirectories first
1039 | for item in items:
1040 | if item.is_dir():
1041 | item.rmdir()
1042 | # Then remove the parent directory
1043 | directory.rmdir()
1044 | self.info(f"Removed empty directory tree: {directory.name}/")
1045 | except OSError:
1046 | # Directory not empty or permission issue, skip silently
1047 | pass
1048 |
1049 | except Exception as e:
1050 | self.warn(f"Could not cleanup empty directories: {e}")
1051 |
1052 | def uninstall(self) -> bool:
1053 | """Remove installed hooks."""
1054 | self.info("Uninstalling Claude Code memory awareness hooks...")
1055 |
1056 | try:
1057 | if not self.claude_hooks_dir.exists():
1058 | self.info("No hooks installation found")
1059 | return True
1060 |
1061 | # Remove hook files
1062 | files_to_remove = [
1063 | "core/session-start.js",
1064 | "core/session-end.js",
1065 | "core/mid-conversation.js",
1066 | "core/memory-retrieval.js",
1067 | "core/topic-change.js",
1068 | "memory-mode-controller.js",
1069 | "test-natural-triggers.js",
1070 | "test-mcp-hook.js",
1071 | "debug-pattern-test.js"
1072 | ]
1073 |
1074 | # Remove utilities
1075 | utility_files = [
1076 | "utilities/adaptive-pattern-detector.js",
1077 | "utilities/performance-manager.js",
1078 | "utilities/mcp-client.js",
1079 | "utilities/memory-client.js",
1080 | "utilities/tiered-conversation-monitor.js"
1081 | ]
1082 | files_to_remove.extend(utility_files)
1083 |
1084 | removed_count = 0
1085 | for file in files_to_remove:
1086 | file_path = self.claude_hooks_dir / file
1087 | if file_path.exists():
1088 | file_path.unlink()
1089 | removed_count += 1
1090 |
1091 | # Remove config files if user confirms
1092 | config_file = self.claude_hooks_dir / "config.json"
1093 | if config_file.exists():
1094 | # We'll keep config files by default since they may have user customizations
1095 | self.info("Configuration files preserved (contains user customizations)")
1096 |
1097 | # Clean up empty directories
1098 | self._cleanup_empty_directories()
1099 |
1100 | self.success(f"Removed {removed_count} hook files and cleaned up empty directories")
1101 | return True
1102 |
1103 | except Exception as e:
1104 | self.error(f"Failed to uninstall hooks: {e}")
1105 | return False
1106 |
1107 |
1108 | def main():
1109 | """Main installer function."""
1110 | parser = argparse.ArgumentParser(
1111 | description="Unified Claude Code Memory Awareness Hooks Installer",
1112 | formatter_class=argparse.RawDescriptionHelpFormatter,
1113 | epilog="""
1114 | Examples:
1115 | python install_hooks.py # Install all features (default)
1116 | python install_hooks.py --basic # Basic hooks only
1117 | python install_hooks.py --natural-triggers # Natural Memory Triggers only
1118 | python install_hooks.py --test # Run tests only
1119 | python install_hooks.py --uninstall # Remove hooks
1120 |
1121 | Features:
1122 | Basic: Session-start and session-end hooks for memory awareness
1123 | Natural Triggers: v7.1.3 intelligent automatic memory awareness with
1124 | pattern detection, performance optimization, and CLI tools
1125 | """
1126 | )
1127 |
1128 | parser.add_argument('--basic', action='store_true',
1129 | help='Install basic memory awareness hooks only')
1130 | parser.add_argument('--natural-triggers', action='store_true',
1131 | help='Install Natural Memory Triggers v7.1.3 only')
1132 | parser.add_argument('--all', action='store_true',
1133 | help='Install all features (default behavior)')
1134 | parser.add_argument('--test', action='store_true',
1135 | help='Run tests only (do not install)')
1136 | parser.add_argument('--uninstall', action='store_true',
1137 | help='Remove installed hooks')
1138 | parser.add_argument('--force', action='store_true',
1139 | help='Force installation even if prerequisites fail')
1140 | parser.add_argument('--dry-run', action='store_true',
1141 | help='Show what would be installed without making changes')
1142 |
1143 | args = parser.parse_args()
1144 |
1145 | # Create installer instance
1146 | installer = HookInstaller()
1147 |
1148 | installer.header(f"Claude Code Memory Awareness Hooks Installer v{get_project_version()}")
1149 | installer.info(f"Script location: {installer.script_dir}")
1150 | installer.info(f"Target hooks directory: {installer.claude_hooks_dir}")
1151 | installer.info(f"Platform: {installer.platform_name}")
1152 |
1153 | # Handle special modes first
1154 | if args.uninstall:
1155 | if installer.uninstall():
1156 | installer.success("Hooks uninstalled successfully")
1157 | else:
1158 | installer.error("Uninstall failed")
1159 | sys.exit(1)
1160 | return
1161 |
1162 | if args.test:
1163 | test_natural_triggers = not args.basic
1164 | if installer.run_tests(test_natural_triggers=test_natural_triggers):
1165 | installer.success("All tests passed")
1166 | else:
1167 | installer.error("Some tests failed")
1168 | sys.exit(1)
1169 | return
1170 |
1171 | # Check prerequisites
1172 | if not installer.check_prerequisites() and not args.force:
1173 | installer.error("Prerequisites check failed. Use --force to continue anyway.")
1174 | sys.exit(1)
1175 |
1176 | # Enhanced MCP Detection and Configuration
1177 | installer.header("MCP Configuration Detection")
1178 | detected_mcp = installer.detect_claude_mcp_configuration()
1179 |
1180 | use_existing_mcp = False
1181 | if detected_mcp:
1182 | # Validate MCP prerequisites
1183 | is_valid, issues = installer.validate_mcp_prerequisites(detected_mcp)
1184 |
1185 | if is_valid:
1186 | installer.success("✅ Valid MCP configuration detected!")
1187 | installer.info("📋 Configuration Options:")
1188 | installer.info(" [1] Use existing MCP setup (recommended) - DRY principle ✨")
1189 | installer.info(" [2] Create independent hooks setup - legacy fallback")
1190 |
1191 | # For now, we'll default to using existing MCP (can be made interactive later)
1192 | use_existing_mcp = True
1193 | installer.info("Using existing MCP configuration (option 1)")
1194 | else:
1195 | installer.warn("⚠️ MCP configuration found but has issues:")
1196 | for issue in issues:
1197 | installer.warn(f" - {issue}")
1198 | installer.info("Will use independent setup as fallback")
1199 | else:
1200 | installer.info("No existing MCP configuration found - using independent setup")
1201 |
1202 | # Environment Detection and Protocol Configuration
1203 | installer.header("Environment Detection & Protocol Configuration")
1204 | env_type = installer.detect_environment_type()
1205 |
1206 | # Determine what to install
1207 | install_all = not (args.basic or args.natural_triggers) or args.all
1208 | install_basic = args.basic or install_all
1209 | install_natural_triggers = args.natural_triggers or install_all
1210 |
1211 | installer.info(f"Installation plan:")
1212 | installer.info(f" Basic hooks: {'Yes' if install_basic else 'No'}")
1213 | installer.info(f" Natural Memory Triggers: {'Yes' if install_natural_triggers else 'No'}")
1214 |
1215 | if args.dry_run:
1216 | installer.info("DRY RUN - No changes will be made")
1217 | installer.info("Would install:")
1218 | if install_basic:
1219 | installer.info(" - Basic memory awareness hooks")
1220 | installer.info(" - Core utilities and configuration")
1221 | if install_natural_triggers:
1222 | installer.info(" - Natural Memory Triggers v7.1.3")
1223 | installer.info(" - Mid-conversation hooks")
1224 | installer.info(" - Performance optimization utilities")
1225 | installer.info(" - CLI management tools")
1226 | return
1227 |
1228 | # Create backup
1229 | installer.create_backup()
1230 |
1231 | # Perform installation
1232 | overall_success = True
1233 |
1234 | # Install components based on selection
1235 | if install_basic:
1236 | if not installer.install_basic_hooks():
1237 | overall_success = False
1238 |
1239 | if install_natural_triggers:
1240 | if not installer.install_natural_triggers():
1241 | overall_success = False
1242 |
1243 | # Install configuration (always needed) with MCP awareness
1244 | if not installer.install_configuration(install_natural_triggers=install_natural_triggers,
1245 | detected_mcp=detected_mcp if use_existing_mcp else None,
1246 | env_type=env_type):
1247 | overall_success = False
1248 |
1249 | # Configure Claude Code settings
1250 | if not installer.configure_claude_settings(install_mid_conversation=install_natural_triggers):
1251 | overall_success = False
1252 |
1253 | # Run tests to verify installation
1254 | if overall_success:
1255 | installer.info("Running post-installation tests...")
1256 | if installer.run_tests(test_natural_triggers=install_natural_triggers):
1257 | installer.header("Installation Complete!")
1258 |
1259 | if install_basic and install_natural_triggers:
1260 | installer.success("Complete Claude Code memory awareness system installed")
1261 | installer.info("Features available:")
1262 | installer.info(" ✅ Session-start and session-end hooks")
1263 | installer.info(" ✅ Natural Memory Triggers with intelligent pattern detection")
1264 | installer.info(" ✅ Mid-conversation memory injection")
1265 | installer.info(" ✅ Performance optimization and CLI management")
1266 | installer.info("")
1267 | installer.info("CLI Management:")
1268 | installer.info(f" node {installer.claude_hooks_dir}/memory-mode-controller.js status")
1269 | installer.info(f" node {installer.claude_hooks_dir}/memory-mode-controller.js profile balanced")
1270 | elif install_natural_triggers:
1271 | installer.success("Natural Memory Triggers v7.1.3 installed")
1272 | installer.info("Advanced memory awareness features available")
1273 | elif install_basic:
1274 | installer.success("Basic memory awareness hooks installed")
1275 | installer.info("Session-based memory awareness enabled")
1276 |
1277 | # Code execution enabled message (applies to all installation types)
1278 | installer.info("")
1279 | installer.success("Code Execution Interface enabled by default")
1280 | installer.info(" ✅ 75-90% token reduction")
1281 | installer.info(" ✅ Automatic MCP fallback")
1282 | installer.info(" ✅ Zero breaking changes")
1283 | installer.info(" ℹ️ Disable in ~/.claude/hooks/config.json if needed")
1284 |
1285 | else:
1286 | installer.warn("Installation completed but some tests failed")
1287 | installer.info("Hooks may still work - check configuration manually")
1288 | else:
1289 | installer.error("Installation failed - some components could not be installed")
1290 | sys.exit(1)
1291 |
1292 |
1293 | if __name__ == "__main__":
1294 | try:
1295 | main()
1296 | except KeyboardInterrupt:
1297 | print(f"\n{Colors.YELLOW}Installation cancelled by user{Colors.NC}")
1298 | sys.exit(1)
1299 | except Exception as e:
1300 | print(f"\n{Colors.RED}Unexpected error: {e}{Colors.NC}")
1301 | sys.exit(1)
```
--------------------------------------------------------------------------------
/archive/docs-root-cleanup-2025-08-23/README-ORIGINAL-BACKUP.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service
2 |
3 | [](https://opensource.org/licenses/Apache-2.0)
4 | [](https://github.com/doobidoo/mcp-memory-service/stargazers)
5 | [](https://github.com/doobidoo/mcp-memory-service/network/members)
6 | [](https://github.com/doobidoo/mcp-memory-service/issues)
7 | [](https://github.com/doobidoo/mcp-memory-service/commits)
8 |
9 | [](https://smithery.ai/server/@doobidoo/mcp-memory-service)
10 | [](https://mseep.ai/app/0513fb92-e941-4fe0-9948-2a1dbb870dcf)
11 |
12 | [](https://claude.ai)
13 | [](https://cursor.sh)
14 | [](https://codeium.com/windsurf)
15 | [](https://lmstudio.ai)
16 | [](https://zed.dev)
17 |
18 | [](https://modelcontextprotocol.io/)
19 | [](https://github.com/doobidoo/mcp-memory-service#features)
20 | [](https://github.com/doobidoo/mcp-memory-service#hardware-compatibility)
21 | [](https://github.com/doobidoo/mcp-memory-service#-in-production)
22 | [](https://github.com/doobidoo/mcp-memory-service#storage-backends)
23 | [](https://github.com/doobidoo/mcp-memory-service#storage-backends)
24 |
25 | A **universal MCP memory service** providing **semantic memory search**, persistent storage, and **autonomous memory consolidation** for **AI assistants** and development environments. This **Model Context Protocol server** works with **Claude Desktop, VS Code, Cursor, Continue, WindSurf, LM Studio, Zed, and 13+ AI applications**, featuring **multiple storage backends** including **SQLite-vec** for **fast local search**, **Cloudflare** for **global edge distribution**, and a revolutionary **dream-inspired consolidation system** that automatically organizes, compresses, and manages your **AI conversation history** over time, creating a **self-evolving knowledge base** for enhanced **AI productivity**.
26 |
27 | <img width="240" alt="grafik" src="https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555" />
28 | <a href="https://glama.ai/mcp/servers/bzvl3lz34o"><img width="380" height="200" src="https://glama.ai/mcp/servers/bzvl3lz34o/badge" alt="Memory Service MCP server" /></a>
29 |
30 | ## Help
31 | - Talk to the Repo with [TalkToGitHub](https://talktogithub.com/doobidoo/mcp-memory-service)!
32 | - Use Gitprobe to digg deeper: [GitProbe](https://gitprobe.com/doobidoo/mcp-memory-service)!
33 |
34 | ---
35 |
36 | ## 📋 Table of Contents
37 |
38 | ### 🚀 Getting Started
39 | - [⚡ Quick Start](#-quick-start)
40 | - [🌍 Cloudflare Backend (v6.2.0)](#cloudflare-v620---cloud-native-)
41 | - [🧠 Claude Code Memory Awareness (v6.0.0)](#-new-claude-code-memory-awareness-v600)
42 | - [🎯 Claude Code Commands (v2.2.0)](#-new-claude-code-commands-v220)
43 | - [🚀 Remote MCP Memory Service (v4.0.0)](#-new-remote-mcp-memory-service-v400)
44 | - [🔄 Distributed Memory Synchronization (v6.3.0)](#-new-distributed-memory-synchronization-v630)
45 | - [📦 Installation Methods](#installation-methods)
46 | - [⚙️ Claude MCP Configuration](#claude-mcp-configuration)
47 |
48 | ### 🌟 Features & Capabilities
49 | - [✨ Features Overview](#features)
50 | - [🧠 Dream-Inspired Memory Consolidation](#-dream-inspired-memory-consolidation)
51 | - [💾 Storage Backends](#storage-backends)
52 | - [🔧 Memory Operations](#memory-operations)
53 |
54 | ### 🌐 Deployment & Multi-Client
55 | - [🌐 Multi-Client Deployment](#-multi-client-deployment)
56 | - [🔒 SSL/TLS Configuration](#ssltls-configuration)
57 | - [🚀 Service Installation](#-service-installation-new)
58 |
59 | ### 📖 Documentation & Support
60 | - [📝 Usage Guide](#usage-guide)
61 | - [⚙️ Configuration Options](#configuration-options)
62 | - [🖥️ Hardware Compatibility](#hardware-compatibility)
63 | - [🧪 Testing](#testing)
64 | - [❓ FAQ](#faq)
65 | - [🛠️ Troubleshooting](#troubleshooting)
66 | - [📚 Comprehensive Documentation](#-comprehensive-documentation)
67 |
68 | ### 👨💻 Development & Community
69 | - [🏗️ Project Structure](#project-structure)
70 | - [📋 Development Guidelines](#development-guidelines)
71 | - [🤝 Integrations](#integrations)
72 | - [💖 Sponsorship](#-why-sponsor-mcp-memory-service)
73 |
74 | ---
75 |
76 | ## 🚀 Quick Start
77 |
78 | Choose your preferred installation method to get started in under 5 minutes:
79 |
80 | ### Option 1: Docker (Fastest - 2 minutes)
81 | ```bash
82 | # Pull and run with default settings
83 | docker pull doobidoo/mcp-memory-service:latest
84 | docker run -d -p 8000:8000 -v $(pwd)/data:/app/data doobidoo/mcp-memory-service:latest
85 | ```
86 | ✅ **Perfect for**: Testing, production deployment, isolation
87 | ➡️ [Complete Docker Setup](#docker-installation)
88 |
89 | ### Option 2: Smithery (Simplest - 1 minute)
90 | ```bash
91 | # Auto-install for Claude Desktop
92 | npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
93 | ```
94 | ✅ **Perfect for**: Claude Desktop users, zero configuration
95 | ➡️ [Smithery Details](#installing-via-smithery)
96 |
97 | ### Option 3: Python Installer (Most Flexible - 5 minutes)
98 | ```bash
99 | # Clone and install with hardware detection
100 | git clone https://github.com/doobidoo/mcp-memory-service.git
101 | cd mcp-memory-service && python install.py
102 | ```
103 | ✅ **Perfect for**: Developers, customization, multi-client setup
104 | ➡️ [Full Installation Guide](#-intelligent-installer-recommended)
105 |
106 | ---
107 |
108 | ## 🧠 NEW: Claude Code Memory Awareness (v6.0.0)
109 |
110 | **Revolutionary automatic memory injection for Claude Code sessions!**
111 |
112 | Transform your development experience with intelligent, automatic memory context that appears seamlessly in every Claude Code session. Never lose track of decisions, insights, or architectural choices again.
113 |
114 | ### ✨ Automatic Memory Injection
115 |
116 | ```bash
117 | # Install the memory awareness hook system
118 | cd claude-hooks && ./install.sh
119 |
120 | # Every Claude Code session now starts with relevant context:
121 | # 🧠 Relevant Memory Context
122 | #
123 | # ## Recent Insights (Last 7 days)
124 | # - Database Performance Issue - Resolved SQLite-vec optimization (yesterday)
125 | # - Authentication Flow - Implemented JWT validation (3 days ago)
126 | #
127 | # ## Key Decisions
128 | # - Architecture Decision - Chose React over Vue (1 week ago)
129 | # - Database Choice - Selected PostgreSQL for production (2 weeks ago)
130 | ```
131 |
132 | ### 🎯 Features
133 |
134 | 🤖 **Zero Cognitive Load**: Memory context appears automatically without user intervention
135 | 🧠 **Intelligent Selection**: Advanced scoring algorithm chooses only relevant memories
136 | ⚡ **Lightning Fast**: Memory injection adds <2 seconds to session startup
137 | 📊 **Multi-Language Support**: Detects JavaScript, Python, Rust, Go, Java, C++ projects
138 | 🏗️ **Context-Aware**: Understands your project structure, git repo, and technology stack
139 | 📝 **Beautiful Formatting**: Categorized, markdown-rich memory presentation
140 | 🔄 **Session Learning**: Automatically stores session outcomes for future reference
141 | ✅ **100% Test Coverage**: Comprehensive testing with complete integration validation
142 |
143 | ### 🚀 Installation
144 |
145 | ```bash
146 | # Clone repository and install hooks
147 | git clone https://github.com/doobidoo/mcp-memory-service.git
148 | cd mcp-memory-service/claude-hooks
149 | ./install.sh
150 |
151 | # Verify installation
152 | npm test # 10 tests, all passing
153 | ```
154 |
155 | ### 🏗️ How It Works
156 |
157 | 1. **Session Start**: Hook detects project context (language, framework, git info)
158 | 2. **Memory Query**: Searches memory service for relevant memories using multi-factor scoring
159 | 3. **Context Injection**: Formats and injects top 8 relevant memories as session context
160 | 4. **Session End**: Analyzes conversation and stores outcomes with intelligent tagging
161 |
162 | ### 📊 Memory Scoring Algorithm
163 |
164 | ```javascript
165 | // Multi-factor relevance scoring
166 | const relevanceScore = (
167 | timeDecayScore * 0.4 + // Recent memories preferred
168 | tagRelevanceScore * 0.3 + // Project-specific tags
169 | contentSimilarityScore * 0.2 + // Semantic matching
170 | memoryTypeBonusScore * 0.1 // Decision/insight bonus
171 | );
172 | ```
173 |
174 | ➡️ [**Technical Architecture**](docs/enhancement-roadmap-issue-14.md) | [**Installation Guide**](claude-hooks/README.md) | [**Test Results**](claude-hooks/tests/)
175 |
176 | ---
177 |
178 | ## 🎯 NEW: Claude Code Commands (v2.2.0)
179 |
180 | **Get started in 2 minutes with direct memory commands!**
181 |
182 | ```bash
183 | # Install with Claude Code commands
184 | python install.py --install-claude-commands
185 |
186 | # Start using immediately
187 | claude /memory-store "Important decision about architecture"
188 | claude /memory-recall "what did we decide last week?"
189 | claude /memory-search --tags "architecture,database"
190 | claude /memory-health
191 | ```
192 |
193 | ✨ **5 conversational commands** following CCPlugins pattern
194 | 🚀 **Zero MCP server configuration** required
195 | 🧠 **Context-aware operations** with automatic project detection
196 | 🎨 **Professional interface** with comprehensive guidance
197 |
198 | ➡️ [**Quick Start Guide**](docs/guides/claude-code-quickstart.md) | [**Full Integration Guide**](docs/guides/claude-code-integration.md)
199 |
200 | ## 🚀 NEW: Remote MCP Memory Service (v4.0.0)
201 |
202 | **Production-ready remote memory service with native MCP-over-HTTP protocol!**
203 |
204 | ### Remote Deployment
205 |
206 | Deploy the memory service on any server for cross-device access:
207 |
208 | ```bash
209 | # On your server
210 | git clone https://github.com/doobidoo/mcp-memory-service.git
211 | cd mcp-memory-service
212 | python install.py
213 | python scripts/run_http_server.py
214 | ```
215 |
216 | **Server Access Points:**
217 | - **MCP Protocol**: `http://your-server:8000/mcp` (for MCP clients)
218 | - **Dashboard**: `http://your-server:8000/` (web interface)
219 | - **API Docs**: `http://your-server:8000/api/docs` (interactive API)
220 |
221 | ### Remote API Access
222 |
223 | Connect any MCP client or tool to your remote memory service:
224 |
225 | ```bash
226 | # Test MCP connection
227 | curl -X POST http://your-server:8000/mcp \
228 | -H "Content-Type: application/json" \
229 | -d '{
230 | "jsonrpc": "2.0",
231 | "id": 1,
232 | "method": "tools/list"
233 | }'
234 |
235 | # Store memories remotely
236 | curl -X POST http://your-server:8000/mcp \
237 | -H "Content-Type: application/json" \
238 | -d '{
239 | "jsonrpc": "2.0",
240 | "id": 1,
241 | "method": "tools/call",
242 | "params": {
243 | "name": "store_memory",
244 | "arguments": {
245 | "content": "Your memory content",
246 | "tags": ["tag1", "tag2"]
247 | }
248 | }
249 | }'
250 | ```
251 |
252 | **Key Benefits:**
253 | - ✅ **Cross-Device Access**: Connect from any device running Claude Code
254 | - ✅ **Native MCP Protocol**: Standard JSON-RPC 2.0 implementation
255 | - ✅ **No Bridge Required**: Direct HTTP/HTTPS connection
256 | - ✅ **Production Ready**: Proven deployment at scale
257 |
258 | ---
259 |
260 | ## 🔄 NEW: Distributed Memory Synchronization (v6.3.0)
261 |
262 | **Git-like workflow for distributed memory systems with automatic conflict resolution!**
263 |
264 | Transform your memory service into a distributed system with seamless synchronization between local development and remote production servers. Features intelligent conflict detection, offline capability, and real-time replication.
265 |
266 | ### ✨ Key Features
267 |
268 | 🌐 **Remote-First Architecture**: Direct API communication with local staging fallback
269 | ⚡ **Real-Time Replication**: Litestream integration for live SQLite synchronization
270 | 🔄 **Git-like Workflow**: Stage → Pull → Apply → Push with automatic conflict resolution
271 | 🏠 **Offline Capability**: Local staging database for offline development
272 | 🔍 **Content Hash Detection**: Intelligent deduplication and conflict prevention
273 | 📡 **Cross-Platform Service**: Works on Linux, macOS, and Windows servers
274 | 🎯 **Zero Configuration**: Automatic service discovery via mDNS/hostname resolution
275 |
276 | ### 🚀 Quick Setup
277 |
278 | ```bash
279 | # Install distributed sync system
280 | ./scripts/memory_sync.sh install
281 |
282 | # Configure remote server (one-time setup)
283 | export REMOTE_MEMORY_HOST="narrowbox.local"
284 | export REMOTE_MEMORY_PORT="8443"
285 |
286 | # Initialize sync with remote server
287 | ./scripts/memory_sync.sh init
288 | ```
289 |
290 | ### 🔧 Git-like Commands
291 |
292 | ```bash
293 | # Stage memories locally (offline mode)
294 | ./scripts/enhanced_memory_store.sh "Important development decision"
295 |
296 | # Pull latest changes from remote
297 | ./scripts/memory_sync.sh pull
298 |
299 | # Push local changes to remote
300 | ./scripts/memory_sync.sh push
301 |
302 | # Full synchronization workflow
303 | ./scripts/memory_sync.sh sync
304 |
305 | # Check sync status with colored output
306 | ./scripts/memory_sync.sh status
307 | ```
308 |
309 | ### 🏗️ Architecture Overview
310 |
311 | ```mermaid
312 | graph TB
313 | A[Local Client] -->|1. Try Direct API| B[Remote Server]
314 | A -->|2. Fallback if Offline| C[Staging DB]
315 | B -->|Real-time Sync| D[Production SQLite]
316 | C -->|Batch Sync| E[Sync Engine]
317 | E -->|Content Hash Check| B
318 | F[Litestream] -->|Continuous Replication| G[Backup Storage]
319 | D --> F
320 | ```
321 |
322 | ### 💾 Components
323 |
324 | #### Core Sync Engine
325 | - **`memory_sync.sh`**: Main orchestrator with colored status output
326 | - **`enhanced_memory_store.sh`**: Remote-first storage with intelligent fallback
327 | - **`pull_remote_changes.sh`**: Conflict-aware remote synchronization
328 | - **`manual_sync.sh`**: HTTP-based sync with content hash validation
329 |
330 | #### Database Infrastructure
331 | - **`staging_db_init.sql`**: Complete SQLite staging schema with triggers
332 | - **`litestream.yml`**: Master/replica configuration for real-time sync
333 | - **Service files**: Cross-platform systemd/LaunchDaemon integration
334 |
335 | #### Advanced Features
336 | - **Content hash-based deduplication**: Prevents duplicate memories across sync
337 | - **Staging database system**: Full offline capability with background sync
338 | - **HTTP replica serving**: Lightweight Python server for cross-network access
339 | - **Service management**: Native integration with system service managers
340 |
341 | ### 🔧 Advanced Configuration
342 |
343 | ```bash
344 | # Fine-tune sync behavior
345 | export SYNC_CONFLICT_RESOLUTION="merge" # merge, local, remote
346 | export SYNC_BATCH_SIZE="100" # Memories per sync batch
347 | export SYNC_RETRY_ATTEMPTS="3" # Network retry count
348 | export SYNC_OFFLINE_THRESHOLD="5" # Seconds before offline mode
349 |
350 | # Litestream replication settings
351 | export LITESTREAM_REPLICA_PATH="/backup/sqlite_vec.db"
352 | export LITESTREAM_SYNC_INTERVAL="1s" # Real-time replication
353 | export LITESTREAM_RETENTION="72h" # Backup retention period
354 | ```
355 |
356 | ### 📊 Status Dashboard
357 |
358 | The sync system provides comprehensive status reporting:
359 |
360 | ```bash
361 | ./scripts/memory_sync.sh status
362 | ```
363 |
364 | **Output includes:**
365 | - 🟢 **Remote connectivity** status with response time
366 | - 📊 **Memory counts** (local vs remote) with sync diff
367 | - ⏰ **Last sync** timestamp and success rate
368 | - 🔄 **Replication status** via Litestream integration
369 | - 🎯 **Conflict detection** and resolution recommendations
370 |
371 | ### 🛠️ Service Integration
372 |
373 | Install as system service for automatic sync:
374 |
375 | ```bash
376 | # Install sync service (auto-detects OS)
377 | ./scripts/memory_sync.sh install-service
378 |
379 | # Enable automatic background sync
380 | systemctl enable mcp-memory-sync # Linux
381 | launchctl load ~/Library/LaunchAgents/com.mcp.memory.sync.plist # macOS
382 | ```
383 |
384 | **Benefits:**
385 | - ✅ **Automatic startup** on boot/login
386 | - ✅ **Background synchronization** every 15 minutes
387 | - ✅ **Service health monitoring** with restart on failure
388 | - ✅ **Cross-platform compatibility** (systemd, LaunchAgent, Windows Service)
389 |
390 | ➡️ **[Complete Sync Documentation](docs/guides/distributed-sync.md)** | **[Installation Guide](docs/installation/distributed-sync.md)** | **[Troubleshooting](docs/troubleshooting/sync-issues.md)**
391 |
392 | ---
393 |
394 | ## Features
395 |
396 | ### 🌟 Universal AI Client Compatibility
397 |
398 | **Works with 13+ AI applications and development environments** via the standard Model Context Protocol (MCP):
399 |
400 | | Client | Status | Configuration | Notes |
401 | |--------|--------|--------------|-------|
402 | | **Claude Desktop** | ✅ Full | `claude_desktop_config.json` | Official MCP support |
403 | | **Claude Code** | ✅ Full | `.claude.json` | Optionally use Claude Commands instead ([guide](CLAUDE_CODE_COMPATIBILITY.md)) |
404 | | **Cursor** | ✅ Full | `.cursor/mcp.json` | AI-powered IDE with MCP support |
405 | | **WindSurf** | ✅ Full | MCP config file | Codeium's AI IDE with built-in server management |
406 | | **LM Studio** | ✅ Full | MCP configuration | Enhanced compatibility with debug output |
407 | | **Cline** | ✅ Full | VS Code MCP config | VS Code extension, formerly Claude Dev |
408 | | **RooCode** | ✅ Full | IDE config | Full MCP client implementation |
409 | | **Zed** | ✅ Full | Built-in config | Native MCP support |
410 | | **VS Code** | ✅ Full | `.vscode/mcp.json` | Via MCP extension |
411 | | **Continue IDE** | ✅ Full | Continue configuration | Extension with MCP support |
412 | | **Standard MCP Libraries** | ✅ Full | Various | Python `mcp`, JavaScript SDK |
413 | | **Custom MCP Clients** | ✅ Full | Implementation-specific | Full protocol compliance |
414 | | **HTTP API** | ✅ Full | REST endpoints | Direct API access on port 8000 |
415 |
416 | **Core Benefits:**
417 | - 🔄 **Cross-Client Memory Sharing**: Use memories across all your AI tools
418 | - 🚀 **Universal Setup**: Single installation works everywhere
419 | - 🔌 **Standard Protocol**: Full MCP compliance ensures compatibility
420 | - 🌐 **Remote Access**: HTTP/HTTPS support for distributed teams
421 |
422 | ➡️ [**Multi-Client Setup Guide**](docs/integration/multi-client.md) | [**IDE Compatibility Details**](docs/ide-compatability.md)
423 |
424 | ### 🧠 Intelligent Memory System
425 |
426 | #### **Autonomous Memory Consolidation**
427 | - **Dream-inspired processing** with multi-layered time horizons (daily → yearly)
428 | - **Creative association discovery** finding non-obvious connections between memories
429 | - **Semantic clustering** automatically organizing related memories
430 | - **Intelligent compression** preserving key information while reducing storage
431 | - **Controlled forgetting** with safe archival and recovery systems
432 | - **Performance optimized** for processing 10k+ memories efficiently
433 |
434 | ### ⚡ ONNX Runtime Support (NEW!)
435 | - **PyTorch-free operation** using ONNX Runtime for embeddings
436 | - **Reduced dependencies** (~500MB less disk space without PyTorch)
437 | - **Faster startup** with pre-optimized ONNX models
438 | - **Automatic fallback** to SentenceTransformers when needed
439 | - **Compatible models** with the same all-MiniLM-L6-v2 embeddings
440 | - Enable with: `export MCP_MEMORY_USE_ONNX=true`
441 |
442 | #### **Advanced Memory Operations**
443 | - **Semantic search** using sentence transformers or ONNX embeddings
444 | - **Natural language time-based recall** (e.g., "last week", "yesterday morning")
445 | - **Enhanced tag deletion system** with flexible multi-tag support
446 | - **Tag-based memory retrieval** system with OR/AND logic
447 | - **Exact match retrieval** and duplicate detection
448 | - **Debug mode** for similarity analysis and troubleshooting
449 |
450 | #### **Enhanced MCP Protocol Features** (v4.1.0+)
451 | - **📚 URI-based Resources**: `memory://stats`, `memory://tags`, `memory://recent/{n}`, `memory://search/{query}`
452 | - **📋 Guided Prompts**: Interactive workflows (memory_review, memory_analysis, knowledge_export)
453 | - **📊 Progress Tracking**: Real-time notifications for long operations
454 | - **🔄 Database Synchronization**: Multi-node sync with Litestream integration
455 | - **🎛️ Client Optimization**: Auto-detection and optimization for Claude Desktop vs LM Studio
456 |
457 | ### 🚀 Deployment & Performance
458 |
459 | #### **Storage Backends**
460 | - **🪶 SQLite-vec (default)**: 10x faster startup, 75% less memory, zero network dependencies
461 | - **📦 ChromaDB (legacy)**: Available for backward compatibility, deprecated in v6.0.0
462 |
463 | #### **Multi-Client Architecture**
464 | - **Production FastAPI server** with auto-generated SSL certificates
465 | - **mDNS Service Discovery** for zero-configuration networking
466 | - **Server-Sent Events (SSE)** with real-time updates
467 | - **API key authentication** for secure deployments
468 | - **Cross-platform service installation** (systemd, LaunchAgent, Windows Service)
469 |
470 | #### **Platform Support**
471 | - **Cross-platform compatibility**: Apple Silicon, Intel, Windows, Linux
472 | - **Hardware-aware optimizations**: CUDA, MPS, DirectML, ROCm support
473 | - **Graceful fallbacks** for limited hardware resources
474 | - **Container support** with Docker images and Docker Compose configurations
475 |
476 | ### Recent Highlights
477 |
478 | #### 🚀 Latest Features
479 | - **v6.3.0**: 🔄 **Distributed Memory Synchronization** - Git-like workflow, real-time Litestream replication, offline capability
480 | - **v6.2.0**: 🌍 **Native Cloudflare Backend Integration** - Global edge distribution, serverless scaling, Vectorize + D1 + R2 storage
481 | - **v6.1.0**: 🧠 **Intelligent Context Updates (Phase 2)** - Real-time conversation analysis with dynamic memory loading
482 | - **v6.0.0**: 🧠 **Claude Code Memory Awareness (Phase 1)** - Automatic memory injection for coding sessions
483 | - **v5.0.2**: ONNX Runtime support for PyTorch-free embeddings and SQLite-vec consolidation fixes
484 | - **v5.0.0**: SQLite-vec is now the default backend - 10x faster startup, 75% less memory
485 |
486 | ➡️ **[View Full Changelog](CHANGELOG.md)** for complete version history and detailed release notes
487 |
488 | ## Installation Methods
489 |
490 | *For quick setup, see the [⚡ Quick Start](#-quick-start) section above.*
491 |
492 | [](#docker-installation)
493 | [](#installing-via-smithery)
494 | [](#-intelligent-installer-recommended)
495 | [](#uvx-installation)
496 |
497 | ### 🚀 Intelligent Installer (Recommended)
498 |
499 | The new unified installer automatically detects your hardware and selects the optimal configuration:
500 |
501 | ```bash
502 | # Clone the repository
503 | git clone https://github.com/doobidoo/mcp-memory-service.git
504 | cd mcp-memory-service
505 |
506 | # Create and activate a virtual environment
507 | python -m venv venv
508 | source venv/bin/activate # On Windows: venv\Scripts\activate
509 |
510 | # Run the intelligent installer
511 | python install.py
512 |
513 | # ✨ NEW: Multi-client setup is now integrated!
514 | # You'll be prompted to configure universal MCP client access
515 | # for Claude Desktop, VS Code, Continue, and other MCP applications
516 | ```
517 |
518 | ### 🎯 Hardware-Specific Installation
519 |
520 | **For Intel Macs:**
521 | For detailed setup instructions specific to Intel Macs, see our [Intel Mac Setup Guide](docs/platforms/macos-intel.md).
522 |
523 | **For Legacy Hardware (2013-2017 Intel Macs):**
524 | ```bash
525 | python install.py --legacy-hardware
526 | ```
527 |
528 | **For Server/Headless Deployment:**
529 | ```bash
530 | python install.py --server-mode
531 | ```
532 |
533 | **For HTTP/SSE API Development:**
534 | ```bash
535 | python install.py --enable-http-api
536 | ```
537 |
538 | **For Migration from ChromaDB:**
539 | ```bash
540 | python install.py --migrate-from-chromadb
541 | ```
542 |
543 | **For Multi-Client Setup:**
544 | ```bash
545 | # Automatic multi-client setup during installation
546 | python install.py --setup-multi-client
547 |
548 | # Skip the interactive multi-client prompt
549 | python install.py --skip-multi-client-prompt
550 | ```
551 |
552 | **For Claude Code Commands:**
553 | ```bash
554 | # Install with Claude Code commands (prompts if CLI detected)
555 | python install.py --install-claude-commands
556 |
557 | # Skip the interactive Claude Code commands prompt
558 | python install.py --skip-claude-commands-prompt
559 | ```
560 |
561 | ### 🧠 What the Installer Does
562 |
563 | 1. **Hardware Detection**: CPU, GPU, memory, and platform analysis
564 | 2. **Intelligent Backend Selection**: SQLite-vec by default, with ChromaDB as legacy option
565 | 3. **Platform Optimization**: macOS Intel fixes, Windows CUDA setup, Linux variations
566 | 4. **Dependency Management**: Compatible PyTorch and ML library versions
567 | 5. **Auto-Configuration**: Claude Desktop config and environment variables
568 | 6. **Migration Support**: Seamless ChromaDB to SQLite-vec migration
569 |
570 | ### 📊 Storage Backend Selection
571 |
572 | **SQLite-vec (default)**: 10x faster startup, zero dependencies, recommended for all users
573 | **ChromaDB (deprecated)**: Legacy support only, will be removed in v6.0.0
574 |
575 | ➡️ **[Detailed Storage Backend Comparison](#storage-backends)**
576 |
577 | To explicitly select a backend during installation:
578 | ```bash
579 | python install.py # Uses SQLite-vec by default
580 | python install.py --storage-backend sqlite_vec # Explicitly use SQLite-vec
581 | python install.py --storage-backend chromadb # Use legacy ChromaDB (not recommended)
582 | ```
583 |
584 | ### Docker Installation
585 |
586 | #### Docker Hub (Recommended)
587 |
588 | The easiest way to run the Memory Service is using our pre-built Docker images. We provide **two variants** optimized for different use cases:
589 |
590 | ##### Standard Image (Full Features)
591 | ```bash
592 | # Pull the standard image (includes PyTorch + CUDA support)
593 | docker pull doobidoo/mcp-memory-service:latest
594 |
595 | # Run with default settings (for MCP clients)
596 | docker run -d -p 8000:8000 \
597 | -v $(pwd)/data/sqlite_db:/app/sqlite_db \
598 | -v $(pwd)/data/backups:/app/backups \
599 | doobidoo/mcp-memory-service:latest
600 | ```
601 |
602 | ##### Slim Image (90% Smaller - Recommended for CPU-only deployments)
603 | ```bash
604 | # Pull the slim image (ONNX + sqlite-vec only, ~300MB vs 3GB+)
605 | docker pull doobidoo/mcp-memory-service:slim
606 |
607 | # Run optimized for CPU-only performance
608 | docker run -d -p 8000:8000 \
609 | -v $(pwd)/data/sqlite_db:/app/sqlite_db \
610 | -v $(pwd)/data/backups:/app/backups \
611 | doobidoo/mcp-memory-service:slim
612 | ```
613 |
614 | **Image Comparison:**
615 | - **Standard**: ~3.4GB (PyTorch + CUDA libraries) - Best for GPU acceleration
616 | - **Slim**: ~300MB (ONNX + sqlite-vec only) - Best for CPU-only deployments, faster pulls
617 |
618 | ##### Advanced Usage
619 | ```bash
620 | # Run in standalone mode (for testing/development)
621 | docker run -d -p 8000:8000 \
622 | -e MCP_STANDALONE_MODE=1 \
623 | -v $(pwd)/data/sqlite_db:/app/sqlite_db \
624 | -v $(pwd)/data/backups:/app/backups \
625 | doobidoo/mcp-memory-service:slim
626 | ```
627 |
628 | #### Docker Compose
629 |
630 | We provide multiple Docker Compose configurations for different scenarios:
631 | - `docker-compose.yml` - Standard configuration for MCP clients
632 | - `docker-compose.standalone.yml` - **Standalone mode** for testing/development (prevents boot loops)
633 | - `docker-compose.uv.yml` - Alternative configuration using UV package manager
634 | - `docker-compose.pythonpath.yml` - Configuration with explicit PYTHONPATH settings
635 |
636 | ```bash
637 | # Using Docker Compose (recommended)
638 | docker-compose up
639 |
640 | # Standalone mode (prevents boot loops)
641 | docker-compose -f docker-compose.standalone.yml up
642 | ```
643 |
644 | #### Building from Source
645 |
646 | If you need to build the Docker image yourself:
647 |
648 | ```bash
649 | # Build the image
650 | docker build -t mcp-memory-service .
651 |
652 | # Run the container
653 | docker run -p 8000:8000 \
654 | -v $(pwd)/data/chroma_db:/app/chroma_db \
655 | -v $(pwd)/data/backups:/app/backups \
656 | mcp-memory-service
657 | ```
658 |
659 | ### uvx Installation
660 |
661 | You can install and run the Memory Service using uvx for isolated execution:
662 |
663 | ```bash
664 | # Install uv (which includes uvx) if not already installed
665 | pip install uv
666 | # Or use the installer script:
667 | # curl -LsSf https://astral.sh/uv/install.sh | sh
668 |
669 | # Install and run the memory service
670 | uvx mcp-memory-service
671 |
672 | # Or install from GitHub
673 | uvx --from git+https://github.com/doobidoo/mcp-memory-service.git mcp-memory-service
674 | ```
675 |
676 | ### Windows Installation (Special Case)
677 |
678 | Windows users may encounter PyTorch installation issues due to platform-specific wheel availability. Use our Windows-specific installation script:
679 |
680 | ```bash
681 | # After activating your virtual environment
682 | python scripts/install_windows.py
683 | ```
684 |
685 | This script handles:
686 | 1. Detecting CUDA availability and version
687 | 2. Installing the appropriate PyTorch version from the correct index URL
688 | 3. Installing other dependencies without conflicting with PyTorch
689 | 4. Verifying the installation
690 |
691 | ### Installing via Smithery
692 |
693 | To install Memory Service for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@doobidoo/mcp-memory-service):
694 |
695 | ```bash
696 | npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
697 | ```
698 |
699 | ### Detailed Installation Guide
700 |
701 | For comprehensive installation instructions and troubleshooting, see the [Installation Guide](docs/installation/master-guide.md).
702 |
703 | ## Configuration
704 |
705 | ### Basic Client Configuration
706 |
707 | #### Claude Desktop Configuration
708 | Add to your `claude_desktop_config.json` file:
709 |
710 | ```json
711 | {
712 | "memory": {
713 | "command": "uv",
714 | "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory"],
715 | "env": {
716 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
717 | "MCP_MEMORY_SQLITE_PATH": "/path/to/sqlite_vec.db",
718 | "MCP_MEMORY_BACKUPS_PATH": "/path/to/backups"
719 | }
720 | }
721 | }
722 | ```
723 |
724 | #### Windows-Specific Configuration
725 | For Windows, use the wrapper script for PyTorch compatibility:
726 |
727 | ```json
728 | {
729 | "memory": {
730 | "command": "python",
731 | "args": ["C:\\path\\to\\mcp-memory-service\\memory_wrapper.py"],
732 | "env": {
733 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
734 | "MCP_MEMORY_SQLITE_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\sqlite_vec.db",
735 | "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\backups"
736 | }
737 | }
738 | }
739 | ```
740 |
741 | ➡️ **[Multi-Client Setup Guide](#-multi-client-deployment)** for Claude Desktop + VS Code + other MCP clients
742 |
743 | ### Environment Variables
744 |
745 | #### Core Configuration
746 | ```bash
747 | # Storage Backend
748 | MCP_MEMORY_STORAGE_BACKEND=sqlite_vec # sqlite_vec (default) or chromadb
749 | MCP_MEMORY_SQLITE_PATH=/path/to/database.db # SQLite database location
750 | MCP_MEMORY_BACKUPS_PATH=/path/to/backups # Backup directory
751 |
752 | # Performance & Hardware
753 | MCP_MEMORY_BATCH_SIZE=32 # Processing batch size
754 | MCP_MEMORY_MODEL_NAME=all-MiniLM-L6-v2 # Embedding model
755 | PYTORCH_ENABLE_MPS_FALLBACK=1 # Apple Silicon fallback
756 | MCP_MEMORY_USE_ONNX=0 # CPU-only mode
757 | LOG_LEVEL=INFO # Logging level
758 | ```
759 |
760 | #### HTTP API & Remote Access
761 | ```bash
762 | # Server Configuration
763 | MCP_HTTP_ENABLED=true # Enable HTTP server
764 | MCP_HTTP_HOST=0.0.0.0 # Bind to all interfaces
765 | MCP_HTTP_PORT=8000 # Server port
766 |
767 | # Security
768 | MCP_API_KEY="your-secure-api-key" # API authentication
769 | MCP_HTTPS_ENABLED=true # Enable SSL/TLS
770 | MCP_HTTPS_PORT=8443 # HTTPS port
771 | ```
772 |
773 | ### Advanced Configuration
774 |
775 | #### SSL/TLS Setup
776 | For production deployments with HTTPS:
777 |
778 | ```bash
779 | # Enable HTTPS with custom certificates
780 | export MCP_HTTPS_ENABLED=true
781 | export MCP_SSL_CERT_FILE="/path/to/certificate.pem"
782 | export MCP_SSL_KEY_FILE="/path/to/private-key.pem"
783 |
784 | # Generate secure API key
785 | export MCP_API_KEY="$(openssl rand -base64 32)"
786 | ```
787 |
788 | **Local Development with mkcert:**
789 | ```bash
790 | # Install mkcert for trusted local certificates
791 | brew install mkcert # macOS
792 | sudo apt install mkcert # Linux
793 |
794 | # Generate local certificates
795 | mkcert -install
796 | mkcert localhost 127.0.0.1 your-domain.local
797 | ```
798 |
799 | #### Memory Consolidation
800 | ```bash
801 | # Enable autonomous memory consolidation
802 | MCP_CONSOLIDATION_ENABLED=true
803 | MCP_CONSOLIDATION_ARCHIVE_PATH=/path/to/archive
804 |
805 | # Retention periods (days)
806 | MCP_RETENTION_CRITICAL=365
807 | MCP_RETENTION_REFERENCE=180
808 | MCP_RETENTION_STANDARD=30
809 | MCP_RETENTION_TEMPORARY=7
810 | ```
811 |
812 | ## 🌐 Multi-Client Deployment
813 |
814 | **NEW**: Deploy MCP Memory Service for multiple clients sharing the same memory database!
815 |
816 | ### 🚀 Centralized Server Deployment (Recommended)
817 |
818 | Perfect for distributed teams, multiple devices, or cloud deployment:
819 |
820 | ```bash
821 | # Install and start HTTP/SSE server
822 | python install.py --server-mode --enable-http-api
823 | export MCP_HTTP_HOST=0.0.0.0 # Allow external connections
824 | export MCP_API_KEY="your-secure-key" # Optional authentication
825 | python scripts/run_http_server.py
826 | ```
827 |
828 | **✅ Benefits:**
829 | - 🔄 **Real-time sync** across all clients via Server-Sent Events (SSE)
830 | - 🌍 **Cross-platform** - works from any device with HTTP access
831 | - 🔒 **Secure** with optional API key authentication
832 | - 📈 **Scalable** - handles many concurrent clients
833 | - ☁️ **Cloud-ready** - deploy on AWS, DigitalOcean, Docker, etc.
834 |
835 | **Access via:**
836 | - **API Docs**: `http://your-server:8000/api/docs`
837 | - **Web Dashboard**: `http://your-server:8000/`
838 | - **REST API**: All MCP operations available via HTTP
839 |
840 | ### ⚠️ Why NOT Cloud Storage (Dropbox/OneDrive/Google Drive)
841 |
842 | **Direct SQLite on cloud storage DOES NOT WORK** for multi-client access:
843 |
844 | ❌ **File locking conflicts** - Cloud sync breaks SQLite's locking mechanism
845 | ❌ **Data corruption** - Incomplete syncs can corrupt the database
846 | ❌ **Sync conflicts** - Multiple clients create "conflicted copy" files
847 | ❌ **Performance issues** - Full database re-upload on every change
848 |
849 | **✅ Solution**: Use centralized HTTP server deployment instead!
850 |
851 | ### 🔗 Local Multi-Client Coordination
852 |
853 | **For local development with multiple MCP clients** (Claude Desktop + VS Code + Continue, etc.):
854 |
855 | The MCP Memory Service features **universal multi-client coordination** for seamless concurrent access:
856 |
857 | **🚀 Integrated Setup (Recommended):**
858 | ```bash
859 | python install.py # Automatically detects and configures all MCP clients
860 | ```
861 |
862 | **Key Benefits:**
863 | - ✅ **Automatic Coordination**: Intelligent detection of optimal access mode
864 | - ✅ **Universal Setup**: Works with any MCP-compatible application
865 | - ✅ **Shared Memory**: All clients access the same memory database
866 | - ✅ **No Lock Conflicts**: WAL mode prevents database locking issues
867 | - ✅ **IDE-Agnostic**: Switch between development tools while maintaining context
868 |
869 | **Supported Clients:** Claude Desktop, Claude Code, VS Code, Continue IDE, Cursor, Cline, Zed, and more
870 |
871 | ### 📖 Complete Documentation
872 |
873 | For detailed deployment guides, configuration options, and troubleshooting:
874 |
875 | 📚 **[Multi-Client Deployment Guide](docs/integration/multi-client.md)**
876 |
877 | Covers:
878 | - **Centralized HTTP/SSE Server** setup and configuration
879 | - **Shared File Access** for local networks (limited scenarios)
880 | - **Cloud Platform Deployment** (AWS, DigitalOcean, Docker)
881 | - **Security & Authentication** setup
882 | - **Performance Tuning** for high-load environments
883 | - **Troubleshooting** common multi-client issues
884 |
885 | ## Usage Guide
886 |
887 | For detailed instructions on how to interact with the memory service in Claude Desktop:
888 |
889 | - [Invocation Guide](docs/guides/invocation_guide.md) - Learn the specific keywords and phrases that trigger memory operations in Claude
890 | - [Installation Guide](docs/installation/master-guide.md) - Detailed setup instructions
891 | - **[Demo Session Walkthrough](docs/tutorials/demo-session-walkthrough.md)** - Real-world development session showcasing advanced features
892 |
893 | The memory service is invoked through natural language commands in your conversations with Claude. For example:
894 | - To store: "Please remember that my project deadline is May 15th."
895 | - To retrieve: "Do you remember what I told you about my project deadline?"
896 |
897 | ### Claude Code Commands Usage
898 | With the optional Claude Code commands installed, you can also use direct command syntax:
899 | ```bash
900 | # Store information with context
901 | claude /memory-store "Important architectural decision about database backend"
902 |
903 | # Recall memories by time
904 | claude /memory-recall "what did we decide about the database last week?"
905 |
906 | # Search by tags or content
907 | claude /memory-search --tags "architecture,database"
908 |
909 | # Capture current session context
910 | claude /memory-context --summary "Development planning session"
911 |
912 | # Check service health
913 | claude /memory-health
914 | ```
915 | - To delete: "Please forget what I told you about my address."
916 |
917 | See the [Invocation Guide](docs/guides/invocation_guide.md) for a complete list of commands and detailed usage examples.
918 |
919 | ## Storage Backends
920 |
921 | The MCP Memory Service supports multiple storage backends to suit different use cases:
922 |
923 | ### SQLite-vec (Default - Recommended)
924 | - **Best for**: Local development, personal use, single-user deployments
925 | - **Features**: Single-file database, 75% lower memory usage, zero network dependencies
926 | - **Memory usage**: Minimal (~50MB for 1K memories)
927 | - **Setup**: Automatically configured, works offline immediately
928 |
929 | ### Cloudflare (v6.2.0 - Cloud-Native) 🚀
930 | - **Best for**: Production deployments, global scale, multi-user applications
931 | - **Features**: Global edge network, serverless scaling, zero infrastructure management
932 | - **Storage**: Vectorize + D1 + R2, Workers AI embeddings
933 | - **Memory usage**: Minimal local footprint, cloud-based storage
934 | - **Setup**: [Cloudflare Setup Guide](docs/cloudflare-setup.md)
935 |
936 | ### ChromaDB (Legacy - Deprecated)
937 | ⚠️ **DEPRECATED**: Will be removed in v7.0.0. Please migrate to SQLite-vec or Cloudflare.
938 | - **Previous use cases**: Large memory collections, advanced vector metrics
939 | - **Issues**: Network dependencies, Hugging Face download failures, high resource usage
940 | - **Memory usage**: Higher (~200MB for 1K memories)
941 | - **Migration**: Run `python scripts/migrate_to_sqlite_vec.py` or `python scripts/migrate_to_cloudflare.py`
942 |
943 | #### Quick Setup for SQLite-vec
944 |
945 | ```bash
946 | # Install sqlite-vec (if using installation script, this is handled automatically)
947 | pip install sqlite-vec
948 |
949 | # Configure the backend
950 | export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
951 | export MCP_MEMORY_SQLITE_PATH=/path/to/sqlite_vec.db
952 |
953 | # Optional: For CPU-only mode without PyTorch (much lighter resource usage)
954 | export MCP_MEMORY_USE_ONNX=1
955 |
956 | # Restart Claude Desktop
957 | ```
958 |
959 | #### SQLite-vec with Optional PyTorch
960 |
961 | The SQLite-vec backend now works with or without PyTorch installed:
962 |
963 | - **With PyTorch**: Full functionality including embedding generation
964 | - **Without PyTorch**: Basic functionality using pre-computed embeddings and ONNX runtime
965 | - **With Homebrew PyTorch**: Integration with macOS Homebrew PyTorch installation
966 |
967 | To install optional machine learning dependencies:
968 |
969 | ```bash
970 | # Add ML dependencies for embedding generation
971 | pip install 'mcp-memory-service[ml]'
972 | ```
973 |
974 | #### Quick Setup for Cloudflare Backend
975 |
976 | ```bash
977 | # Install additional dependencies
978 | pip install -r requirements-cloudflare.txt
979 |
980 | # Create Cloudflare resources (using Wrangler CLI)
981 | wrangler vectorize create mcp-memory-index --dimensions=768 --metric=cosine
982 | wrangler d1 create mcp-memory-db
983 |
984 | # Configure environment variables
985 | export MCP_MEMORY_STORAGE_BACKEND=cloudflare
986 | export CLOUDFLARE_API_TOKEN="your-api-token"
987 | export CLOUDFLARE_ACCOUNT_ID="your-account-id"
988 | export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index"
989 | export CLOUDFLARE_D1_DATABASE_ID="your-d1-database-id"
990 |
991 | # Optional: R2 bucket for large content
992 | export CLOUDFLARE_R2_BUCKET="mcp-memory-content"
993 |
994 | # Start the service
995 | uv run memory server
996 | ```
997 |
998 | 📖 **[Complete Cloudflare Setup Guide](docs/cloudflare-setup.md)**
999 |
1000 | #### Homebrew PyTorch Integration
1001 |
1002 | For macOS users who prefer to use Homebrew's PyTorch installation:
1003 |
1004 | ```bash
1005 | # Install PyTorch via Homebrew
1006 | brew install pytorch
1007 |
1008 | # Run MCP Memory Service with Homebrew PyTorch integration
1009 | ./run_with_homebrew.sh
1010 | ```
1011 |
1012 | This integration offers several benefits:
1013 | - Uses Homebrew's isolated Python environment for PyTorch
1014 | - Avoids dependency conflicts with Claude Desktop
1015 | - Reduces memory usage in the main process
1016 | - Provides better stability in resource-constrained environments
1017 |
1018 | For detailed documentation on the Homebrew PyTorch integration:
1019 | - [Homebrew Integration Guide](docs/integration/homebrew.md) - Technical journey and solution architecture
1020 |
1021 | #### Migration Between Backends
1022 |
1023 | ```bash
1024 | # Migrate from ChromaDB to SQLite-vec
1025 | python migrate_to_sqlite_vec.py
1026 |
1027 | # Full migration with backup
1028 | python scripts/migrate_storage.py \
1029 | --from chroma --to sqlite_vec \
1030 | --backup --backup-path backup.json
1031 | ```
1032 |
1033 | For detailed SQLite-vec setup, migration, and troubleshooting, see the [SQLite-vec Backend Guide](docs/sqlite-vec-backend.md).
1034 |
1035 |
1036 | ## Memory Operations
1037 |
1038 | The memory service provides the following operations through the MCP server:
1039 |
1040 | ### Core Memory Operations
1041 |
1042 | 1. `store_memory` - Store new information with optional tags
1043 | 2. `retrieve_memory` - Perform semantic search for relevant memories
1044 | 3. `recall_memory` - Retrieve memories using natural language time expressions
1045 | 4. `search_by_tag` - Find memories using specific tags
1046 | 5. `exact_match_retrieve` - Find memories with exact content match
1047 | 6. `debug_retrieve` - Retrieve memories with similarity scores
1048 |
1049 | ### Database Management
1050 |
1051 | 7. `create_backup` - Create database backup
1052 | 8. `get_stats` - Get memory statistics
1053 | 9. `optimize_db` - Optimize database performance
1054 | 10. `check_database_health` - Get database health metrics
1055 | 11. `check_embedding_model` - Verify model status
1056 |
1057 | ### Memory Management
1058 |
1059 | 12. `delete_memory` - Delete specific memory by hash
1060 | 13. `delete_by_tag` - **Enhanced**: Delete memories with specific tag(s) - supports both single tags and multiple tags
1061 | 14. `delete_by_tags` - **New**: Explicitly delete memories containing any of the specified tags (OR logic)
1062 | 15. `delete_by_all_tags` - **New**: Delete memories containing all specified tags (AND logic)
1063 | 16. `cleanup_duplicates` - Remove duplicate entries
1064 |
1065 | ### API Consistency Improvements
1066 |
1067 | **Issue 5 Resolution**: Enhanced tag deletion functionality for consistent API design.
1068 |
1069 | - **Before**: `search_by_tag` accepted arrays, `delete_by_tag` only accepted single strings
1070 | - **After**: Both operations now support flexible tag handling
1071 |
1072 | ```javascript
1073 | // Single tag deletion (backward compatible)
1074 | delete_by_tag("temporary")
1075 |
1076 | // Multiple tag deletion (new!)
1077 | delete_by_tag(["temporary", "outdated", "test"]) // OR logic
1078 |
1079 | // Explicit methods for clarity
1080 | delete_by_tags(["tag1", "tag2"]) // OR logic
1081 | delete_by_all_tags(["urgent", "important"]) // AND logic
1082 | ```
1083 |
1084 | ### Example Usage
1085 |
1086 | ```javascript
1087 | // Store memories with tags
1088 | store_memory("Project deadline is May 15th", {tags: ["work", "deadlines", "important"]})
1089 | store_memory("Grocery list: milk, eggs, bread", {tags: ["personal", "shopping"]})
1090 | store_memory("Meeting notes from sprint planning", {tags: ["work", "meetings", "important"]})
1091 |
1092 | // Search by multiple tags (existing functionality)
1093 | search_by_tag(["work", "important"]) // Returns memories with either tag
1094 |
1095 | // Enhanced deletion options (new!)
1096 | delete_by_tag("temporary") // Delete single tag (backward compatible)
1097 | delete_by_tag(["temporary", "outdated"]) // Delete memories with any of these tags
1098 | delete_by_tags(["personal", "shopping"]) // Explicit multi-tag deletion
1099 | delete_by_all_tags(["work", "important"]) // Delete only memories with BOTH tags
1100 | ```
1101 |
1102 | ## 🧠 Dream-Inspired Memory Consolidation
1103 |
1104 | The memory consolidation system operates autonomously in the background, inspired by how human memory works during sleep cycles. It automatically organizes, compresses, and manages your memories across multiple time horizons.
1105 |
1106 | ### Quick Start
1107 | Enable consolidation with a single environment variable:
1108 | ```bash
1109 | export MCP_CONSOLIDATION_ENABLED=true
1110 | ```
1111 |
1112 | ### How It Works
1113 | - **Daily consolidation** (light processing): Updates memory relevance and basic organization
1114 | - **Weekly consolidation**: Discovers creative associations between memories
1115 | - **Monthly consolidation**: Performs semantic clustering and intelligent compression
1116 | - **Quarterly/Yearly consolidation**: Deep archival and long-term memory management
1117 |
1118 | ### New MCP Tools Available
1119 | Once enabled, you get access to powerful new consolidation tools:
1120 | - `consolidate_memories` - Manually trigger consolidation for any time horizon
1121 | - `get_consolidation_health` - Monitor system health and performance
1122 | - `get_consolidation_stats` - View processing statistics and insights
1123 | - `schedule_consolidation` - Configure autonomous scheduling
1124 | - `get_memory_associations` - Explore discovered memory connections
1125 | - `get_memory_clusters` - Browse semantic memory clusters
1126 | - `get_consolidation_recommendations` - Get AI-powered memory management advice
1127 |
1128 | ### Advanced Configuration
1129 | Fine-tune the consolidation system through environment variables:
1130 | ```bash
1131 | # Archive location (default: ~/.mcp_memory_archive)
1132 | export MCP_CONSOLIDATION_ARCHIVE_PATH=/path/to/archive
1133 |
1134 | # Retention periods (days)
1135 | export MCP_RETENTION_CRITICAL=365 # Critical memories
1136 | export MCP_RETENTION_REFERENCE=180 # Reference materials
1137 | export MCP_RETENTION_STANDARD=30 # Standard memories
1138 | export MCP_RETENTION_TEMPORARY=7 # Temporary memories
1139 |
1140 | # Association discovery settings
1141 | export MCP_ASSOCIATION_MIN_SIMILARITY=0.3 # Sweet spot range
1142 | export MCP_ASSOCIATION_MAX_SIMILARITY=0.7 # for creative connections
1143 |
1144 | # Autonomous scheduling (cron-style)
1145 | export MCP_SCHEDULE_DAILY="02:00" # 2 AM daily
1146 | export MCP_SCHEDULE_WEEKLY="SUN 03:00" # 3 AM on Sundays
1147 | export MCP_SCHEDULE_MONTHLY="01 04:00" # 4 AM on 1st of month
1148 | ```
1149 |
1150 | ### Performance
1151 | - Designed to process 10k+ memories efficiently
1152 | - Automatic hardware optimization (CPU/GPU/MPS)
1153 | - Safe archival system - no data is ever permanently deleted
1154 | - Full recovery capabilities for all archived memories
1155 |
1156 |
1157 | ## 🚀 Service Installation (NEW!)
1158 |
1159 | Install MCP Memory Service as a native system service for automatic startup:
1160 |
1161 | ### Cross-Platform Service Installer
1162 |
1163 | ```bash
1164 | # Install as a service (auto-detects OS)
1165 | python install_service.py
1166 |
1167 | # Start the service
1168 | python install_service.py --start
1169 |
1170 | # Check service status
1171 | python install_service.py --status
1172 |
1173 | # Stop the service
1174 | python install_service.py --stop
1175 |
1176 | # Uninstall the service
1177 | python install_service.py --uninstall
1178 | ```
1179 |
1180 | The installer provides:
1181 | - ✅ **Automatic OS detection** (Windows, macOS, Linux)
1182 | - ✅ **Native service integration** (systemd, LaunchAgent, Windows Service)
1183 | - ✅ **Automatic startup** on boot/login
1184 | - ✅ **Service management commands**
1185 | - ✅ **Secure API key generation**
1186 | - ✅ **Platform-specific optimizations**
1187 |
1188 | For detailed instructions, see the [Service Installation Guide](docs/guides/service-installation.md).
1189 |
1190 | ## Hardware Compatibility
1191 |
1192 | | Platform | Architecture | Accelerator | Status | Notes |
1193 | |----------|--------------|-------------|--------|-------|
1194 | | macOS | Apple Silicon (M1/M2/M3) | MPS | ✅ Fully supported | Best performance |
1195 | | macOS | Apple Silicon under Rosetta 2 | CPU | ✅ Supported with fallbacks | Good performance |
1196 | | macOS | Intel | CPU | ✅ Fully supported | Good with optimized settings |
1197 | | Windows | x86_64 | CUDA | ✅ Fully supported | Best performance |
1198 | | Windows | x86_64 | DirectML | ✅ Supported | Good performance |
1199 | | Windows | x86_64 | CPU | ✅ Supported with fallbacks | Slower but works |
1200 | | Linux | x86_64 | CUDA | ✅ Fully supported | Best performance |
1201 | | Linux | x86_64 | ROCm | ✅ Supported | Good performance |
1202 | | Linux | x86_64 | CPU | ✅ Supported with fallbacks | Slower but works |
1203 | | Linux | ARM64 | CPU | ✅ Supported with fallbacks | Slower but works |
1204 | | Any | Any | No PyTorch | ✅ Supported with SQLite-vec | Limited functionality, very lightweight |
1205 |
1206 | ## Testing
1207 |
1208 | ```bash
1209 | # Install test dependencies
1210 | pip install pytest pytest-asyncio
1211 |
1212 | # Run all tests
1213 | pytest tests/
1214 |
1215 | # Run specific test categories
1216 | pytest tests/test_memory_ops.py
1217 | pytest tests/test_semantic_search.py
1218 | pytest tests/test_database.py
1219 |
1220 | # Verify environment compatibility
1221 | python scripts/verify_environment_enhanced.py
1222 |
1223 | # Verify PyTorch installation on Windows
1224 | python scripts/verify_pytorch_windows.py
1225 |
1226 | # Perform comprehensive installation verification
1227 | python scripts/test_installation.py
1228 | ```
1229 |
1230 | ## FAQ
1231 |
1232 | ### Can I use MCP Memory Service with multiple AI clients simultaneously?
1233 |
1234 | **Yes!** The service features universal multi-client coordination for seamless concurrent access across Claude Desktop, VS Code, Continue, Cursor, and other MCP clients. See the [Local Multi-Client Coordination](#-local-multi-client-coordination) section for details.
1235 |
1236 | ### What's the difference between SQLite-vec and ChromaDB backends?
1237 |
1238 | **SQLite-vec (recommended)**: 10x faster startup, zero network dependencies, 75% less memory usage, single-file database
1239 | **ChromaDB (deprecated)**: Legacy support only, requires network access for models, will be removed in v6.0.0
1240 |
1241 | ➡️ **[Detailed Backend Comparison](#storage-backends)**
1242 |
1243 | ### How do I migrate from ChromaDB to SQLite-vec?
1244 |
1245 | Run the migration script to safely transfer your existing memories:
1246 | ```bash
1247 | python scripts/migrate_to_sqlite_vec.py
1248 | ```
1249 | The process preserves all memories, tags, and metadata while improving performance.
1250 |
1251 | ### Can I deploy MCP Memory Service on a remote server?
1252 |
1253 | **Yes!** The service supports production deployment with HTTP/HTTPS server, API authentication, SSL certificates, and Docker containers. Perfect for teams and cross-device access.
1254 |
1255 | ➡️ **[Remote Server Deployment](#-centralized-server-deployment-recommended)**
1256 |
1257 | ### Why does my installation fail on Apple Silicon Macs?
1258 |
1259 | Use the intelligent installer which handles Apple Silicon optimizations automatically:
1260 | ```bash
1261 | python install.py
1262 | ```
1263 | It detects MPS support, configures fallbacks, and selects compatible PyTorch versions.
1264 |
1265 | ### How much memory and storage does the service use?
1266 |
1267 | **SQLite-vec**: ~50MB RAM for 1K memories, single database file
1268 | **ChromaDB**: ~200MB RAM for 1K memories, multiple files
1269 |
1270 | Storage scales linearly: ~1MB per 1000 memories with SQLite-vec.
1271 |
1272 | ### Is my data secure and private?
1273 |
1274 | **Yes!** All data is stored locally by default. For remote deployments, the service supports API key authentication, HTTPS encryption, and runs in user-space (not as root) for security.
1275 |
1276 | ## Troubleshooting
1277 |
1278 | See the [Installation Guide](docs/installation/master-guide.md) and [Troubleshooting Guide](docs/troubleshooting/general.md) for detailed troubleshooting steps.
1279 |
1280 | ### Quick Troubleshooting Tips
1281 |
1282 | - **Windows PyTorch errors**: Use `python scripts/install_windows.py`
1283 | - **macOS Intel dependency conflicts**: Use `python install.py --force-compatible-deps`
1284 | - **Recursion errors**: Run `python scripts/fix_sitecustomize.py`
1285 | - **Environment verification**: Run `python scripts/verify_environment_enhanced.py`
1286 | - **Memory issues**: Set `MCP_MEMORY_BATCH_SIZE=4` and try a smaller model
1287 | - **Apple Silicon**: Ensure Python 3.10+ built for ARM64, set `PYTORCH_ENABLE_MPS_FALLBACK=1`
1288 | - **Installation testing**: Run `python scripts/test_installation.py`
1289 |
1290 | ## 📚 Comprehensive Documentation
1291 |
1292 | ### Installation & Setup
1293 | - **[Master Installation Guide](docs/installation/master-guide.md)** - Complete installation guide with hardware-specific paths
1294 | - **[Storage Backend Guide](docs/guides/STORAGE_BACKENDS.md)** ⭐ **NEW** - Comprehensive CLI options including multi-client setup
1295 | - **[Multi-Client Setup](docs/integration/multi-client.md)** ⭐ **NEW** - Integrated setup for any MCP application
1296 | - **[Storage Backend Comparison](docs/guides/STORAGE_BACKENDS.md)** - Detailed comparison and selection guide
1297 | - **[Migration Guide](docs/guides/migration.md)** - ChromaDB to SQLite-vec migration instructions
1298 |
1299 | ### Platform-Specific Guides
1300 | - **[Intel Mac Setup Guide](docs/platforms/macos-intel.md)** - Comprehensive guide for Intel Mac users
1301 | - **[Legacy Mac Guide](docs/platforms/macos-intel.md)** - Optimized for 2015 MacBook Pro and older Intel Macs
1302 | - **[Windows Setup](docs/guides/windows-setup.md)** - Windows-specific installation and troubleshooting
1303 | - **[Ubuntu Setup](docs/guides/UBUNTU_SETUP.md)** - Linux server installation guide
1304 |
1305 | ### API & Integration
1306 | - **[HTTP/SSE API](docs/IMPLEMENTATION_PLAN_HTTP_SSE.md)** - New web interface documentation
1307 | - **[Claude Desktop Integration](docs/guides/claude_integration.md)** - Configuration examples
1308 | - **[Integrations](docs/integrations.md)** - Third-party tools and extensions
1309 |
1310 | ### Advanced Topics
1311 | - **[Multi-Client Architecture](docs/development/multi-client-architecture.md)** ⭐ **NEW** - Technical implementation details
1312 | - **[Homebrew PyTorch Integration](docs/integration/homebrew.md)** - Using system PyTorch
1313 | - **[Docker Deployment](docs/deployment/docker.md)** - Container-based deployment
1314 | - **[Performance Optimization](docs/implementation/performance.md)** - Tuning for different hardware
1315 |
1316 | ### Troubleshooting & Support
1317 | - **[General Troubleshooting](docs/troubleshooting/general.md)** - Common issues and solutions
1318 | - **[Hardware Compatibility](docs/DOCUMENTATION_AUDIT.md)** - Compatibility matrix and known issues
1319 |
1320 | ### Quick Commands
1321 | ```bash
1322 | # Get personalized setup recommendations
1323 | python install.py --help-detailed
1324 |
1325 | # Generate hardware-specific setup guide
1326 | python install.py --generate-docs
1327 |
1328 | # Test your installation
1329 | python scripts/test_memory_simple.py
1330 | ```
1331 |
1332 | ## Project Structure
1333 |
1334 | ```
1335 | mcp-memory-service/
1336 | ├── src/mcp_memory_service/ # Core package code
1337 | │ ├── __init__.py
1338 | │ ├── config.py # Configuration utilities
1339 | │ ├── models/ # Data models
1340 | │ ├── storage/ # Storage implementations
1341 | │ ├── utils/ # Utility functions
1342 | │ └── server.py # Main MCP server
1343 | ├── scripts/ # Helper scripts
1344 | ├── memory_wrapper.py # Windows wrapper script
1345 | ├── install.py # Enhanced installation script
1346 | └── tests/ # Test suite
1347 | ```
1348 |
1349 | ## Development Guidelines
1350 |
1351 | - Python 3.10+ with type hints
1352 | - Use dataclasses for models
1353 | - Triple-quoted docstrings for modules and functions
1354 | - Async/await pattern for all I/O operations
1355 | - Follow PEP 8 style guidelines
1356 | - Include tests for new features
1357 |
1358 | ### Git Setup for Contributors
1359 |
1360 | After cloning the repository, run the setup script to configure automated `uv.lock` conflict resolution:
1361 |
1362 | ```bash
1363 | ./scripts/setup-git-merge-drivers.sh
1364 | ```
1365 |
1366 | This enables automatic resolution of `uv.lock` merge conflicts by:
1367 | 1. Using the incoming version to resolve conflicts
1368 | 2. Automatically running `uv sync` to regenerate the lock file
1369 | 3. Ensuring consistent dependency resolution across all environments
1370 |
1371 | The setup is required only once per clone and benefits all contributors by eliminating manual conflict resolution.
1372 |
1373 | ## License
1374 |
1375 | MIT License - See LICENSE file for details
1376 |
1377 | ## Acknowledgments
1378 |
1379 | - ChromaDB team for the vector database
1380 | - Sentence Transformers project for embedding models
1381 | - MCP project for the protocol specification
1382 |
1383 | ## 🎯 Why Sponsor MCP Memory Service?
1384 |
1385 | ## 🏆 In Production
1386 | - Deployed on Glama.ai
1387 | - Managing 300+ enterprise memories
1388 | - Processing queries in <1 second
1389 |
1390 | ### Production Impact
1391 | - **319+ memories** actively managed
1392 | - **828ms** average query response time
1393 | - **100%** cache hit ratio performance
1394 | - **20MB** efficient vector storage
1395 |
1396 | ### Developer Community
1397 | - Complete MCP protocol implementation
1398 | - Cross-platform compatibility
1399 | - React dashboard with real-time statistics
1400 | - Comprehensive documentation
1401 |
1402 | ### Enterprise Features
1403 | - Semantic search with sentence-transformers
1404 | - Tag-based categorization system
1405 | - Automatic backup and optimization
1406 | - Health monitoring dashboard
1407 |
1408 | ## Contact
1409 |
1410 | [Telegram](https://t.me/doobeedoo)
1411 |
1412 | ## Integrations
1413 |
1414 | The MCP Memory Service can be extended with various tools and utilities. See [Integrations](docs/integrations.md) for a list of available options, including:
1415 |
1416 | - [MCP Memory Dashboard](https://github.com/doobidoo/mcp-memory-dashboard) - Web UI for browsing and managing memories
1417 | - [Claude Memory Context](https://github.com/doobidoo/claude-memory-context) - Inject memory context into Claude project instructions
1418 |
```