This is page 1 of 62. 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
│ ├── commands
│ │ ├── README.md
│ │ ├── refactor-function
│ │ ├── refactor-function-prod
│ │ └── refactor-function.md
│ ├── consolidation-fix-handoff.md
│ ├── consolidation-hang-fix-summary.md
│ ├── directives
│ │ ├── agents.md
│ │ ├── code-quality-workflow.md
│ │ ├── consolidation-details.md
│ │ ├── development-setup.md
│ │ ├── hooks-configuration.md
│ │ ├── memory-first.md
│ │ ├── memory-tagging.md
│ │ ├── pr-workflow.md
│ │ ├── quality-system-details.md
│ │ ├── README.md
│ │ ├── refactoring-checklist.md
│ │ ├── storage-backends.md
│ │ └── version-management.md
│ ├── prompts
│ │ └── hybrid-cleanup-integration.md
│ ├── settings.local.json.backup
│ └── settings.local.json.local
├── .commit-message
├── .coveragerc
├── .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-branch-automation.yml
│ ├── claude-code-review.yml
│ ├── claude.yml
│ ├── cleanup-images.yml.disabled
│ ├── dev-setup-validation.yml
│ ├── docker-publish.yml
│ ├── dockerfile-lint.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
├── .metrics
│ ├── baseline_cc_install_hooks.txt
│ ├── baseline_mi_install_hooks.txt
│ ├── baseline_nesting_install_hooks.txt
│ ├── BASELINE_REPORT.md
│ ├── COMPLEXITY_COMPARISON.txt
│ ├── QUICK_REFERENCE.txt
│ ├── README.md
│ ├── REFACTORED_BASELINE.md
│ ├── REFACTORING_COMPLETION_REPORT.md
│ └── TRACKING_TABLE.md
├── .pyscn
│ ├── .gitignore
│ └── reports
│ └── analyze_20251123_214224.html
├── AGENTS.md
├── ai-optimized-tool-descriptions.py
├── 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
│ │ ├── auto-capture-hook.js
│ │ ├── auto-capture-hook.ps1
│ │ ├── memory-retrieval.js
│ │ ├── mid-conversation.js
│ │ ├── permission-request.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-AUTO-CAPTURE.md
│ ├── README-NATURAL-TRIGGERS.md
│ ├── README-PERMISSION-REQUEST.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-permission-request.js
│ │ ├── test-session-tracking.json
│ │ └── test-threading.json
│ ├── utilities
│ │ ├── adaptive-pattern-detector.js
│ │ ├── auto-capture-patterns.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-cache.json
│ │ ├── session-tracker.js
│ │ ├── tiered-conversation-monitor.js
│ │ ├── user-override-detector.js
│ │ └── version-checker.js
│ └── WINDOWS-SESSIONSTART-BUG.md
├── CLAUDE.md
├── CODE_OF_CONDUCT.md
├── COMMIT_MESSAGE.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
│ │ ├── graph-database-design.md
│ │ ├── 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
│ ├── demo-recording-script.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-280-post-mortem.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
│ │ ├── quality-system-configs.md
│ │ └── tag-schema.json
│ ├── features
│ │ └── association-quality-boost.md
│ ├── 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
│ │ ├── memory-quality-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
│ │ └── update-restart-demo.png
│ ├── 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
│ ├── LIGHTWEIGHT_ONNX_SETUP.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
│ │ └── graph-migration-guide.md
│ ├── natural-memory-triggers
│ │ ├── cli-reference.md
│ │ ├── installation-guide.md
│ │ └── performance-optimization.md
│ ├── oauth-setup.md
│ ├── pr-graphql-integration.md
│ ├── quality-system-ui-implementation.md
│ ├── quick-setup-cloudflare-dual-environment.md
│ ├── README.md
│ ├── refactoring
│ │ └── phase-3-3-analysis.md
│ ├── releases
│ │ └── v8.72.0-testing.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
│ │ ├── database-transfer-migration.md
│ │ ├── general.md
│ │ ├── hooks-quick-reference.md
│ │ ├── memory-management.md
│ │ ├── pr162-schema-caching-issue.md
│ │ ├── session-end-hooks.md
│ │ └── sync-issues.md
│ ├── tutorials
│ │ ├── advanced-techniques.md
│ │ ├── data-analysis.md
│ │ └── demo-session-walkthrough.md
│ ├── wiki-documentation-plan.md
│ └── wiki-Graph-Database-Architecture.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
├── IMPLEMENTATION_SUMMARY.md
├── install_service.py
├── install.py
├── LICENSE
├── NOTICE
├── PR_DESCRIPTION.md
├── pyproject.toml
├── pytest.ini
├── README.md
├── release-notes-v8.61.0.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
│ ├── ci
│ │ ├── check_dockerfile_args.sh
│ │ └── validate_imports.sh
│ ├── 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
│ │ ├── add_project_tags.py
│ │ ├── apply_quality_boost_retroactively.py
│ │ ├── assign_memory_types.py
│ │ ├── auto_retag_memory_merge.py
│ │ ├── auto_retag_memory.py
│ │ ├── backfill_graph_table.py
│ │ ├── check_memory_types.py
│ │ ├── cleanup_association_memories_hybrid.py
│ │ ├── cleanup_association_memories.py
│ │ ├── cleanup_corrupted_encoding.py
│ │ ├── cleanup_low_quality.py
│ │ ├── cleanup_memories.py
│ │ ├── cleanup_organize.py
│ │ ├── consolidate_memory_types.py
│ │ ├── consolidation_mappings.json
│ │ ├── delete_orphaned_vectors_fixed.py
│ │ ├── delete_test_memories.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
│ │ ├── retag_valuable_memories.py
│ │ ├── scan_todos.sh
│ │ ├── soft_delete_test_memories.py
│ │ └── sync_status.py
│ ├── 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
│ │ ├── pre_pr_check.sh
│ │ ├── quality_gate.sh
│ │ ├── resolve_threads.sh
│ │ ├── run_pyscn_analysis.sh
│ │ ├── run_quality_checks_on_files.sh
│ │ ├── run_quality_checks.sh
│ │ ├── thread_status.sh
│ │ └── watch_reviews.sh
│ ├── quality
│ │ ├── bulk_evaluate_onnx.py
│ │ ├── check_test_scores.py
│ │ ├── debug_deberta_scoring.py
│ │ ├── export_deberta_onnx.py
│ │ ├── fix_dead_code_install.sh
│ │ ├── migrate_to_deberta.py
│ │ ├── phase1_dead_code_analysis.md
│ │ ├── phase2_complexity_analysis.md
│ │ ├── README_PHASE1.md
│ │ ├── README_PHASE2.md
│ │ ├── rescore_deberta.py
│ │ ├── rescore_fallback.py
│ │ ├── reset_onnx_scores.py
│ │ ├── track_pyscn_metrics.sh
│ │ └── weekly_quality_review.sh
│ ├── README.md
│ ├── run
│ │ ├── memory_wrapper_cleanup.ps1
│ │ ├── memory_wrapper_cleanup.py
│ │ ├── memory_wrapper_cleanup.sh
│ │ ├── README_CLEANUP_WRAPPER.md
│ │ ├── 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
│ │ ├── http_server_manager.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
│ │ └── windows
│ │ ├── add_watchdog_trigger.ps1
│ │ ├── install_scheduled_task.ps1
│ │ ├── manage_service.ps1
│ │ ├── run_http_server_background.ps1
│ │ ├── uninstall_scheduled_task.ps1
│ │ └── update_and_restart.ps1
│ ├── setup-lightweight.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
│ ├── update_and_restart.sh
│ ├── utils
│ │ ├── claude_commands_utils.py
│ │ ├── detect_platform.py
│ │ ├── generate_personalized_claude_md.sh
│ │ ├── groq
│ │ ├── groq_agent_bridge.py
│ │ ├── list-collections.py
│ │ ├── memory_wrapper_uv.py
│ │ ├── query_memories.py
│ │ ├── README_detect_platform.md
│ │ ├── smithery_wrapper.py
│ │ ├── test_groq_bridge.sh
│ │ └── uv_wrapper.py
│ └── validation
│ ├── check_dev_setup.py
│ ├── check_documentation_links.py
│ ├── check_handler_coverage.py
│ ├── diagnose_backend_config.py
│ ├── validate_configuration_complete.py
│ ├── validate_graph_tools.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
│ ├── _version.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
│ ├── quality
│ │ ├── __init__.py
│ │ ├── ai_evaluator.py
│ │ ├── async_scorer.py
│ │ ├── config.py
│ │ ├── implicit_signals.py
│ │ ├── metadata_codec.py
│ │ ├── onnx_ranker.py
│ │ └── scorer.py
│ ├── server
│ │ ├── __init__.py
│ │ ├── __main__.py
│ │ ├── cache_manager.py
│ │ ├── client_detection.py
│ │ ├── environment.py
│ │ ├── handlers
│ │ │ ├── __init__.py
│ │ │ ├── consolidation.py
│ │ │ ├── documents.py
│ │ │ ├── graph.py
│ │ │ ├── memory.py
│ │ │ ├── quality.py
│ │ │ └── utility.py
│ │ └── logging_config.py
│ ├── server_impl.py
│ ├── services
│ │ ├── __init__.py
│ │ └── memory_service.py
│ ├── storage
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── cloudflare.py
│ │ ├── factory.py
│ │ ├── graph.py
│ │ ├── http_client.py
│ │ ├── hybrid.py
│ │ ├── migrations
│ │ │ └── 008_add_graph_table.sql
│ │ └── 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
│ │ ├── directory_ingestion.py
│ │ ├── document_processing.py
│ │ ├── gpu_detection.py
│ │ ├── hashing.py
│ │ ├── health_check.py
│ │ ├── http_server_manager.py
│ │ ├── port_detection.py
│ │ ├── quality_analytics.py
│ │ ├── startup_orchestrator.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
│ │ ├── quality.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
│ ├── i18n
│ │ ├── de.json
│ │ ├── en.json
│ │ ├── es.json
│ │ ├── fr.json
│ │ ├── ja.json
│ │ ├── ko.json
│ │ └── zh.json
│ ├── index.html
│ ├── README.md
│ ├── sse_test.html
│ └── style.css
├── start_http_debug.bat
├── start_http_server.sh
├── test_document.txt
├── test_version_checker.js
├── TESTING_NOTES.md
├── 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
│ │ └── test_graph_modes.py
│ ├── contracts
│ │ └── api-specification.yml
│ ├── integration
│ │ ├── conftest.py
│ │ ├── HANDLER_COVERAGE_REPORT.md
│ │ ├── package-lock.json
│ │ ├── package.json
│ │ ├── test_all_memory_handlers.py
│ │ ├── 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
│ ├── storage
│ │ ├── conftest.py
│ │ └── test_graph_storage.py
│ ├── test_client.py
│ ├── test_content_splitting.py
│ ├── test_database.py
│ ├── test_deberta_quality.py
│ ├── test_fallback_quality.py
│ ├── test_graph_traversal.py
│ ├── test_hybrid_cloudflare_limits.py
│ ├── test_hybrid_storage.py
│ ├── test_lightweight_onnx.py
│ ├── test_memory_ops.py
│ ├── test_memory_wrapper_cleanup.py
│ ├── test_quality_integration.py
│ ├── test_quality_system.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_imports.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
│ └── test_uv_no_pip_installer_fallback.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
└── verify_compression.sh
```
# Files
--------------------------------------------------------------------------------
/.envnn#:
--------------------------------------------------------------------------------
```
1 |
```
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
```
1 | # Auto-resolve lock file conflicts and regenerate lock file
2 | uv.lock merge=uv-lock-merge
```
--------------------------------------------------------------------------------
/.env.sqlite.backup:
--------------------------------------------------------------------------------
```
1 | # SQLite-vec Configuration for MCP Memory Service (Backup)
2 | MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
3 | MCP_MEMORY_SQLITE_PATH=/home/hkr/.local/share/mcp-memory/primary_sqlite_vec.db
4 |
```
--------------------------------------------------------------------------------
/.pyscn/.gitignore:
--------------------------------------------------------------------------------
```
1 | # pyscn generated files
2 |
3 | # Analysis reports (HTML, JSON)
4 | reports/
5 |
6 | # Historical metrics tracking
7 | history/
8 |
9 | # Temporary analysis files
10 | *.tmp
11 | *.log
12 |
13 | # Keep directory structure
14 | !.gitignore
15 |
```
--------------------------------------------------------------------------------
/.mcp.json.template:
--------------------------------------------------------------------------------
```
1 | {
2 | "mcpServers": {
3 | "memory-service": {
4 | "type": "stdio",
5 | "command": "python",
6 | "args": ["scripts/run_memory_server.py"],
7 | "env": {
8 | "MCP_MEMORY_CHROMA_PATH": "{{USER_HOME}}/.mcp_memory_chroma",
9 | "LOG_LEVEL": "INFO",
10 | "MCP_TIMEOUT": "30000"
11 | }
12 | }
13 | }
14 | }
```
--------------------------------------------------------------------------------
/.mcp.json.backup:
--------------------------------------------------------------------------------
```
1 | {
2 | "mcpServers": {
3 | "memory-service": {
4 | "type": "stdio",
5 | "command": "python",
6 | "args": [
7 | "scripts/run_memory_server.py"
8 | ],
9 | "env": {
10 | "MCP_MEMORY_CHROMA_PATH": "/home/hkr/.mcp_memory_chroma",
11 | "LOG_LEVEL": "INFO",
12 | "MCP_TIMEOUT": "30000"
13 | }
14 | },
15 | "memory": {
16 | "command": "uv",
17 | "args": [
18 | "--directory",
19 | "/home/hkr/repositories/mcp-memory-service",
20 | "run",
21 | "memory"
22 | ],
23 | "env": {
24 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
25 | "MCP_MEMORY_SQLITE_PRAGMAS": "busy_timeout=15000,cache_size=20000",
26 | "LOG_LEVEL": "INFO"
27 | }
28 | }
29 | }
30 | }
```
--------------------------------------------------------------------------------
/.dockerignore:
--------------------------------------------------------------------------------
```
1 | # Virtual Environments
2 | .venv/
3 | venv/
4 | py310_venv/
5 | venv_py310/
6 | env/
7 | .env
8 | .Python
9 |
10 | # Python Cache Files
11 | __pycache__/
12 | *.py[cod]
13 | *$py.class
14 | *.so
15 | .pytest_cache/
16 | .tox/
17 | .coverage
18 | coverage.*
19 | .cache/
20 | .hypothesis/
21 |
22 | # Git Repository
23 | .git/
24 | .gitignore
25 |
26 | # Build Artifacts
27 | build/
28 | develop-eggs/
29 | dist/
30 | downloads/
31 | eggs/
32 | .eggs/
33 | lib/
34 | lib64/
35 | parts/
36 | sdist/
37 | var/
38 | wheels/
39 | *.egg-info/
40 | .installed.cfg
41 | *.egg
42 | __pypackages__/
43 |
44 | # Development Files
45 | *.log
46 | *.bak
47 | *.tmp
48 | *.old
49 | *.swp
50 | *.swo
51 | test_output.txt
52 | dxdiag_output.txt
53 | dxdiag.txt
54 | development_notes.md
55 | migration_*.log
56 | deploy_test*.sh
57 |
58 | # IDE and Editor Files
59 | .vscode/
60 | .idea/
61 | .codegpt/
62 |
63 | # OS Specific Files
64 | .DS_Store
65 | .AppleDouble
66 | .LSOverride
67 | Thumbs.db
68 | Desktop.ini
69 |
70 | # Database and Storage Directories
71 | chroma_db/
72 | .mcp_memory_chroma/
73 | .mcp_memory_sqlite/
74 | *.sqlite
75 | *.sqlite-*
76 | *.sqlite3
77 | backups/
78 |
79 | # Configuration Files (may contain sensitive data)
80 | claude_desktop_config_updated.json
81 | claude_config/
82 | .claude/
83 | .mcp.json
84 | CLAUDE_MEMORY.md
85 | *_reference_memories_*.json
86 |
87 | # Test Artifacts
88 | tests/test_db/
89 | /tmp/test_mcp*.py
90 | test_mcp*.py
91 | debug_mcp*.py
92 | *_test.py.old
93 | test_*.py.backup
94 | *.cover
95 | nosetests.xml
96 | coverage.xml
97 |
98 | # Temporary and Personal Files
99 | YOUR_PERSONALIZED_SETUP_GUIDE.md
100 | CLAUDE_PERSONALIZED.md
101 | *_old
102 | *_backup
103 |
104 | # Aider and AI Tools
105 | .aider.*
106 |
107 | # Documentation Build Artifacts
108 | docs/_build/
109 | docs/site/
110 |
111 | # Archive Directories
112 | archive/
```
--------------------------------------------------------------------------------
/.coveragerc:
--------------------------------------------------------------------------------
```
1 | [run]
2 | source = src/mcp_memory_service
3 | omit =
4 | # OAuth system - no tests yet (Issue #316)
5 | */web/oauth/*
6 | # Web infrastructure - minimal test coverage
7 | */web/app.py
8 | */web/sse.py
9 | # Web API endpoints - minimal test coverage
10 | */web/api/*
11 | */web/dependencies.py
12 | # Sync infrastructure - no tests
13 | */sync/*
14 | # Backup/scheduler - infrastructure code
15 | */backup/scheduler.py
16 | */consolidation/scheduler.py
17 | # CLI commands - minimal coverage
18 | */cli/*
19 | # API client layer - infrastructure code
20 | */api/client.py
21 | */api/operations.py
22 | */api/sync_wrapper.py
23 | # Ingestion system - minimal coverage
24 | */ingestion/*
25 | # Discovery system - infrastructure code
26 | */discovery/*
27 | # Utility modules - infrastructure code
28 | */utils/cache_manager.py
29 | */utils/directory_ingestion.py
30 | */utils/health_check.py
31 | */utils/http_server_manager.py
32 | */utils/port_detection.py
33 | */utils/quality_analytics.py
34 | */utils/startup_orchestrator.py
35 | */utils/time_parser.py
36 | */utils/gpu_detection.py
37 | */utils/db_utils.py
38 | */utils/content_splitter.py
39 | */utils/debug.py
40 | # HTTP client - minimal usage
41 | */storage/http_client.py
42 | # CLI utilities
43 | */cli/utils.py
44 | # CLI entry points
45 | */__main__.py
46 | */mcp_server.py
47 |
48 | [report]
49 | precision = 2
50 | show_missing = true
51 | skip_covered = false
52 | exclude_lines =
53 | pragma: no cover
54 | def __repr__
55 | if TYPE_CHECKING:
56 | raise AssertionError
57 | raise NotImplementedError
58 | if __name__ == .__main__.:
59 | @(abc\.)?abstractmethod
60 |
```
--------------------------------------------------------------------------------
/.commit-message:
--------------------------------------------------------------------------------
```
1 | fix: address Gemini code review feedback (PR #209)
2 |
3 | CRITICAL FIXES:
4 | 1. Fix async/await issue in operations.py health() function
5 | - Changed get_storage() to await get_storage_async()
6 | - Ensures proper async execution throughout call stack
7 |
8 | 2. Fix hardcoded macOS path in client.py
9 | - Replaced ~/Library/Application Support with cross-platform get_base_directory()
10 | - Works on macOS, Linux, and Windows
11 |
12 | DOCUMENTATION IMPROVEMENTS:
13 | 3. Replace Unicode multiplication symbols (x) with ASCII (x)
14 | - Fixed 6 documentation files for better compatibility
15 | - Prevents encoding issues in terminals and editors
16 |
17 | 4. Replace absolute local paths with relative repo paths
18 | - Removed /Users/hkr/Documents/GitHub/mcp-memory-service/
19 | - Now uses relative paths (src/, docs/)
20 |
21 | RESOURCE MANAGEMENT:
22 | 5. Add explicit close() and close_async() methods
23 | - Proper resource cleanup for storage backends
24 | - Sync and async versions for different contexts
25 | - Exported in public API
26 |
27 | NEW FEATURES:
28 | 6. Write 5-minute migration guide
29 | - Located at docs/migration/code-execution-api-quick-start.md
30 | - Covers fresh install and upgrade paths
31 | - Includes troubleshooting and ROI calculator
32 |
33 | 7. Enable code execution by default in installer
34 | - Auto-detects Python path (python3 for Unix, python for Windows)
35 | - Adds codeExecution config to hooks
36 | - Updates both generate_basic_config() and generate_hooks_config_from_mcp()
37 | - Success messaging shows 75-90% token reduction benefits
38 |
39 | TESTING:
40 | - API tests pass (23/42 passing, 19 failures are pre-existing database duplicates)
41 | - Manual validation confirms health() works correctly
42 | - Cross-platform path handling verified
43 |
44 | FILES CHANGED:
45 | - src/mcp_memory_service/api/operations.py (async fix)
46 | - src/mcp_memory_service/api/client.py (paths + close methods)
47 | - src/mcp_memory_service/api/__init__.py (export close functions)
48 | - claude-hooks/install_hooks.py (code execution config)
49 | - claude-hooks/config.json (add codeExecution section)
50 | - docs/migration/code-execution-api-quick-start.md (NEW)
51 | - docs/api/* (Unicode + path fixes)
52 | - docs/research/* (Unicode + path fixes)
53 |
54 | Ready for PR #209 merge.
55 |
56 | Generated with Claude Code
57 |
58 | Co-Authored-By: Claude <[email protected]>
59 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 |
2 | # Windows device name artifacts (created when running Windows commands in Git Bash)
3 | nul
4 | NUL
5 | con
6 | CON
7 | aux
8 | AUX
9 | prn
10 | PRN
11 |
12 | # Aider files
13 | .aider.*
14 |
15 | # Private/sensitive documents
16 | docs/saas-monetization-strategy.md
17 |
18 | # Local memory exports (contain sensitive data)
19 | local_export*.json
20 |
21 | # Python
22 | __pycache__/
23 | *.py[cod]
24 | *$py.class
25 | *.so
26 |
27 | # Python environment & build artifacts
28 | .Python
29 | env/
30 | .venv/
31 | venv/
32 | py310_venv/
33 | venv_py310/
34 | .uv/
35 | build/
36 | develop-eggs/
37 | dist/
38 | downloads/
39 | eggs/
40 | .eggs/
41 | lib/
42 | lib64/
43 | !scripts/pr/lib/
44 | parts/
45 | sdist/
46 | var/
47 | wheels/
48 | *.egg-info/
49 | .installed.cfg
50 | *.egg
51 |
52 | # Python project tools
53 | pip-wheel-metadata/
54 | __pypackages__/
55 |
56 | # Virtual Environment activation files (redundant due to .venv/ but explicit if needed)
57 | .env
58 | .env.local
59 | .env.development
60 | .env.test
61 | .env.production
62 | # But include template files
63 | !.env.example
64 |
65 | # IDEs & Editors
66 | .idea/
67 | .vscode/
68 | *.swp
69 | *.swo
70 |
71 | # OS-specific files
72 | .DS_Store
73 | .AppleDouble
74 | .LSOverride
75 |
76 | # CodeGPT / Extensions
77 | .codegpt/
78 |
79 | # ChromaDB artifacts
80 | chroma_db/
81 | tests/test_db/chroma.sqlite3
82 |
83 | # SQLite-vec artifacts
84 | *.sqlite
85 | *.sqlite-*
86 | .mcp_memory_sqlite/
87 | .mcp_memory_chroma/
88 |
89 | # pyscn analysis artifacts (reports and history tracked in .pyscn/.gitignore)
90 | .pyscn/reports/
91 | .pyscn/history/
92 |
93 | # Quality analysis reports
94 | reports/
95 |
96 | # Project-specific artifacts
97 | backups/
98 | test_output.txt
99 | dxdiag_output.txt
100 | dxdiag.txt
101 | claude_desktop_config_updated.json
102 | claude_config/claude_desktop_config.json
103 |
104 | # Remove these if mistakenly included
105 | =1.0.0,
106 | =11.0.3
107 | =*.*.*
108 | **vX.Y.Z**
109 | **vX.Y.Z**:
110 | timestamp
111 | updated_at
112 |
113 | # Logs and debugging
114 | *.log
115 | *.bak
116 | *.tmp
117 | *.old
118 |
119 | # Claude hooks runtime cache
120 | claude-hooks/utilities/session-cache.json
121 |
122 | # Test and development artifacts
123 | test_*.py.backup
124 | *_test.py.old
125 | development_notes.md
126 |
127 | # Temporary MCP test files
128 | /tmp/test_mcp*.py
129 | test_mcp*.py
130 | debug_mcp*.py
131 |
132 | # Migration artifacts
133 | migration_*.log
134 | deploy_test*.sh
135 |
136 | # Optional: VSCode debugging & Python caches
137 | *.coverage
138 | coverage.*
139 | .cache/
140 | .pytest_cache/
141 | .tox/
142 | nosetests.xml
143 | coverage.xml
144 | *.cover
145 | .hypothesis/
146 | claude_config/claude_desktop_config.json
147 | .claude/mcp_config.json
148 |
149 | # Personalized setup guides (generated locally)
150 | YOUR_PERSONALIZED_SETUP_GUIDE.md
151 | .mcp.json
152 |
153 | # Local memory service configuration (contains private endpoints/keys)
154 | CLAUDE_MEMORY.md
155 | *_reference_memories_*.json
156 |
157 | # Claude Code local settings (personal configurations)
158 | .claude/settings.local.json*
159 | scripts/.claude/settings.local.json*
160 |
161 | # Amp CLI Bridge (entire directory - user-specific working space)
162 | .claude/amp/
163 |
164 | # Personal files
165 | CLAUDE_PERSONALIZED.md
166 | CLAUDE.local.md
167 | SESSION_MEMORY_2025-08-11.md
168 |
169 | # Context crystallizer artifacts
170 | .context-crystallizer/
171 |
172 | # Git tools
173 | .git-rewrite/
174 |
175 | # Node.js dependencies and artifacts
176 | node_modules/
177 | npm-debug.log*
178 | yarn-debug.log*
179 | yarn-error.log*
180 | package-lock.json
181 | .npm
182 | .mcp.json.disabled
183 | data/
184 |
185 | # GitHub wiki clone (managed separately)
186 | .wiki/
187 |
188 | # Keep directory structure but ignore content
189 | !.claude/amp/prompts/pending/.gitkeep
190 | !.claude/amp/responses/ready/.gitkeep
191 | !.claude/amp/responses/consumed/.gitkeep
192 | .local/
193 |
194 | # Social media posts
195 | social-media/
196 |
197 | # Python version compatibility marker
198 | venv/.python312_compat
199 |
```
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
```
1 | # Cloudflare Configuration for MCP Memory Service
2 | # ================================================
3 | # Copy this file to .env and replace with your actual credentials
4 | #
5 | # Setup Instructions:
6 | # 1. Copy this file: cp .env.example .env
7 | # 2. Create Cloudflare API Token at: https://dash.cloudflare.com/profile/api-tokens
8 | # 3. Replace placeholder values below with your actual credentials
9 | # 4. Never commit your .env file to git (it's already in .gitignore)
10 |
11 | # =============================================================================
12 | # REQUIRED: Cloudflare API Token
13 | # =============================================================================
14 | # Create at: https://dash.cloudflare.com/profile/api-tokens
15 | # Required permissions:
16 | # - Account: Cloudflare Workers:Edit
17 | # - Zone Resources: Include All zones
18 | # - Account Resources: Include All accounts
19 | #
20 | # IMPORTANT: Test your token with the account-scoped endpoint:
21 | # curl "https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/tokens/verify" \
22 | # -H "Authorization: Bearer {YOUR_TOKEN}"
23 | #
24 | # DO NOT use the generic endpoint (will fail for scoped tokens):
25 | # curl "https://api.cloudflare.com/client/v4/user/tokens/verify" ❌
26 | CLOUDFLARE_API_TOKEN=your-cloudflare-api-token-here
27 |
28 | # =============================================================================
29 | # REQUIRED: Cloudflare Account ID
30 | # =============================================================================
31 | # Find in: Cloudflare Dashboard > Right sidebar under "Account ID"
32 | # Example: be0e35a26715043ef8df90253268c33f
33 | CLOUDFLARE_ACCOUNT_ID=your-account-id-here
34 |
35 | # =============================================================================
36 | # REQUIRED: D1 Database ID
37 | # =============================================================================
38 | # Create with: wrangler d1 create mcp-memory-database
39 | # Or find existing: wrangler d1 list
40 | # Example: f745e9b4-ba8e-4d47-b38f-12af91060d5a
41 | CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id-here
42 |
43 | # =============================================================================
44 | # REQUIRED: Vectorize Index Name
45 | # =============================================================================
46 | # Create with: wrangler vectorize create mcp-memory-index --dimensions=384
47 | # Or find existing: wrangler vectorize list
48 | # Example: mcp-memory-index
49 | CLOUDFLARE_VECTORIZE_INDEX=your-vectorize-index-name
50 |
51 | # =============================================================================
52 | # OPTIONAL: R2 Bucket for Large Content Storage
53 | # =============================================================================
54 | # Create with: wrangler r2 bucket create mcp-memory-content
55 | # Only needed if you plan to store large content (>1MB)
56 | # CLOUDFLARE_R2_BUCKET=mcp-memory-content
57 |
58 | # =============================================================================
59 | # STORAGE BACKEND CONFIGURATION
60 | # =============================================================================
61 | # Options: sqlite_vec | cloudflare | hybrid
62 | # - sqlite_vec: Fast local storage (development)
63 | # - cloudflare: Cloud storage with Cloudflare (production)
64 | # - hybrid: Best of both - local speed + cloud persistence (recommended)
65 | MCP_MEMORY_STORAGE_BACKEND=cloudflare
66 |
67 | # =============================================================================
68 | # OPTIONAL: Advanced Configuration
69 | # =============================================================================
70 |
71 | # Cloudflare embedding model (default is recommended)
72 | # CLOUDFLARE_EMBEDDING_MODEL=@cf/baai/bge-base-en-v1.5
73 |
74 | # Large content threshold for R2 storage (bytes)
75 | # CLOUDFLARE_LARGE_CONTENT_THRESHOLD=1048576
76 |
77 | # HTTP Interface (Web Dashboard)
78 | # NOTE: The HTTP dashboard is a SEPARATE server from the MCP server.
79 | # To start the dashboard: uv run python scripts/server/run_http_server.py
80 | # Or use Windows Task Scheduler: scripts/service/windows/install_scheduled_task.ps1
81 | MCP_HTTP_ENABLED=true
82 | MCP_HTTP_PORT=8000
83 | # MCP_HTTPS_ENABLED=true
84 | # MCP_HTTPS_PORT=8443
85 |
86 | # OAuth 2.1 Authentication (for web interface)
87 | # MCP_OAUTH_ENABLED=false
88 |
89 | # Hybrid Backend Configuration (if using hybrid)
90 | # MCP_HYBRID_SYNC_INTERVAL=300 # Sync every 5 minutes
91 | # MCP_HYBRID_BATCH_SIZE=50 # Sync 50 operations at a time
92 | # MCP_HYBRID_SYNC_ON_STARTUP=true # Initial sync on startup
93 |
94 | # Offline Mode (for air-gapped deployments)
95 | # MCP_MEMORY_OFFLINE=1 # Prevent HuggingFace model downloads
96 | # Note: Models must be pre-cached before enabling
97 | # First install downloads models automatically
98 |
99 | # =============================================================================
100 | # GRAPH DATABASE CONFIGURATION (v8.51.0+)
101 | # =============================================================================
102 | # Controls how memory associations are stored
103 | # Options:
104 | # - memories_only: Store in memories.metadata.associations (backward compatible, v8.48.0 behavior)
105 | # - dual_write: Write to both memories.metadata AND memory_graph table (migration mode, default)
106 | # - graph_only: Write to memory_graph table only (future mode, requires migration complete)
107 | #
108 | # Migration Path:
109 | # 1. Start with dual_write (default) - maintains compatibility while building graph data
110 | # 2. Run migration script to backfill memory_graph from existing associations
111 | # 3. Validate graph data completeness
112 | # 4. Switch to graph_only mode after validation
113 | #
114 | # Benefits of graph_only mode:
115 | # - 5-10x faster association queries (indexed graph table vs JSON metadata parsing)
116 | # - Efficient bidirectional traversal (A→B and B→A)
117 | # - Support for multiple connection types (semantic, temporal, causal, thematic)
118 | # - Foundation for advanced graph analytics (PageRank, clustering, path finding)
119 | #
120 | MCP_GRAPH_STORAGE_MODE=dual_write
121 |
122 | # =============================================================================
123 | # TROUBLESHOOTING
124 | # =============================================================================
125 | # Common issues:
126 | # 1. "Invalid API Token" - Check token permissions and expiry
127 | # 2. "Database not found" - Verify D1 database ID is correct
128 | # 3. "Vectorize index not found" - Check index name and dimensions (384)
129 | # 4. "Account access denied" - Ensure API token has account permissions
130 | #
131 | # Documentation: https://github.com/doobidoo/mcp-memory-service/wiki
132 | # Support: https://github.com/doobidoo/mcp-memory-service/issues
```
--------------------------------------------------------------------------------
/tests/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP-MEMORY-SERVICE Tests
2 |
3 | This directory contains tests for the MCP-MEMORY-SERVICE project.
4 |
5 | ## Directory Structure
6 |
7 | - `integration/` - Integration tests between components
8 | - `unit/` - Unit tests for individual components
9 | - `performance/` - Performance benchmarks
10 |
11 | ## Running Tests
12 |
13 | ```bash
14 | # Run all tests
15 | pytest
16 |
17 | # Run specific test category
18 | pytest tests/unit/
19 | pytest tests/integration/
20 | pytest tests/performance/
21 | ```
22 |
```
--------------------------------------------------------------------------------
/archive/setup-development/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Development Files Archive
2 |
3 | This directory contains files used during the development and setup process:
4 |
5 | ## 📁 Archived Files
6 |
7 | - **`setup_consolidation_mdns.sh`** - Original manual startup script (superseded by systemd service)
8 | - **`test_service.sh`** - Debug script for troubleshooting service startup issues
9 | - **`STARTUP_SETUP_GUIDE.md`** - Original startup guide (superseded by COMPLETE_SETUP_GUIDE.md)
10 |
11 | ## 🔄 Superseded By
12 |
13 | These files were used during development but are now superseded by:
14 |
15 | - **Production Service**: `mcp-memory.service` + `service_control.sh`
16 | - **Complete Documentation**: `COMPLETE_SETUP_GUIDE.md`
17 | - **Quick Start**: `README_PRODUCTION.md`
18 |
19 | ## 🗂️ Purpose
20 |
21 | These files are kept for:
22 | - Historical reference
23 | - Debugging if needed
24 | - Understanding the development process
25 | - Potential future troubleshooting
26 |
27 | **Note**: Use the production files in the root directory for normal operation.
```
--------------------------------------------------------------------------------
/tools/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Development Tools and Utilities
2 |
3 | This directory contains development tools, build utilities, and deployment configurations for MCP Memory Service.
4 |
5 | ## Directory Structure
6 |
7 | ### `/build/` - Build Tools
8 | - `setup.py` - Python package build configuration
9 | - Build scripts and packaging utilities
10 |
11 | ### `/deployments/` - Deployment Tools
12 | - `cloudflare/` - Cloudflare Workers deployment configuration
13 | - Cloud platform deployment scripts and configurations
14 |
15 | ### `/docker/` - Docker Tools
16 | - Multiple Docker configurations and Dockerfiles
17 | - Docker Compose files for different deployment scenarios
18 | - Docker utility scripts and entrypoints
19 |
20 | ## Usage
21 |
22 | ### Build Tools
23 | ```bash
24 | # Build Python package
25 | cd tools/build
26 | python setup.py sdist bdist_wheel
27 | ```
28 |
29 | ### Docker Deployment
30 | ```bash
31 | # Use various Docker configurations
32 | cd tools/docker
33 | docker-compose -f docker-compose.yml up
34 | docker-compose -f docker-compose.standalone.yml up
35 | ```
36 |
37 | ### Cloudflare Workers
38 | ```bash
39 | # Deploy to Cloudflare Workers
40 | cd tools/deployments/cloudflare
41 | npm install
42 | wrangler deploy
43 | ```
44 |
45 | ## Related Documentation
46 |
47 | - [Docker Deployment Guide](../docs/deployment/docker.md) - Comprehensive Docker setup
48 | - [Installation Guide](../docs/installation/master-guide.md) - General installation
49 | - [Development Guide](../docs/technical/development.md) - Development setup
```
--------------------------------------------------------------------------------
/docs/assets/images/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Screenshots
2 |
3 | This directory contains screenshots and visual assets for the MCP Memory Service documentation.
4 |
5 | ## Dashboard Screenshots
6 |
7 | ### v3.3.0 Dashboard Features
8 |
9 | The modern dashboard includes:
10 |
11 | 
12 |
13 | **Key Features:**
14 | - **Modern Design**: Gradient backgrounds with professional card layout
15 | - **Live Statistics**: Real-time server metrics including:
16 | - Total memories count
17 | - Embedding model information
18 | - Server health status
19 | - Response time metrics
20 | - **Interactive Endpoints**: Organized API documentation with hover effects
21 | - **Tech Stack Badges**: Visual representation of FastAPI, SQLite-vec, PyTorch, etc.
22 | - **Responsive Layout**: Works on desktop and mobile devices
23 | - **Auto-Refresh**: Stats update every 30 seconds
24 |
25 | ## Access URLs
26 |
27 | - **Dashboard**: http://localhost:8000
28 | - **mDNS**: http://mcp-memory-service.local:8000
29 | - **API Docs**: http://localhost:8000/api/docs
30 | - **ReDoc**: http://localhost:8000/api/redoc
31 |
32 | ## Screenshot Instructions
33 |
34 | To capture the dashboard for documentation:
35 |
36 | 1. Ensure the HTTP server is running: `python scripts/run_http_server.py`
37 | 2. Wait for stats to load (shows actual memory count)
38 | 3. Take full-page screenshot at 1920x1080 resolution
39 | 4. Save as `dashboard-v3.3.0.png` in this directory
40 | 5. Update README.md references accordingly
41 |
42 | ## File Naming Convention
43 |
44 | - `dashboard-v{version}.png` - Main dashboard screenshots
45 | - `api-docs-v{version}.png` - API documentation screenshots
46 | - `mobile-v{version}.png` - Mobile responsive views
47 | - `feature-{name}-v{version}.png` - Specific feature screenshots
```
--------------------------------------------------------------------------------
/.claude/directives/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Directives
2 |
3 | This directory contains modular directive files that supplement CLAUDE.md with specific behavioral rules and conventions.
4 |
5 | ## Purpose
6 |
7 | - **Keep CLAUDE.md concise** - Move detailed directives here
8 | - **Organize by topic** - Each file covers a specific concern
9 | - **Easy to reference** - Claude can read specific directives when needed
10 | - **Maintainable** - Update directives without bloating main file
11 |
12 | ## Available Directives
13 |
14 | ### Core Directives (Always Apply)
15 |
16 | - **memory-tagging.md** - CRITICAL: How to tag memories correctly for this project
17 |
18 | ### Reference Directives (Read When Needed)
19 |
20 | - *(Add more as needed - examples below)*
21 | - `release-workflow.md` - Version management, changelog updates, PR workflow
22 | - `code-quality.md` - Quality standards, complexity limits, pre-commit checks
23 | - `testing.md` - Test requirements, coverage expectations
24 | - `documentation.md` - When/where to document (CHANGELOG vs Wiki vs CLAUDE.md)
25 |
26 | ## How This Works
27 |
28 | ### In CLAUDE.md
29 |
30 | ```markdown
31 | ## Directives
32 |
33 | **IMPORTANT**: Read `.claude/directives/memory-tagging.md` before storing any memories manually.
34 |
35 | For detailed directives on specific topics, see `.claude/directives/` directory.
36 | ```
37 |
38 | ### When You Need Guidance
39 |
40 | ```bash
41 | # Claude automatically reads directives when relevant
42 | # Or explicitly request:
43 | "Check the release workflow directive before creating a release"
44 | "What does the memory tagging directive say?"
45 | ```
46 |
47 | ## Structure Guidelines
48 |
49 | Each directive file should:
50 | 1. **Start with context** - Why this directive exists
51 | 2. **Provide clear rules** - What to do, what NOT to do
52 | 3. **Include examples** - Show correct and incorrect usage
53 | 4. **Explain consequences** - What breaks if not followed
54 | 5. **Keep it concise** - 50-100 lines max per file
55 |
56 | ## Benefits
57 |
58 | ✅ **CLAUDE.md stays focused** - High-level overview and essential commands
59 | ✅ **Directives are discoverable** - Organized by topic
60 | ✅ **Easy to update** - Change one file without context switching
61 | ✅ **Context-aware** - Claude reads relevant directives when needed
62 | ✅ **Version controlled** - Track directive changes over time
63 |
```
--------------------------------------------------------------------------------
/tools/docker/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Docker Setup for MCP Memory Service
2 |
3 | ## 🚀 Quick Start
4 |
5 | Choose your mode:
6 |
7 | ### MCP Protocol Mode (for Claude Desktop, VS Code)
8 | ```bash
9 | docker-compose up -d
10 | ```
11 |
12 | ### HTTP API Mode (for REST API, Web Dashboard)
13 | ```bash
14 | docker-compose -f docker-compose.http.yml up -d
15 | ```
16 |
17 | ## 📝 What's New (v5.0.4)
18 |
19 | Thanks to feedback from Joe Esposito, we've completely simplified the Docker setup:
20 |
21 | ### ✅ Fixed Issues
22 | - **PYTHONPATH** now correctly set to `/app/src`
23 | - **run_server.py** properly copied for HTTP mode
24 | - **Embedding models** pre-downloaded during build (no runtime failures)
25 |
26 | ### 🎯 Simplified Structure
27 | - **2 clear modes** instead of 4 confusing variants
28 | - **Unified entrypoint** that auto-detects mode
29 | - **Single Dockerfile** for all configurations
30 |
31 | ## 🔧 Configuration
32 |
33 | ### Environment Variables
34 |
35 | | Variable | Description | Default |
36 | |----------|-------------|---------|
37 | | `MCP_MODE` | Operation mode: `mcp` or `http` | `mcp` |
38 | | `MCP_API_KEY` | API key for HTTP mode | `your-secure-api-key-here` |
39 | | `HTTP_PORT` | Host port for HTTP mode | `8000` |
40 | | `LOG_LEVEL` | Logging level | `INFO` |
41 |
42 | ### Volume Mounts
43 |
44 | All data is stored in a single `./data` directory:
45 | - SQLite database: `./data/sqlite_vec.db`
46 | - Backups: `./data/backups/`
47 |
48 | ## 🧪 Testing
49 |
50 | Run the test script to verify both modes work:
51 | ```bash
52 | ./test-docker-modes.sh
53 | ```
54 |
55 | ## 📊 HTTP Mode Endpoints
56 |
57 | When running in HTTP mode:
58 | - **Dashboard**: http://localhost:8000/
59 | - **API Docs**: http://localhost:8000/api/docs
60 | - **Health Check**: http://localhost:8000/api/health
61 |
62 | ## 🔄 Migration from Old Setup
63 |
64 | If you were using the old Docker files:
65 |
66 | | Old File | New Alternative |
67 | |----------|-----------------|
68 | | `docker-compose.standalone.yml` | Use `docker-compose.http.yml` |
69 | | `docker-compose.uv.yml` | UV is now built-in |
70 | | `docker-compose.pythonpath.yml` | Fixed in main Dockerfile |
71 |
72 | See [DEPRECATED.md](./DEPRECATED.md) for details.
73 |
74 | ## 🐛 Troubleshooting
75 |
76 | ### Container exits immediately
77 | - For HTTP mode: Check logs with `docker-compose -f docker-compose.http.yml logs`
78 | - Ensure `MCP_MODE=http` is set in environment
79 |
80 | ### Cannot connect to HTTP endpoints
81 | - Verify container is running: `docker ps`
82 | - Check port mapping: `docker port <container_name>`
83 | - Test health: `curl http://localhost:8000/api/health`
84 |
85 | ### Embedding model errors
86 | - Models are pre-downloaded during build
87 | - If issues persist, rebuild: `docker-compose build --no-cache`
88 |
89 | ## 🙏 Credits
90 |
91 | Special thanks to **Joe Esposito** for identifying and helping fix the Docker setup issues!
```
--------------------------------------------------------------------------------
/examples/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Examples
2 |
3 | This directory contains example configurations, scripts, and setup utilities for deploying MCP Memory Service in various scenarios.
4 |
5 | ## Directory Structure
6 |
7 | ### `/config/` - Configuration Examples
8 | - Example Claude Desktop configurations
9 | - Template configuration files for different deployment scenarios
10 | - MCP server configuration samples
11 |
12 | ### `/setup/` - Setup Scripts and Utilities
13 | - Multi-client setup scripts
14 | - Automated configuration tools
15 | - Installation helpers
16 |
17 | ## Core Files
18 |
19 | ### `http-mcp-bridge.js`
20 | A Node.js script that bridges MCP JSON-RPC protocol to HTTP REST API calls. This allows MCP clients like Claude Desktop to connect to a remote HTTP server instead of running a local instance.
21 |
22 | **Usage:**
23 | 1. Configure your server endpoint and API key as environment variables
24 | 2. Use this script as the MCP server command in your client configuration
25 |
26 | ### `claude-desktop-http-config.json`
27 | Example Claude Desktop configuration for connecting to a remote MCP Memory Service HTTP server via the bridge script.
28 |
29 | **Setup:**
30 | 1. Update the path to `http-mcp-bridge.js`
31 | 2. Set your server endpoint URL
32 | 3. Add your API key (if authentication is enabled)
33 | 4. Copy this configuration to your Claude Desktop config file
34 |
35 | ### `codex-mcp-config.json`
36 | Example Codex configuration using `mcp-proxy` to bridge stdio to the service’s Streamable HTTP endpoint at `/mcp`.
37 |
38 | **Setup:**
39 | 1. Install the proxy: `pipx install mcp-proxy` (or `uv tool install mcp-proxy`)
40 | 2. Set server API key on the server: `export MCP_API_KEY=...`
41 | 3. Copy this file and adjust `your-server` and API key
42 | 4. Place it in Codex’s MCP config location (see Codex docs)
43 |
44 | Why proxy? Codex does not support HTTP transports natively and requires a stdio bridge.
45 |
46 | ## Quick Start
47 |
48 | ### 1. Server Setup
49 | ```bash
50 | # On your server machine
51 | cd mcp-memory-service
52 | python install.py --server-mode --storage-backend sqlite_vec
53 | export MCP_HTTP_HOST=0.0.0.0
54 | export MCP_API_KEY="your-secure-key"
55 | python scripts/run_http_server.py
56 | ```
57 |
58 | ### 2. Client Configuration
59 | ```bash
60 | # Update the bridge script path and server details
61 | cp examples/claude-desktop-http-config.json ~/.config/claude-desktop/
62 | ```
63 |
64 | ### 3. Test Connection
65 | ```bash
66 | # Test the HTTP API directly
67 | curl -H "Authorization: Bearer your-secure-key" \
68 | http://your-server:8000/api/health
69 | ```
70 |
71 | ## Advanced Usage
72 |
73 | - See the [Multi-Client Setup Guide](../docs/integration/multi-client.md) for Codex, Cursor, Qwen, and Gemini recipes.
74 | - For Cursor/Qwen/Gemini direct HTTP usage, prefer the Streamable HTTP endpoint: `http(s)://<host>:8000/mcp` with header `Authorization: Bearer <MCP_API_KEY>`.
75 |
```
--------------------------------------------------------------------------------
/docs/archive/obsolete-workflows/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Obsolete Workflows Archive
2 |
3 | This directory contains historical documentation of workflows that have been superseded by better, automated solutions.
4 |
5 | ## Contents
6 |
7 | ### `load_memory_context.md` (August 2025)
8 |
9 | **Original Purpose**: Manual prompt with curl commands to load memory context at Claude Code session start.
10 |
11 | **Why Obsolete**: Completely superseded by Natural Memory Triggers v7.1.3+ (September 2025).
12 |
13 | #### Evolution Timeline
14 |
15 | **Phase 1: Manual Loading (Aug 2025)** ❌ OBSOLETE
16 | ```bash
17 | # Users had to manually run curl commands and paste output
18 | curl -k -s -X POST https://server:8443/mcp \
19 | -H "Authorization: Bearer token" \
20 | -d '{"method": "tools/call", "params": {...}}'
21 | ```
22 | **Problems**: Manual, error-prone, required copy-paste, network configuration complexity
23 |
24 | **Phase 2: SessionStart Hooks (Aug-Sept 2025)** ✅ IMPROVED
25 | - Automatic memory retrieval at session start
26 | - Project detection and intelligent scoring
27 | - Git-aware context integration
28 |
29 | **Phase 3: Natural Memory Triggers (Sept 2025+)** ✅ PRODUCTION
30 | - 85%+ trigger accuracy with semantic pattern detection
31 | - Multi-tier performance optimization (50ms → 500ms tiers)
32 | - CLI management system for real-time configuration
33 | - Adaptive learning based on usage patterns
34 |
35 | **Phase 4: Team Collaboration (v7.0.0+)** ✅ NETWORK DISTRIBUTION
36 | - OAuth 2.1 Dynamic Client Registration
37 | - Claude Code HTTP transport
38 | - Zero-configuration team collaboration
39 | - Better than manual network sharing
40 |
41 | #### Current Solution
42 |
43 | Instead of manual prompts, users now get:
44 |
45 | ```bash
46 | # One-time installation
47 | cd claude-hooks && python install_hooks.py --natural-triggers
48 |
49 | # That's it! Automatic context injection from now on
50 | ```
51 |
52 | **Benefits**:
53 | - ✅ Zero manual steps per session
54 | - ✅ 85%+ trigger accuracy
55 | - ✅ Intelligent pattern detection
56 | - ✅ Multi-tier performance
57 | - ✅ Team collaboration via OAuth
58 |
59 | #### Historical Value
60 |
61 | This archive demonstrates:
62 | 1. **UX Evolution**: Manual → Semi-automatic → Fully automatic
63 | 2. **Problem Recognition**: Identifying pain points (manual commands)
64 | 3. **Iterative Improvement**: Each phase solved previous limitations
65 | 4. **User-Centric Design**: Continuously reducing friction
66 |
67 | #### Migration
68 |
69 | If you're still using manual prompts:
70 |
71 | **Old Approach** (manual):
72 | ```bash
73 | curl -k -s -X POST https://server:8443/mcp ... | jq -r '.result.content[0].text'
74 | ```
75 |
76 | **New Approach** (automatic):
77 | ```bash
78 | # Install once
79 | python claude-hooks/install_hooks.py --natural-triggers
80 |
81 | # Enjoy automatic context injection forever
82 | ```
83 |
84 | See: [Natural Memory Triggers Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)
85 |
86 | ---
87 |
88 | **Last Updated**: October 25, 2025
89 | **Status**: Archived for historical reference only
90 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/web/static/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Interactive Dashboard
2 |
3 | This directory contains the static assets for the interactive memory management dashboard.
4 |
5 | ## Files Overview
6 |
7 | - **`index.html`** - Main dashboard interface with complete UI structure
8 | - **`app.js`** - Frontend JavaScript application with API integration and real-time updates
9 | - **`style.css`** - Comprehensive CSS with responsive design and component styling
10 | - **`sse_test.html`** - Server-Sent Events testing interface (existing)
11 |
12 | ## Features Implemented
13 |
14 | ### 🎯 Core Dashboard
15 | - **Welcome overview** with memory statistics and quick actions
16 | - **Recent memories** display with click-to-view details
17 | - **Quick stats** showing total memories, recent activity, and tag counts
18 | - **Responsive design** that works on mobile, tablet, and desktop
19 |
20 | ### 🔍 Search & Browse
21 | - **Semantic search** with real-time suggestions
22 | - **Advanced filters** by tags, date range, and content type
23 | - **Grid/list view** toggles for different viewing preferences
24 | - **Search results** with relevance scoring and highlighting
25 |
26 | ### 📝 Memory Management
27 | - **Add new memories** with modal interface and auto-tagging
28 | - **View memory details** with full content, metadata, and tags
29 | - **Edit/delete operations** with confirmation and undo capabilities
30 | - **Bulk operations** for efficient memory organization
31 |
32 | ### ⚡ Real-time Features
33 | - **Server-Sent Events** integration for live updates
34 | - **Connection status** monitoring with reconnection logic
35 | - **Toast notifications** for user feedback
36 | - **Live statistics** updates without page refresh
37 |
38 | ### 🎨 User Experience
39 | - **Progressive disclosure** - simple by default, powerful when needed
40 | - **Keyboard shortcuts** - Ctrl+K for search, Ctrl+M for add memory
41 | - **Loading states** and error handling throughout
42 | - **Accessibility** features with proper ARIA labels and focus management
43 |
44 | ## Testing the Dashboard
45 |
46 | ### 1. Start the Server
47 | ```bash
48 | # With HTTPS (recommended)
49 | export MCP_HTTPS_ENABLED=true
50 | export MCP_HTTPS_PORT=8443
51 | python run_server.py
52 | ```
53 |
54 | ### 2. Access the Dashboard
55 | - **HTTPS**: https://localhost:8443/
56 | - **HTTP**: http://localhost:8000/
57 |
58 | ### 3. Test Core Functionality
59 | 1. **Search**: Use semantic queries and apply filters
60 | 2. **Add Memory**: Click "Add Memory" and create test content
61 | 3. **View Details**: Click memory cards to see full details
62 | 4. **Real-time Updates**: Open in multiple tabs to test SSE
63 | 5. **Keyboard Shortcuts**: Try Ctrl+K (search) and Ctrl+M (add)
64 |
65 | ## Technical Implementation
66 |
67 | - **Vanilla JavaScript** - No build process required
68 | - **CSS Grid + Flexbox** - Modern responsive layouts
69 | - **Server-Sent Events** - Real-time backend communication
70 | - **Progressive Enhancement** - Works without JavaScript for basics
71 | - **API Integration** - Full REST API connectivity with error handling
```
--------------------------------------------------------------------------------
/.claude/commands/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Commands
2 |
3 | Custom slash commands for mcp-memory-service development.
4 |
5 | ## Available Commands
6 |
7 | ### `/refactor-function` (PoC)
8 |
9 | Automated function complexity reduction using multi-agent workflow.
10 |
11 | **Status**: Proof of Concept (simulated agents)
12 |
13 | **Usage**:
14 | ```bash
15 | # Quick test
16 | /refactor-function --dry-run
17 |
18 | # Interactive (would work with real agents)
19 | # 1. Select function in editor
20 | # 2. Run: /refactor-function
21 | # 3. Review changes
22 | # 4. Apply if approved
23 | ```
24 |
25 | **Workflow**:
26 | ```
27 | Select Function → Baseline Analysis → Refactor → Validate → Review → Apply
28 | ```
29 |
30 | **Current Implementation** (PoC):
31 | - ✅ CLI interface working
32 | - ✅ Workflow orchestration
33 | - ✅ User confirmation flow
34 | - ⚠️ Simulated agent responses (placeholder)
35 | - ❌ Not yet integrated with real agents (amp-bridge, code-quality-guard)
36 |
37 | **Next Steps for Production**:
38 | 1. Integrate with Task agent calls
39 | 2. Read actual file content via Read tool
40 | 3. Apply changes via Edit tool
41 | 4. Create commits via Bash tool
42 | 5. Add Claude Code settings.json hook
43 |
44 | **Proven Track Record**:
45 | - Based on Issue #340 workflow (45.5% complexity reduction)
46 | - 2-3x faster than manual refactoring
47 | - 100% validation success rate
48 |
49 | ## Installation
50 |
51 | Commands are located in `.claude/commands/` and executable:
52 |
53 | ```bash
54 | # Make executable (already done)
55 | chmod +x .claude/commands/refactor-function
56 |
57 | # Test PoC
58 | .claude/commands/refactor-function --dry-run
59 |
60 | # With options
61 | .claude/commands/refactor-function --target-complexity 6
62 | ```
63 |
64 | ## Configuration (Future)
65 |
66 | Add to Claude Code `settings.json`:
67 |
68 | ```json
69 | {
70 | "commands": {
71 | "refactor-function": {
72 | "path": ".claude/commands/refactor-function",
73 | "description": "Reduce function complexity automatically",
74 | "requiresSelection": true,
75 | "agents": ["amp-bridge", "code-quality-guard"]
76 | }
77 | }
78 | }
79 | ```
80 |
81 | ## Development
82 |
83 | ### Command Structure
84 | ```
85 | .claude/commands/
86 | ├── README.md # This file
87 | ├── refactor-function # Executable Python script (PoC)
88 | └── refactor-function.md # Full specification
89 | ```
90 |
91 | ### Adding New Commands
92 |
93 | 1. Create executable script in `.claude/commands/<name>`
94 | 2. Add specification in `.claude/commands/<name>.md`
95 | 3. Update this README
96 | 4. Test with `--dry-run` flag
97 | 5. Document in commit message
98 |
99 | ### Testing
100 |
101 | ```bash
102 | # Unit test individual functions
103 | python3 -c "from refactor-function import RefactorCommand; ..."
104 |
105 | # Integration test full workflow
106 | .claude/commands/refactor-function --dry-run
107 |
108 | # With real selection (future)
109 | echo '{"file": "...", "function": "..."}' | .claude/commands/refactor-function
110 | ```
111 |
112 | ## Related Documentation
113 |
114 | - **Command Specification**: `refactor-function.md` - Full design doc
115 | - **Issue #340**: Original workflow that inspired this command
116 | - **Agent Docs**: `.claude/directives/agents.md` - Agent usage guide
117 |
118 | ## Future Commands (Ideas)
119 |
120 | - `/complexity-report` - Analyze file/module complexity
121 | - `/extract-method` - Manual Extract Method refactoring
122 | - `/add-tests` - Generate tests for function
123 | - `/simplify-conditionals` - Reduce boolean complexity
124 | - `/remove-duplication` - DRY principle enforcement
125 |
126 | ## Contributing
127 |
128 | New command ideas? Open an issue or PR with:
129 | 1. Use case description
130 | 2. Example workflow
131 | 3. Expected input/output
132 | 4. Agent requirements
133 |
134 | ## Credits
135 |
136 | Inspired by proven workflow from Issue #340:
137 | - 3 functions refactored in 2 hours
138 | - 45.5% total complexity reduction
139 | - Multi-agent orchestration (amp-bridge + code-quality-guard)
140 |
```
--------------------------------------------------------------------------------
/scripts/sync/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Database Synchronization Scripts
2 |
3 | This directory contains scripts for synchronizing SQLite-vec databases across multiple machines using JSON export/import and Litestream replication.
4 |
5 | ## Overview
6 |
7 | The synchronization system enables you to:
8 | - Export memories from one machine to JSON format
9 | - Import memories from multiple JSON files into a central database
10 | - Set up real-time replication using Litestream
11 | - Maintain consistent memory databases across multiple devices
12 |
13 | ## Scripts
14 |
15 | ### export_memories.py
16 |
17 | Export memories from a local SQLite-vec database to JSON format.
18 |
19 | **Usage:**
20 | ```bash
21 | # Basic export
22 | python export_memories.py
23 |
24 | # Export from specific database
25 | python export_memories.py --db-path /path/to/sqlite_vec.db
26 |
27 | # Export to specific file
28 | python export_memories.py --output my_export.json
29 |
30 | # Export with embedding vectors (large file size)
31 | python export_memories.py --include-embeddings
32 |
33 | # Export only specific tags
34 | python export_memories.py --filter-tags claude-code,architecture
35 | ```
36 |
37 | **Features:**
38 | - Preserves original timestamps and metadata
39 | - Adds source machine tracking
40 | - Supports tag filtering
41 | - Optional embedding vector export
42 | - Cross-platform compatibility
43 |
44 | ### import_memories.py
45 |
46 | Import memories from JSON export files into a central database.
47 |
48 | **Usage:**
49 | ```bash
50 | # Import single file
51 | python import_memories.py windows_export.json
52 |
53 | # Import multiple files
54 | python import_memories.py windows_export.json macbook_export.json
55 |
56 | # Dry run analysis
57 | python import_memories.py --dry-run exports/*.json
58 |
59 | # Import to specific database
60 | python import_memories.py --db-path /path/to/central.db exports/*.json
61 | ```
62 |
63 | **Features:**
64 | - Intelligent deduplication based on content hash
65 | - Preserves original timestamps
66 | - Adds source tracking tags
67 | - Conflict detection and resolution
68 | - Comprehensive import statistics
69 |
70 | ## Typical Workflow
71 |
72 | ### Phase 1: Initial Consolidation
73 |
74 | 1. **Export from each machine:**
75 | ```bash
76 | # On Windows PC
77 | python export_memories.py --output windows_memories.json
78 |
79 | # On MacBook
80 | python export_memories.py --output macbook_memories.json
81 | ```
82 |
83 | 2. **Transfer files to central server:**
84 | ```bash
85 | scp windows_memories.json central-server:/tmp/
86 | scp macbook_memories.json central-server:/tmp/
87 | ```
88 |
89 | 3. **Import on central server:**
90 | ```bash
91 | # Analyze first
92 | python import_memories.py --dry-run /tmp/*.json
93 |
94 | # Import for real
95 | python import_memories.py /tmp/windows_memories.json /tmp/macbook_memories.json
96 | ```
97 |
98 | ### Phase 2: Set up Litestream
99 |
100 | After consolidating all memories into the central database, set up Litestream for ongoing synchronization.
101 |
102 | ## JSON Export Format
103 |
104 | The export format preserves all memory data:
105 |
106 | ```json
107 | {
108 | "export_metadata": {
109 | "source_machine": "machine-name",
110 | "export_timestamp": "2025-08-12T10:30:00Z",
111 | "total_memories": 450,
112 | "database_path": "/path/to/sqlite_vec.db",
113 | "platform": "Windows",
114 | "exporter_version": "5.0.0"
115 | },
116 | "memories": [
117 | {
118 | "content": "Memory content here",
119 | "content_hash": "sha256hash",
120 | "tags": ["tag1", "tag2"],
121 | "created_at": 1673545200.0,
122 | "updated_at": 1673545200.0,
123 | "memory_type": "note",
124 | "metadata": {},
125 | "export_source": "machine-name"
126 | }
127 | ]
128 | }
129 | ```
130 |
131 | ## Deduplication Strategy
132 |
133 | Memories are deduplicated based on content hash:
134 | - Same content hash = duplicate (skipped)
135 | - Different content hash = unique (imported)
136 | - Original timestamps are preserved
137 | - Source machine tags are added for tracking
138 |
139 | ## Error Handling
140 |
141 | Both scripts include comprehensive error handling:
142 | - JSON format validation
143 | - Database connectivity checks
144 | - File existence verification
145 | - Transaction rollback on failures
146 | - Detailed error logging
147 |
148 | ## Performance Considerations
149 |
150 | - **Export**: ~1000 memories/second
151 | - **Import**: ~500 memories/second with deduplication
152 | - **File Size**: ~1KB per memory (without embeddings)
153 | - **Memory Usage**: Processes files in streaming fashion
154 |
155 | ## Troubleshooting
156 |
157 | ### Common Issues
158 |
159 | 1. **Database not found:**
160 | ```bash
161 | # Check default location
162 | python -c "from mcp_memory_service.config import get_storage_path; print(get_storage_path())"
163 | ```
164 |
165 | 2. **Permission errors:**
166 | ```bash
167 | # Ensure database directory is writable
168 | chmod 755 ~/.local/share/mcp-memory/
169 | ```
170 |
171 | 3. **JSON format errors:**
172 | ```bash
173 | # Validate JSON file
174 | python -m json.tool export.json > /dev/null
175 | ```
176 |
177 | ### Logging
178 |
179 | Enable verbose logging for debugging:
180 | ```bash
181 | python export_memories.py --verbose
182 | python import_memories.py --verbose
183 | ```
184 |
185 | ## Next Steps
186 |
187 | After using these scripts for initial consolidation:
188 |
189 | 1. Set up Litestream for real-time sync
190 | 2. Configure replica nodes
191 | 3. Implement monitoring and alerting
192 | 4. Schedule regular backups
193 |
194 | See the main documentation for complete Litestream setup instructions.
```
--------------------------------------------------------------------------------
/.metrics/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Complexity Analysis & Refactoring Metrics
2 |
3 | **Project:** MCP Memory Service - install_hooks.py Refactoring
4 | **Created:** 2026-01-10
5 | **Purpose:** Track complexity reduction and code quality improvements
6 |
7 | ---
8 |
9 | ## Quick Start
10 |
11 | ### View Current Metrics
12 |
13 | ```bash
14 | # Cyclomatic Complexity
15 | source .venv-analysis/bin/activate
16 | radon cc claude-hooks/install_hooks.py -s -a
17 |
18 | # Maintainability Index
19 | radon mi claude-hooks/install_hooks.py -s
20 |
21 | # Nesting Depth (Custom Analysis)
22 | python3 /tmp/analyze_functions.py
23 | ```
24 |
25 | ### Compare Progress
26 |
27 | ```bash
28 | # Compare complexity
29 | diff baseline_cc_install_hooks.txt after_cc_install_hooks.txt
30 |
31 | # Compare maintainability
32 | diff baseline_mi_install_hooks.txt after_mi_install_hooks.txt
33 |
34 | # Compare nesting depth
35 | diff baseline_nesting_install_hooks.txt after_nesting_install_hooks.txt
36 | ```
37 |
38 | ---
39 |
40 | ## Files in This Directory
41 |
42 | | File | Purpose | Usage |
43 | |------|---------|-------|
44 | | `BASELINE_REPORT.md` | Comprehensive baseline analysis | Read first for full context |
45 | | `QUICK_REFERENCE.txt` | Quick lookup table | Terminal-friendly summary |
46 | | `TRACKING_TABLE.md` | Progress tracking | Update after each phase |
47 | | `baseline_cc_install_hooks.txt` | Cyclomatic complexity baseline | Compare after refactoring |
48 | | `baseline_mi_install_hooks.txt` | Maintainability index baseline | Compare after refactoring |
49 | | `baseline_nesting_install_hooks.txt` | Nesting depth baseline | Compare after refactoring |
50 | | `README.md` | This file | Usage instructions |
51 |
52 | ---
53 |
54 | ## Baseline Summary
55 |
56 | ### Target Functions
57 |
58 | 1. **_parse_mcp_get_output()** (Lines 238-268)
59 | - Priority: P0 (CRITICAL)
60 | - Complexity: C (12) → Target: A (≤6)
61 | - Nesting: 9 levels → Target: ≤3 levels
62 | - Issue: Worst nesting in entire file
63 |
64 | 2. **validate_mcp_prerequisites()** (Lines 351-385)
65 | - Priority: P1 (HIGH)
66 | - Complexity: C (12) → Target: A (≤5)
67 | - Boolean Ops: 12 → Target: <5
68 | - Issue: Excessive boolean complexity
69 |
70 | 3. **detect_claude_mcp_configuration()** (Lines 198-236)
71 | - Priority: P2 (MEDIUM)
72 | - Complexity: B (9) → Target: A (≤6)
73 | - Nesting: 5 levels → Target: ≤3 levels
74 | - Issue: Over-engineered exception handling
75 |
76 | ### File-Level Targets
77 |
78 | - Maintainability Index: C (2.38) → B (≥5.0)
79 | - Average Complexity: B (7.7) → A (≤5.0)
80 | - Total LOC: 1,454 (expected minor reduction)
81 |
82 | ---
83 |
84 | ## Refactoring Phases
85 |
86 | ### Phase 1: _parse_mcp_get_output() (2-3 hours)
87 | - Extract field parsers into data-driven dictionary
88 | - Replace if/elif chain with lookup table
89 | - Reduce nesting from 9 → 3 levels
90 | - Separate parsing from validation
91 |
92 | ### Phase 2: validate_mcp_prerequisites() (2-3 hours)
93 | - Extract validation rules into separate validator functions
94 | - Replace boolean chains with explicit validation methods
95 | - Use validation classes (one per server type)
96 | - Separate concerns: detection → validation → reporting
97 |
98 | ### Phase 3: detect_claude_mcp_configuration() (1-2 hours)
99 | - Extract subprocess calls into dedicated methods
100 | - Simplify exception handling (use single try/except)
101 | - Extract fallback logic into separate method
102 | - Reduce nesting from 5 → 3 levels
103 |
104 | **Total Estimated Effort:** 5-8 hours
105 |
106 | ---
107 |
108 | ## Success Criteria
109 |
110 | ### Must Have (Blocking)
111 | - [ ] All 3 functions achieve complexity ≤6 (Grade A)
112 | - [ ] All 3 functions achieve nesting depth ≤3 levels
113 | - [ ] File maintainability index improves to B (≥5.0)
114 | - [ ] No new security issues introduced
115 | - [ ] All existing tests pass
116 |
117 | ### Should Have (Non-Blocking)
118 | - [ ] Test coverage maintained or increased
119 | - [ ] Boolean operators reduced to <5 in validate_mcp_prerequisites
120 | - [ ] Security issues reduced from 4 → 0
121 | - [ ] Average complexity improves to A (≤5.0)
122 |
123 | ---
124 |
125 | ## Validation Workflow
126 |
127 | After each refactoring phase:
128 |
129 | 1. **Run Metrics**
130 | ```bash
131 | source .venv-analysis/bin/activate
132 | radon cc claude-hooks/install_hooks.py -s -a > after_cc_install_hooks.txt
133 | radon mi claude-hooks/install_hooks.py -s > after_mi_install_hooks.txt
134 | python3 /tmp/analyze_functions.py > after_nesting_install_hooks.txt
135 | ```
136 |
137 | 2. **Compare Results**
138 | ```bash
139 | diff baseline_cc_install_hooks.txt after_cc_install_hooks.txt
140 | diff baseline_mi_install_hooks.txt after_mi_install_hooks.txt
141 | diff baseline_nesting_install_hooks.txt after_nesting_install_hooks.txt
142 | ```
143 |
144 | 3. **Run Tests**
145 | ```bash
146 | pytest tests/ -v
147 | ```
148 |
149 | 4. **Security Scan**
150 | ```bash
151 | bandit -r claude-hooks/install_hooks.py
152 | ```
153 |
154 | 5. **Update Tracking**
155 | - Update `TRACKING_TABLE.md` with current metrics
156 | - Note any observations or challenges
157 |
158 | ---
159 |
160 | ## Tools Used
161 |
162 | ### Analysis Tools
163 | - **radon** - Cyclomatic complexity and maintainability index
164 | - **bandit** - Security vulnerability scanning
165 | - **Custom AST analyzer** (`/tmp/analyze_functions.py`) - Nesting depth
166 |
167 | ### Installation
168 | ```bash
169 | python3 -m venv .venv-analysis
170 | source .venv-analysis/bin/activate
171 | pip install radon bandit
172 | ```
173 |
174 | ---
175 |
176 | ## Expected Improvements
177 |
178 | | Metric | Before | After | Improvement |
179 | |--------|--------|-------|-------------|
180 | | **Cyclomatic Complexity (worst)** | C (12) | A (≤6) | 50% reduction |
181 | | **Nesting Depth (worst)** | 9 levels | ≤3 levels | 67% reduction |
182 | | **Boolean Operators (worst)** | 12 | <5 | 58% reduction |
183 | | **Maintainability Index (file)** | C (2.38) | B (≥5.0) | 110% increase |
184 | | **Average Complexity (file)** | B (7.7) | A (≤5.0) | 35% reduction |
185 |
186 | ---
187 |
188 | ## References
189 |
190 | - **Baseline Analysis:** `BASELINE_REPORT.md`
191 | - **Quick Reference:** `QUICK_REFERENCE.txt`
192 | - **Progress Tracking:** `TRACKING_TABLE.md`
193 | - **Project Context:** `/CLAUDE.md` (Code Quality Monitoring section)
194 |
195 | ---
196 |
197 | ## Contact & Support
198 |
199 | For questions or issues with the refactoring process:
200 | 1. Review `BASELINE_REPORT.md` for detailed analysis
201 | 2. Check `TRACKING_TABLE.md` for current progress
202 | 3. Consult project maintainers if blockers arise
203 |
204 | ---
205 |
206 | **Last Updated:** 2026-01-10
207 |
```
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Documentation
2 |
3 | Welcome to the comprehensive documentation for MCP Memory Service - a Model Context Protocol server that provides semantic memory and persistent storage capabilities for Claude Desktop and other MCP clients.
4 |
5 | ## Quick Start
6 |
7 | - **New Users**: Start with the [Installation Guide](installation/master-guide.md)
8 | - **Multi-Client Setup**: See [Multi-Client Integration](integration/multi-client.md)
9 | - **Docker Users**: Check out [Docker Deployment](deployment/docker.md)
10 | - **Troubleshooting**: Visit [General Troubleshooting](troubleshooting/general.md)
11 |
12 | ## Documentation Structure
13 |
14 | ### 📦 Installation & Setup
15 |
16 | - **[Master Installation Guide](installation/master-guide.md)** - Comprehensive installation instructions for all platforms
17 | - **[Platform-Specific Guides](platforms/)** - Detailed setup for specific operating systems
18 | - [macOS Intel](platforms/macos-intel.md) - Intel Mac setup (including legacy 2013-2017 models)
19 | - [Windows](platforms/windows.md) - Windows installation with CUDA/DirectML support
20 | - [Ubuntu](platforms/ubuntu.md) - Ubuntu setup for desktop and server
21 |
22 | ### 🔗 Integration & Connectivity
23 |
24 | - **[Multi-Client Setup](integration/multi-client.md)** - Share memory across multiple applications
25 | - **[Homebrew Integration](integration/homebrew.md)** - Use system-installed PyTorch via Homebrew
26 | - **[Claude Desktop Integration](guides/claude_integration.md)** - Connect with Claude Desktop
27 | - **[IDE Compatibility](ide-compatability.md)** - VS Code, Continue, and other IDE integrations
28 |
29 | ### 🚀 Deployment
30 |
31 | - **[Docker Deployment](deployment/docker.md)** - Containerized deployment with various configurations
32 | - **[Server Deployment](deployment/multi-client-server.md)** - Production server setups
33 | - **[Cloud Deployment](glama-deployment.md)** - Cloud platform deployment guides
34 |
35 | ### 📚 User Guides
36 |
37 | - **[MCP Protocol Enhancements](guides/mcp-enhancements.md)** - Resources, Prompts, and Progress Tracking (v4.1.0)
38 | - **[Storage Backends](guides/STORAGE_BACKENDS.md)** - ChromaDB vs SQLite-vec comparison and configuration
39 | - **[Migration Guide](guides/migration.md)** - Migrate between storage backends and versions
40 | - **[Scripts Reference](guides/scripts.md)** - Available utility scripts
41 | - **[Invocation Guide](guides/invocation_guide.md)** - Different ways to run the service
42 |
43 | ### 🎯 Tutorials & Examples
44 |
45 | - **[Data Analysis Examples](tutorials/data-analysis.md)** - Advanced data analysis with memory service
46 | - **[Advanced Techniques](tutorials/advanced-techniques.md)** - Power user techniques and patterns
47 | - **[Demo Session Walkthrough](tutorials/demo-session-walkthrough.md)** - Step-by-step usage examples
48 |
49 | ### 🔧 Maintenance & Administration
50 |
51 | - **[Memory Maintenance](maintenance/memory-maintenance.md)** - Database cleanup, optimization, and backup
52 | - **[Health Checks](implementation/health_checks.md)** - Monitoring and diagnostics
53 | - **[Performance Tuning](implementation/performance.md)** - Optimization techniques
54 |
55 | ### 📖 API Reference
56 |
57 | - **[Memory Metadata API](api/memory-metadata-api.md)** - Advanced metadata operations
58 | - **[Tag Standardization](api/tag-standardization.md)** - Tag schema and conventions
59 | - **[HTTP/SSE API](IMPLEMENTATION_PLAN_HTTP_SSE.md)** - Web API documentation for multi-client setups
60 |
61 | ### 🛠️ Development & Technical
62 |
63 | - **[Development Guide](technical/development.md)** - Contributing and development setup
64 | - **[Architecture Overview](development/multi-client-architecture.md)** - System architecture and design patterns
65 | - **[Technical Implementation](technical/)** - Deep dive into technical details
66 | - [Memory Migration](technical/memory-migration.md)
67 | - [Tag Storage](technical/tag-storage.md)
68 |
69 | ### 🔍 Troubleshooting
70 |
71 | - **[General Troubleshooting](troubleshooting/general.md)** - Common issues and solutions
72 | - **[Docker Issues](deployment/docker.md#troubleshooting)** - Docker-specific troubleshooting
73 | - **[Platform-Specific Issues](platforms/)** - Platform-specific troubleshooting sections
74 |
75 | ## Project Information
76 |
77 | ### About MCP Memory Service
78 |
79 | MCP Memory Service enables persistent, semantic memory for AI applications through the Model Context Protocol. It provides:
80 |
81 | - **Semantic Search**: Vector-based memory retrieval using sentence transformers
82 | - **Multiple Storage Backends**: ChromaDB for full features, SQLite-vec for lightweight deployments
83 | - **Multi-Client Support**: Shared memory across multiple applications
84 | - **Cross-Platform**: Support for macOS, Windows, and Linux
85 | - **Flexible Deployment**: Local installation, Docker containers, or cloud deployment
86 |
87 | ### Key Features
88 |
89 | - ✅ **Semantic Memory Storage**: Store and retrieve memories using natural language
90 | - ✅ **Multi-Client Access**: Share memories across Claude Desktop, VS Code, and other MCP clients
91 | - ✅ **Flexible Storage**: Choose between ChromaDB (full-featured) or SQLite-vec (lightweight)
92 | - ✅ **Cross-Platform**: Native support for macOS (Intel & Apple Silicon), Windows, and Linux
93 | - ✅ **Docker Ready**: Complete containerization support with multiple deployment options
94 | - ✅ **Hardware Optimized**: Automatic detection and optimization for available hardware (CUDA, MPS, DirectML)
95 | - ✅ **Production Ready**: HTTP/SSE API, authentication, monitoring, and scaling features
96 |
97 | ### Recent Updates
98 |
99 | - **v0.2.2+**: Enhanced multi-client support with automatic MCP application detection
100 | - **SQLite-vec Backend**: Lightweight alternative to ChromaDB for resource-constrained systems
101 | - **Homebrew Integration**: Native support for Homebrew-installed PyTorch on macOS
102 | - **Docker Improvements**: Fixed boot loops, added multiple deployment configurations
103 | - **HTTP/SSE API**: Real-time multi-client communication with Server-Sent Events
104 |
105 | ## Getting Help
106 |
107 | ### Quick Links
108 |
109 | - **Installation Issues**: Check the [Installation Guide](installation/master-guide.md) and platform-specific guides
110 | - **Configuration Problems**: See [Troubleshooting](troubleshooting/general.md)
111 | - **Multi-Client Setup**: Follow the [Multi-Client Guide](integration/multi-client.md)
112 | - **Performance Issues**: Review [Performance Tuning](implementation/performance.md)
113 |
114 | ### Support Resources
115 |
116 | - **GitHub Issues**: Report bugs and request features
117 | - **Documentation**: Comprehensive guides for all use cases
118 | - **Community**: Share experiences and get help from other users
119 |
120 | ### Contributing
121 |
122 | We welcome contributions! See the [Development Guide](technical/development.md) for information on:
123 |
124 | - Setting up a development environment
125 | - Running tests
126 | - Submitting pull requests
127 | - Code style and conventions
128 |
129 | ## Version History
130 |
131 | - **Latest**: Enhanced documentation organization, consolidated guides, improved navigation
132 | - **v0.2.2**: Multi-client improvements, SQLite-vec backend, Homebrew integration
133 | - **v0.2.1**: Docker deployment fixes, HTTP/SSE API enhancements
134 | - **v0.2.0**: Multi-client support, cross-platform compatibility improvements
135 |
136 | ---
137 |
138 | ## Navigation Tips
139 |
140 | - **📁 Folders**: Click on folder names to explore sections
141 | - **🔗 Links**: All internal links are relative and work offline
142 | - **📱 Mobile**: Documentation is mobile-friendly for on-the-go reference
143 | - **🔍 Search**: Use your browser's search (Ctrl/Cmd+F) to find specific topics
144 |
145 | **Happy memory-ing! 🧠✨**
```
--------------------------------------------------------------------------------
/claude_commands/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Commands for MCP Memory Service
2 |
3 | This directory contains conversational Claude Code commands that integrate memory functionality into your Claude Code workflow. These commands follow the CCPlugins pattern of markdown-based conversational instructions.
4 |
5 | ## Available Commands
6 |
7 | ### `/session-start` - Manual Session Initialization
8 | Display session memory context manually by running the session-start hook. **Windows Workaround**: Required for Windows users due to SessionStart hook bug (#160). Works on all platforms.
9 |
10 | **Usage:**
11 | ```bash
12 | claude /session-start
13 | ```
14 |
15 | **Why this exists:**
16 | - Windows users cannot use automatic SessionStart hooks (causes Claude Code to hang)
17 | - Provides same functionality as automatic session-start hook
18 | - Safe manual alternative that works on all platforms (Windows, macOS, Linux)
19 |
20 | **What it does:**
21 | - Loads relevant project memories at session start
22 | - Analyzes git history and recent changes
23 | - Displays categorized memory context (recent work, current problems, additional context)
24 |
25 | ### `/memory-store` - Store Current Context
26 | Store information in your MCP Memory Service with proper context and tagging. Automatically detects project context, applies relevant tags, and includes machine hostname for source tracking.
27 |
28 | **Usage:**
29 | ```bash
30 | claude /memory-store "Important architectural decision about database backend"
31 | claude /memory-store --tags "decision,architecture" "We chose SQLite-vec for performance"
32 | ```
33 |
34 | ### `/memory-recall` - Time-based Memory Retrieval
35 | Retrieve memories using natural language time expressions. Perfect for finding past conversations and decisions.
36 |
37 | **Usage:**
38 | ```bash
39 | claude /memory-recall "what did we decide about the database last week?"
40 | claude /memory-recall "yesterday's architectural discussions"
41 | ```
42 |
43 | ### `/memory-search` - Tag and Content Search
44 | Search through stored memories using tags, content keywords, and semantic similarity.
45 |
46 | **Usage:**
47 | ```bash
48 | claude /memory-search --tags "architecture,database"
49 | claude /memory-search "SQLite performance optimization"
50 | ```
51 |
52 | ### `/memory-context` - Session Context Integration
53 | Capture the current conversation and project context as a memory for future reference. Automatically includes machine source identification for multi-device workflows.
54 |
55 | **Usage:**
56 | ```bash
57 | claude /memory-context
58 | claude /memory-context --summary "Architecture planning session"
59 | ```
60 |
61 | ### `/memory-health` - Service Health Check
62 | Check the health and status of your MCP Memory Service, providing diagnostics and statistics.
63 |
64 | **Usage:**
65 | ```bash
66 | claude /memory-health
67 | claude /memory-health --detailed
68 | ```
69 |
70 | ## Installation
71 |
72 | ### Automatic Installation (Recommended)
73 |
74 | The commands can be installed automatically during the main MCP Memory Service installation:
75 |
76 | ```bash
77 | # Install with commands (will prompt if Claude Code CLI is detected)
78 | python install.py
79 |
80 | # Force install commands
81 | python install.py --install-claude-commands
82 |
83 | # Skip command installation prompt
84 | python install.py --skip-claude-commands-prompt
85 | ```
86 |
87 | ### Manual Installation
88 |
89 | You can also install the commands manually:
90 |
91 | ```bash
92 | # Install commands directly
93 | python scripts/claude_commands_utils.py
94 |
95 | # Test installation prerequisites
96 | python scripts/claude_commands_utils.py --test
97 |
98 | # Uninstall commands
99 | python scripts/claude_commands_utils.py --uninstall
100 | ```
101 |
102 | ## Requirements
103 |
104 | - **Claude Code CLI**: Must be installed and available in PATH
105 | - **MCP Memory Service**: Should be installed and configured
106 | - **File System Access**: Write access to `~/.claude/commands/` directory
107 |
108 | ## How It Works
109 |
110 | 1. **Command Files**: Each command is a markdown file with conversational instructions
111 | 2. **Claude Code Integration**: Commands are installed to `~/.claude/commands/`
112 | 3. **Service Connection**: Commands connect via mDNS discovery or direct HTTPS endpoints
113 | 4. **Context Awareness**: Commands understand your current project and session context
114 | 5. **API Integration**: Uses standard MCP Memory Service API endpoints for all operations
115 |
116 | ## Command Features
117 |
118 | - **Machine Source Tracking**: Automatic hostname tagging for multi-device memory filtering
119 | - **Conversational Interface**: Natural language interactions following CCPlugins pattern
120 | - **Context Detection**: Automatic project and session context recognition
121 | - **Smart Tagging**: Intelligent tag generation based on current work
122 | - **Auto-Save**: Immediate storage without confirmation prompts
123 | - **Flexible Configuration**: Supports both mDNS discovery and direct HTTPS endpoints
124 | - **API Compatibility**: Works with standard MCP Memory Service API endpoints
125 |
126 | ## Example Workflow
127 |
128 | ```bash
129 | # Start a development session (automatically tagged with machine hostname)
130 | claude /memory-context --summary "Starting work on mDNS integration"
131 |
132 | # Store important decisions (includes source:machine-name tag)
133 | claude /memory-store --tags "mDNS,architecture" "Decided to use zeroconf library for service discovery"
134 |
135 | # Continue development...
136 |
137 | # Later, recall what was decided
138 | claude /memory-recall "what did we decide about mDNS last week?"
139 |
140 | # Search for related information
141 | claude /memory-search --tags "mDNS,zeroconf"
142 |
143 | # Search memories from specific machine
144 | claude /memory-search --tags "source:laptop-work"
145 |
146 | # Check service health
147 | claude /memory-health
148 | ```
149 |
150 | ## Troubleshooting
151 |
152 | ### Commands Not Available
153 | - Ensure Claude Code CLI is installed: `claude --version`
154 | - Check if commands are installed: `ls ~/.claude/commands/memory-*.md`
155 | - Reinstall commands: `python scripts/claude_commands_utils.py`
156 |
157 | ### Service Connection Issues
158 | - **Service Health**: Check if service is accessible: `curl -k https://your-endpoint:8443/api/health`
159 | - **Comprehensive Diagnostics**: Use `claude /memory-health` for detailed service status
160 | - **Local Development**: Verify server can start: `python scripts/run_memory_server.py --help`
161 | - **Endpoint Configuration**: Verify API endpoints match your service deployment
162 |
163 | ### Permission Issues
164 | - Check directory permissions: `ls -la ~/.claude/commands/`
165 | - Ensure write access to the commands directory
166 | - Try running installation with appropriate permissions
167 |
168 | ## Configuration & API Compatibility
169 |
170 | These commands integrate with your MCP Memory Service through configurable endpoints:
171 |
172 | - **Flexible Connection**: Supports both mDNS auto-discovery and direct HTTPS endpoints
173 | - **Configurable Endpoints**: Template uses `memory.local:8443` but can be customized to your setup
174 | - **API Requirements**: Commands must use these standard API endpoints to function:
175 | - `POST /api/search` - Semantic similarity search
176 | - `POST /api/search/by-tag` - Tag-based search (AND/OR matching)
177 | - `POST /api/search/by-time` - Time-based natural language queries
178 | - `GET /api/memories` - List memories with pagination
179 | - `POST /api/memories` - Store new memories
180 | - `GET /api/health/detailed` - Service health diagnostics
181 | - **Backend Compatibility**: Works with both ChromaDB and SQLite-vec storage backends
182 | - **HTTPS Support**: Uses curl with `-k` flag for self-signed certificates
183 |
184 | **Important**: Commands are configurable but must maintain compatibility with the documented API endpoints to function properly. Users can customize server locations but not the API contract.
185 |
186 | ## Development
187 |
188 | The commands are implemented using:
189 |
190 | - **Markdown Format**: Conversational instructions in markdown files
191 | - **Python Utilities**: Installation and management scripts in `scripts/claude_commands_utils.py`
192 | - **Integration Logic**: Seamless installation via main `install.py` script
193 | - **Cross-Platform Support**: Works on Windows, macOS, and Linux
194 |
195 | For more information about the MCP Memory Service, see the main project documentation.
```
--------------------------------------------------------------------------------
/claude-hooks/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Claude Code Memory Awareness Hooks
2 |
3 | Automatic memory awareness and intelligent context injection for Claude Code using the MCP Memory Service.
4 |
5 | ## Quick Start
6 |
7 | ```bash
8 | cd claude-hooks
9 |
10 | # Install Natural Memory Triggers v7.1.3 (recommended)
11 | python install_hooks.py --natural-triggers
12 |
13 | # OR install basic memory awareness hooks
14 | python install_hooks.py --basic
15 | ```
16 |
17 | > **Note**: The unified Python installer replaces all previous installers and provides cross-platform compatibility with enhanced features. See [MIGRATION.md](MIGRATION.md) for details.
18 |
19 | This installs hooks that automatically:
20 | - Load relevant project memories when Claude Code starts
21 | - Inject meaningful contextual information (no more generic fluff!)
22 | - Store session insights and decisions for future reference
23 | - Provide on-demand memory retrieval when you need it
24 |
25 | ## Components
26 |
27 | - **Core Hooks**: `session-start.js` (Hook v2.2), `session-end.js`, `memory-retrieval.js`, `permission-request.js` (v1.0) - Smart memory management and permission automation
28 | - **Utilities**: Project detection, quality-aware scoring, intelligent formatting, context shift detection
29 | - **Tests**: Comprehensive integration test suite (14 tests)
30 |
31 | ## Features
32 |
33 | ### 🎯 **NEW in v8.5.7**: SessionStart Hook Visibility Features
34 | Three complementary ways to view session memory context:
35 |
36 | 1. **Visible Summary Output** - Clean bordered console display at session start
37 | - Shows: project name, storage backend, memory count (with recent indicator), git context
38 | - Respects `cleanMode` configuration for minimal output
39 |
40 | 2. **Detailed Log File** - `~/.claude/last-session-context.txt`
41 | - Auto-generated on each session start
42 | - Contains: project details, storage backend, memory statistics, git analysis, top loaded memories
43 |
44 | 3. **Status Line Display** ⭐ - Always-visible status bar at bottom of terminal
45 | - Format: `🧠 8 (8 recent) memories | 📊 10 commits`
46 | - Displays static session memory context (set once at session start)
47 | - **Requires**: `jq` (JSON parser) and Claude Code statusLine configuration
48 | - **Platform**: Linux/macOS (Windows SessionStart hook broken - issue #160)
49 | - **Windows Workaround**: Use `/session-start` slash command for manual session initialization
50 |
51 | ### ✨ **Hook v2.2.0**: Enhanced Output Control
52 | - **Clean Output Mode**: Configurable verbosity levels for minimal or detailed output
53 | - **Smart Filtering**: Hide memory scoring details while keeping essential information
54 | - **Professional UX**: Removed noisy wrapper tags and improved ANSI formatting
55 | - **Granular Control**: Fine-tune what information is displayed during hook execution
56 |
57 | ### 🧠 **Previous Features (Project v6.7.0)**: Smart Memory Context
58 | - **Quality Content Extraction**: Extracts actual decisions/insights from session summaries instead of "implementation..." fluff
59 | - **Duplicate Filtering**: Automatically removes repetitive session summaries
60 | - **Smart Timing**: Only injects memories when contextually appropriate (no more mid-session disruptions)
61 | - **On-Demand Retrieval**: Manual memory refresh with `memory-retrieval.js` hook
62 |
63 | ### 🧠 **Core Features**
64 | - **Automatic Memory Injection**: Load relevant memories at session start with quality filtering
65 | - **Project Awareness**: Detect current project context and frameworks
66 | - **Memory Consolidation**: Store session outcomes and insights
67 | - **Intelligent Selection**: Quality-aware scoring that prioritizes meaningful content over just recency
68 | - **🆕 Permission Automation** (v1.0): Auto-approve safe MCP tool operations, block destructive actions - See [README-PERMISSION-REQUEST.md](README-PERMISSION-REQUEST.md)
69 |
70 | ### 🎮 **User Overrides** (`#skip` / `#remember`)
71 |
72 | Control memory hook behavior directly from your messages:
73 |
74 | | Trigger | Effect |
75 | |---------|--------|
76 | | `#skip` | Skip all memory operations for this message |
77 | | `#remember` | Force memory operations (bypass cooldowns, thresholds) |
78 |
79 | **Examples:**
80 | ```
81 | User: "Quick test, ignore this #skip"
82 | → ⏭️ Memory Hook → Skipped by user override (#skip)
83 |
84 | User: "Important architecture decision #remember"
85 | → 💾 Memory Hook → Force triggered by user override (#remember)
86 | ```
87 |
88 | **Supported Hooks:**
89 |
90 | | Hook | `#skip` | `#remember` |
91 | |------|---------|-------------|
92 | | session-start | Skips memory retrieval | Forces retrieval |
93 | | mid-conversation | Skips analysis | Bypasses cooldown, forces trigger |
94 | | session-end | Skips consolidation | Bypasses length/confidence checks |
95 | | auto-capture | Skips storage | Forces storage |
96 |
97 | Configuration in `config.json`:
98 | ```json
99 | {
100 | "autoCapture": {
101 | "userOverrides": {
102 | "forceRemember": "#remember",
103 | "forceSkip": "#skip",
104 | "applyTo": ["auto-capture", "session-start", "mid-conversation", "session-end"]
105 | }
106 | }
107 | }
108 | ```
109 |
110 | ## Installation
111 |
112 | ### Unified Installer (Recommended)
113 | ```bash
114 | cd claude-hooks
115 | python install_hooks.py # Installs all features
116 |
117 | # OR install specific features
118 | python install_hooks.py --basic # Basic memory hooks only
119 | python install_hooks.py --natural-triggers # Natural Memory Triggers only
120 | ```
121 |
122 | **Prerequisites:**
123 | - Python 3.10+
124 | - Node.js (for hooks execution)
125 | - **`jq`** (required for statusLine feature - displays memory context in Claude Code status bar)
126 | - macOS: `brew install jq`
127 | - Linux: `sudo apt install jq` (Ubuntu/Debian) or equivalent
128 | - Windows: `choco install jq` or download from https://jqlang.github.io/jq/
129 |
130 | ### Manual
131 | ```bash
132 | cp -r claude-hooks/* ~/.claude/hooks/
133 | chmod +x ~/.claude/hooks/statusline.sh # Make statusline executable (Unix only)
134 | # Edit ~/.claude/settings.json and ~/.claude/hooks/config.json
135 | ```
136 |
137 | ## Verification
138 |
139 | After installation:
140 | ```bash
141 | claude --debug hooks # Should show "Found 1 hook matchers in settings"
142 | cd ~/.claude/hooks && node tests/integration-test.js # Run 14 integration tests
143 | ```
144 |
145 | ## Configuration
146 |
147 | Edit `~/.claude/hooks/config.json`:
148 | ```json
149 | {
150 | "memoryService": {
151 | "endpoint": "https://your-server:8443",
152 | "apiKey": "your-api-key",
153 | "maxMemoriesPerSession": 8,
154 | "injectAfterCompacting": false
155 | },
156 | "memoryScoring": {
157 | "weights": {
158 | "timeDecay": 0.25,
159 | "tagRelevance": 0.35,
160 | "contentRelevance": 0.15,
161 | "contentQuality": 0.25
162 | }
163 | }
164 | }
165 | ```
166 |
167 | ### ⚙️ **Output Verbosity Control (Hook v2.2.0)**
168 | ```json
169 | {
170 | "output": {
171 | "verbose": true, // Show hook activity messages
172 | "showMemoryDetails": false, // Hide detailed memory scoring
173 | "showProjectDetails": true, // Show project detection info
174 | "showScoringDetails": false,// Hide scoring breakdowns
175 | "cleanMode": false // Ultra-minimal output mode
176 | }
177 | }
178 | ```
179 |
180 | **Verbosity Levels**:
181 | - **Normal** (`verbose: true`, others `false`): Shows essential information only
182 | - **Detailed** (`showMemoryDetails: true`): Include memory scoring details
183 | - **Clean** (`cleanMode: true`): Minimal output, only success/error messages
184 | - **Silent** (`verbose: false`): Hook works silently in background
185 |
186 | ### ⚙️ **Previous Configuration Options (Project v6.7.0)**
187 | - `injectAfterCompacting`: Controls whether to inject memories after compacting events (default: `false`)
188 | - `contentQuality`: New scoring weight for content quality assessment (filters generic summaries)
189 | - Enhanced memory filtering automatically removes "implementation..." fluff
190 |
191 | ## Usage
192 |
193 | Once installed, hooks work automatically:
194 | - **Session start**: Load relevant project memories
195 | - **Session end**: Store insights and decisions
196 | - No manual intervention required
197 |
198 | ## Troubleshooting
199 |
200 | ### Quick Fixes
201 | - **Hooks not detected**: `ls ~/.claude/settings.json` → Reinstall if missing
202 | - **JSON parse errors**: Update to latest version (includes Python dict conversion)
203 | - **Connection failed**: Check `curl -k https://your-endpoint:8443/api/health`
204 | - **Wrong directory**: Move `~/.claude-code/hooks/*` to `~/.claude/hooks/`
205 |
206 | ### Debug Mode
207 | ```bash
208 | claude --debug hooks # Shows hook execution details
209 | node ~/.claude/hooks/core/session-start.js # Test individual hooks
210 | ```
211 |
212 | ### Windows-Specific Issues
213 |
214 | #### Path Configuration
215 | - **Directory Structure**: Hooks should be installed to `%USERPROFILE%\.claude\hooks\`
216 | - **JSON Path Format**: Use forward slashes in settings.json: `"command": "node C:/Users/username/.claude/hooks/core/session-start.js"`
217 | - **Avoid Backslashes**: Windows backslashes in JSON need escaping: `"C:\\\\Users\\\\..."` (prefer forward slashes instead)
218 |
219 | #### Settings Configuration Example
220 | ```json
221 | {
222 | "hooks": [
223 | {
224 | "pattern": "session-start",
225 | "command": "node C:/Users/your-username/.claude/hooks/core/session-start.js"
226 | }
227 | ]
228 | }
229 | ```
230 |
231 | #### Common Fixes
232 | - **Wrong Path Format**: If you see `session-start-wrapper.bat` errors, update your settings.json to use the Node.js script directly
233 | - **Legacy Directory**: If using old `.claude-code` directory, move contents to `.claude` directory
234 | - **Permission Issues**: Run installation scripts as Administrator if needed
235 |
236 | ## Changelog
237 |
238 | ### Hook v2.2.0 (2025-01-25) - Enhanced Output Control
239 | **🎯 Focus**: Professional UX and configurable verbosity
240 |
241 | **New Features**:
242 | - **Output Verbosity Control**: Granular configuration for hook output levels
243 | - **Clean Mode**: Ultra-minimal output option for distraction-free usage
244 | - **Smart Filtering**: Hide memory scoring details while preserving essential information
245 |
246 | **Improvements**:
247 | - **Removed Noise**: Eliminated `<session-start-hook>` wrapper tags and verbose logging
248 | - **Enhanced ANSI**: Improved color consistency and formatting throughout
249 | - **Better Defaults**: Less verbose output by default while maintaining functionality
250 |
251 | **Configuration**:
252 | - Added `output` section with `verbose`, `showMemoryDetails`, `showProjectDetails`, `cleanMode` options
253 | - Backwards compatible - existing configurations work without changes
254 | - Self-documenting configuration with clear field names
255 |
256 | ### Hook v2.1.0 - Smart Memory Integration
257 | - Advanced memory scoring and quality assessment
258 | - Enhanced context injection with deduplication
259 | - Improved project detection and context awareness
260 |
261 | ### Project v6.7.0 - Smart Memory Context
262 | - Quality content extraction and duplicate filtering
263 | - Smart timing and context shift detection
264 | - On-demand memory retrieval capabilities
265 |
266 | ## Documentation
267 |
268 | For comprehensive documentation including detailed troubleshooting, advanced configuration, and development guides, see:
269 |
270 | **[📖 Memory Awareness Hooks - Detailed Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Awareness-Hooks-Detailed-Guide)**
271 |
272 | This guide covers:
273 | - Advanced installation methods and configuration options
274 | - Comprehensive troubleshooting with solutions
275 | - Custom hook development and architecture diagrams
276 | - Memory service integration and testing frameworks
```
--------------------------------------------------------------------------------
/scripts/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service Scripts
2 |
3 | This directory contains organized utility scripts for maintaining, managing, and operating the MCP Memory Service. Scripts are categorized by function for easy navigation and maintenance.
4 |
5 | ## 📁 Directory Structure
6 |
7 | ```
8 | scripts/
9 | ├── backup/ # Backup and restore operations
10 | ├── database/ # Database analysis and health monitoring
11 | ├── development/ # Development tools and debugging utilities
12 | ├── installation/ # Setup and installation scripts
13 | ├── linux/ # Linux service management shortcuts (v7.5.1+)
14 | ├── maintenance/ # Database cleanup and repair operations
15 | ├── migration/ # Data migration and schema updates
16 | ├── server/ # Server runtime and operational scripts
17 | ├── service/ # Service management and deployment
18 | ├── sync/ # Backend synchronization utilities
19 | ├── testing/ # Test scripts and validation
20 | ├── utils/ # General utility scripts and wrappers
21 | ├── validation/ # Configuration and system validation
22 | ├── run/ # Runtime execution scripts
23 | ├── archive/ # Deprecated scripts (kept for reference)
24 | └── README.md # This file
25 | ```
26 |
27 | ## 🚀 Quick Reference
28 |
29 | ### Essential Daily Operations
30 | ```bash
31 | # Service Management
32 | ./service/memory_service_manager.sh status # Check service status
33 | ./service/memory_service_manager.sh start-cloudflare # Start with Cloudflare backend
34 |
35 | # Backend Synchronization
36 | ./sync/claude_sync_commands.py status # Check sync status
37 | ./sync/claude_sync_commands.py backup # Backup Cloudflare → SQLite
38 | ./sync/claude_sync_commands.py sync # Bidirectional sync
39 | ./sync/sync_now.py --verbose # Manual on-demand hybrid sync (v7.5.1+)
40 |
41 | # Configuration Validation
42 | ./validation/validate_configuration_complete.py # Comprehensive config validation
43 | ./validation/diagnose_backend_config.py # Cloudflare backend diagnostics
44 | ./validation/verify_environment.py # Check environment setup
45 |
46 | # Database Health
47 | ./database/simple_timestamp_check.py # Quick health check
48 | ./database/db_health_check.py # Comprehensive health analysis
49 | ```
50 |
51 | ## 📂 Detailed Directory Guide
52 |
53 | ### 🔄 **sync/** - Backend Synchronization
54 | Essential for managing dual-backend setups and data synchronization.
55 |
56 | #### Cloudflare Hybrid Sync (Cloud Backend)
57 | | Script | Purpose | Quick Usage |
58 | |--------|---------|-------------|
59 | | `sync_memory_backends.py` | Core bidirectional sync engine | `python sync/sync_memory_backends.py --status` |
60 | | `claude_sync_commands.py` | User-friendly sync wrapper | `python sync/claude_sync_commands.py backup` |
61 | | `sync_now.py` | Manual on-demand hybrid sync (v7.5.1+) | `python sync/sync_now.py --verbose` |
62 | | `export_memories.py` | Export memories to JSON | `python sync/export_memories.py` |
63 | | `import_memories.py` | Import memories from JSON | `python sync/import_memories.py data.json` |
64 |
65 | **Key Features:**
66 | - ✅ Bidirectional Cloudflare ↔ SQLite synchronization
67 | - ✅ Intelligent deduplication using content hashing
68 | - ✅ Dry-run mode for safe testing
69 | - ✅ Comprehensive status reporting
70 |
71 | #### Litestream Sync (Local Network HTTP API)
72 | Located in `sync/litestream/` - Git-like staging workflow for syncing to central SQLite-vec HTTP API server.
73 |
74 | | Script | Purpose | Quick Usage |
75 | |--------|---------|-------------|
76 | | `memory_sync.sh` | Main sync orchestrator (stash → pull → apply → push) | `./sync/litestream/memory_sync.sh sync` |
77 | | `push_to_remote.sh` | Push staged changes to remote API | `./sync/litestream/push_to_remote.sh` |
78 | | `pull_remote_changes.sh` | Pull latest from remote | `./sync/litestream/pull_remote_changes.sh` |
79 | | `stash_local_changes.sh` | Stash local changes to staging | `./sync/litestream/stash_local_changes.sh` |
80 | | `apply_local_changes.sh` | Apply staged changes locally | `./sync/litestream/apply_local_changes.sh` |
81 | | `setup_local_litestream.sh` | Initialize local Litestream setup | `./sync/litestream/setup_local_litestream.sh` |
82 | | `setup_remote_litestream.sh` | Setup remote API server | `./sync/litestream/setup_remote_litestream.sh` |
83 |
84 | **Key Features:**
85 | - ✅ Git-like staging database workflow
86 | - ✅ Conflict detection and resolution
87 | - ✅ Multi-device local network synchronization
88 | - ✅ Sync to central HTTP API (e.g., `https://narrowbox.local:8443/api/memories`)
89 | - ✅ macOS launchd service for automatic replication
90 |
91 | **Note:** Litestream sync (local network) is separate from Cloudflare hybrid sync (cloud backend)
92 |
93 | ### 🛠️ **service/** - Service Management
94 | Linux service management for production deployments.
95 |
96 | | Script | Purpose | Quick Usage |
97 | |--------|---------|-------------|
98 | | `memory_service_manager.sh` | Complete service lifecycle management | `./service/memory_service_manager.sh start-cloudflare` |
99 | | `service_control.sh` | Basic service control operations | `./service/service_control.sh restart` |
100 | | `service_utils.py` | Service utility functions | Used by other service scripts |
101 | | `deploy_dual_services.sh` | Deploy dual-backend architecture | `./service/deploy_dual_services.sh` |
102 | | `update_service.sh` | Update running service | `./service/update_service.sh` |
103 |
104 | **Key Features:**
105 | - ✅ Dual-backend configuration management
106 | - ✅ Environment file handling (.env, .env.sqlite)
107 | - ✅ Service health monitoring
108 | - ✅ Integrated sync operations
109 |
110 | ### ✅ **validation/** - Configuration & System Validation
111 | Ensure proper setup and configuration.
112 |
113 | | Script | Purpose | Quick Usage |
114 | |--------|---------|-------------|
115 | | `validate_configuration_complete.py` | Comprehensive config validation | `python validation/validate_configuration_complete.py` |
116 | | `diagnose_backend_config.py` | Cloudflare backend diagnostics | `python validation/diagnose_backend_config.py` |
117 | | `validate_memories.py` | Memory data validation | `python validation/validate_memories.py` |
118 | | `validate_migration.py` | Migration validation | `python validation/validate_migration.py` |
119 | | `verify_environment.py` | Environment setup checker | `python validation/verify_environment.py` |
120 | | `verify_pytorch_windows.py` | PyTorch Windows validation | `python validation/verify_pytorch_windows.py` |
121 | | `verify_torch.py` | PyTorch installation check | `python validation/verify_torch.py` |
122 | | `check_documentation_links.py` | Documentation link validator | `python validation/check_documentation_links.py` |
123 |
124 | **Key Features:**
125 | - ✅ Claude Code global configuration validation
126 | - ✅ Cloudflare credentials verification
127 | - ✅ Environment conflict detection
128 | - ✅ Comprehensive error reporting with solutions
129 |
130 | ### 🗄️ **database/** - Database Analysis & Health
131 | Monitor and analyze database health and performance.
132 |
133 | | Script | Purpose | Quick Usage |
134 | |--------|---------|-------------|
135 | | `simple_timestamp_check.py` | Quick timestamp health check | `python database/simple_timestamp_check.py` |
136 | | `db_health_check.py` | Comprehensive health analysis | `python database/db_health_check.py` |
137 | | `analyze_sqlite_vec_db.py` | Detailed SQLite-vec analysis | `python database/analyze_sqlite_vec_db.py` |
138 | | `check_sqlite_vec_status.py` | SQLite-vec status checker | `python database/check_sqlite_vec_status.py` |
139 |
140 | **Exit Codes (for CI/CD):**
141 | - `0` - Excellent/Good health
142 | - `1` - Warning status
143 | - `2` - Critical issues
144 | - `3` - Analysis failed
145 |
146 | ### 🧹 **maintenance/** - Database Cleanup & Repair
147 | Scripts for maintaining database integrity and performance.
148 |
149 | | Script | Purpose | Quick Usage |
150 | |--------|---------|-------------|
151 | | `find_duplicates.py` | Find and remove duplicate memories | `python maintenance/find_duplicates.py --execute` |
152 | | `cleanup_corrupted_encoding.py` | Fix corrupted emoji encoding | `python maintenance/cleanup_corrupted_encoding.py --execute` |
153 | | `repair_memories.py` | Repair corrupted memory entries | `python maintenance/repair_memories.py` |
154 | | `cleanup_memories.py` | General memory cleanup | `python maintenance/cleanup_memories.py` |
155 | | `repair_sqlite_vec_embeddings.py` | Fix embedding inconsistencies | `python maintenance/repair_sqlite_vec_embeddings.py` |
156 | | `repair_zero_embeddings.py` | Fix zero/null embeddings | `python maintenance/repair_zero_embeddings.py` |
157 |
158 | **Safety Features:**
159 | - ✅ Dry-run mode available for all scripts
160 | - ✅ Comprehensive backup recommendations
161 | - ✅ Detailed reporting of changes
162 |
163 | ### 💾 **backup/** - Backup & Restore Operations
164 | Data protection and recovery operations.
165 |
166 | | Script | Purpose | Quick Usage |
167 | |--------|---------|-------------|
168 | | `backup_memories.py` | Create memory backups | `python backup/backup_memories.py` |
169 | | `restore_memories.py` | Restore from backups | `python backup/restore_memories.py backup.json` |
170 | | `backup_sqlite_vec.sh` | SQLite-vec database backup | `./backup/backup_sqlite_vec.sh` |
171 | | `export_distributable_memories.sh` | Create distributable exports | `./backup/export_distributable_memories.sh` |
172 |
173 | ### 🔄 **migration/** - Data Migration & Schema Updates
174 | Handle database migrations and data transformations.
175 |
176 | | Script | Purpose | Quick Usage |
177 | |--------|---------|-------------|
178 | | `migrate_to_cloudflare.py` | Migrate to Cloudflare backend | `python migration/migrate_to_cloudflare.py` |
179 | | `migrate_chroma_to_sqlite.py` | ChromaDB → SQLite migration | `python migration/migrate_chroma_to_sqlite.py` |
180 | | `migrate_sqlite_vec_embeddings.py` | Update embedding format | `python migration/migrate_sqlite_vec_embeddings.py` |
181 | | `migrate_timestamps.py` | Fix timestamp issues | `python migration/migrate_timestamps.py` |
182 | | `cleanup_mcp_timestamps.py` | Clean timestamp proliferation | `python migration/cleanup_mcp_timestamps.py` |
183 | | `verify_mcp_timestamps.py` | Verify timestamp consistency | `python migration/verify_mcp_timestamps.py` |
184 |
185 | ### 🏠 **installation/** - Setup & Installation
186 | Platform-specific installation and setup scripts.
187 |
188 | | Script | Purpose | Quick Usage |
189 | |--------|---------|-------------|
190 | | `install.py` | Platform-aware installer with backend selection | `python installation/install.py --storage-backend hybrid` |
191 | | `install_linux_service.py` | Linux service installation | `python installation/install_linux_service.py` |
192 | | `install_macos_service.py` | macOS service setup | `python installation/install_macos_service.py` |
193 | | `install_windows_service.py` | Windows service installation | `python installation/install_windows_service.py` |
194 | | `install_uv.py` | UV package manager installation | `python installation/install_uv.py` |
195 | | `setup_cloudflare_resources.py` | Cloudflare resource setup | `python installation/setup_cloudflare_resources.py` |
196 | | `setup_claude_mcp.sh` | Claude MCP configuration | `./installation/setup_claude_mcp.sh` |
197 | | `setup_backup_cron.sh` | Automated backup scheduling | `./installation/setup_backup_cron.sh` |
198 |
199 | ### 🐧 **linux/** - Linux Service Management Shortcuts
200 | Quick service management wrappers for Linux systemd deployments (v7.5.1+).
201 |
202 | | Script | Purpose | Quick Usage |
203 | |--------|---------|-------------|
204 | | `service_status.sh` | Check systemd service status | `./linux/service_status.sh` |
205 | | `start_service.sh` | Start mcp-memory service | `./linux/start_service.sh` |
206 | | `stop_service.sh` | Stop mcp-memory service | `./linux/stop_service.sh` |
207 | | `view_logs.sh` | View service logs | `./linux/view_logs.sh` |
208 | | `uninstall_service.sh` | Remove systemd service | `./linux/uninstall_service.sh` |
209 |
210 | **Key Features:**
211 | - ✅ Simple wrappers for systemd service management
212 | - ✅ User-level service control (~/.config/systemd/user/)
213 | - ✅ Quick status and log viewing
214 | - ✅ Clean uninstall capabilities
215 |
216 | ### 🖥️ **server/** - Server Runtime & Operations
217 | Scripts for running and managing the memory server.
218 |
219 | | Script | Purpose | Quick Usage |
220 | |--------|---------|-------------|
221 | | `run_memory_server.py` | Start memory server | `python server/run_memory_server.py` |
222 | | `run_http_server.py` | Start HTTP API server | `python server/run_http_server.py` |
223 | | `check_server_health.py` | Health check endpoint | `python server/check_server_health.py` |
224 | | `memory_offline.py` | Offline memory operations | `python server/memory_offline.py` |
225 | | `preload_models.py` | Pre-load ML models | `python server/preload_models.py` |
226 |
227 | ### 🧪 **testing/** - Test Scripts & Validation
228 | Comprehensive testing and validation scripts.
229 |
230 | | Script | Purpose | Quick Usage |
231 | |--------|---------|-------------|
232 | | `run_complete_test.py` | Complete system test | `python testing/run_complete_test.py` |
233 | | `test_memory_api.py` | API functionality tests | `python testing/test_memory_api.py` |
234 | | `test_cloudflare_backend.py` | Cloudflare backend tests | `python testing/test_cloudflare_backend.py` |
235 | | `test_sqlite_vec_embeddings.py` | Embedding system tests | `python testing/test_sqlite_vec_embeddings.py` |
236 | | `simple_test.py` | Basic functionality test | `python testing/simple_test.py` |
237 |
238 | ### 🔧 **utils/** - General Utilities
239 | Helper scripts and utility functions.
240 |
241 | | Script | Purpose | Quick Usage |
242 | |--------|---------|-------------|
243 | | `claude_commands_utils.py` | Claude command utilities | Used by Claude Code hooks |
244 | | `query_memories.py` | Direct memory querying | `python utils/query_memories.py "search term"` |
245 | | `memory_wrapper_uv.py` | UV package manager wrapper | Used by other scripts |
246 | | `generate_personalized_claude_md.sh` | Generate custom CLAUDE.md | `./utils/generate_personalized_claude_md.sh` |
247 |
248 | ### 🛠️ **development/** - Development Tools
249 | Tools for developers and debugging.
250 |
251 | | Script | Purpose | Quick Usage |
252 | |--------|---------|-------------|
253 | | `setup-git-merge-drivers.sh` | Configure git merge drivers | `./development/setup-git-merge-drivers.sh` |
254 | | `fix_mdns.sh` | Fix mDNS issues | `./development/fix_mdns.sh` |
255 | | `uv-lock-merge.sh` | Handle UV lock file merges | `./development/uv-lock-merge.sh` |
256 | | `find_orphaned_files.py` | Find orphaned database files | `python development/find_orphaned_files.py` |
257 |
258 | ## 🎯 Common Use Cases
259 |
260 | ### Initial Setup
261 | ```bash
262 | # 1. Validate environment
263 | python validation/verify_environment.py
264 |
265 | # 2. Install appropriate service
266 | python installation/install_linux_service.py
267 |
268 | # 3. Validate configuration
269 | python validation/validate_config.py
270 |
271 | # 4. Start service
272 | ./service/memory_service_manager.sh start-cloudflare
273 | ```
274 |
275 | ### Daily Operations
276 | ```bash
277 | # Check overall health
278 | ./service/memory_service_manager.sh status
279 | python database/simple_timestamp_check.py
280 |
281 | # Sync backends
282 | python sync/claude_sync_commands.py sync
283 |
284 | # Backup
285 | python sync/claude_sync_commands.py backup
286 | ```
287 |
288 | ### Troubleshooting
289 | ```bash
290 | # Validate configuration
291 | python validation/validate_config.py
292 |
293 | # Check database health
294 | python database/db_health_check.py
295 |
296 | # Fix common issues
297 | python maintenance/find_duplicates.py --execute
298 | python maintenance/cleanup_corrupted_encoding.py --execute
299 | ```
300 |
301 | ### Migration & Upgrades
302 | ```bash
303 | # Before migration - backup
304 | python backup/backup_memories.py
305 |
306 | # Migrate to new backend
307 | python migration/migrate_to_cloudflare.py
308 |
309 | # Verify migration
310 | python validation/validate_memories.py
311 | ```
312 |
313 | ## 🚨 Safety Guidelines
314 |
315 | ### Before Running Maintenance Scripts
316 | 1. **Always backup first**: `python backup/backup_memories.py`
317 | 2. **Use dry-run mode**: Most scripts support `--dry-run` or similar
318 | 3. **Test with small datasets** when possible
319 | 4. **Check database health**: `python database/simple_timestamp_check.py`
320 |
321 | ### Script Execution Order
322 | 1. **Validation** scripts first (check environment)
323 | 2. **Backup** before any data modifications
324 | 3. **Maintenance** operations (cleanup, repair)
325 | 4. **Verification** after changes
326 | 5. **Service restart** if needed
327 |
328 | ## 🔗 Integration with Documentation
329 |
330 | This scripts directory integrates with:
331 | - **CLAUDE.md**: Essential commands for Claude Code users
332 | - **AGENTS.md**: Agent development and release process
333 | - **Wiki**: Detailed setup and troubleshooting guides
334 | - **GitHub Actions**: CI/CD pipeline integration
335 |
336 | ## 📝 Adding New Scripts
337 |
338 | When adding new scripts:
339 | 1. **Choose appropriate category** based on primary function
340 | 2. **Follow naming conventions**: `snake_case.py` or `kebab-case.sh`
341 | 3. **Include proper documentation** in script headers
342 | 4. **Add safety mechanisms** for data-modifying operations
343 | 5. **Update this README** with script description
344 | 6. **Test with multiple backends** (SQLite-vec, Cloudflare)
345 |
346 | ## 🆘 Getting Help
347 |
348 | - **Configuration issues**: Run `python validation/validate_config.py`
349 | - **Database problems**: Run `python database/db_health_check.py`
350 | - **Documentation links**: Run `python validation/check_documentation_links.py`
351 | - **General health**: Run `./service/memory_service_manager.sh status`
352 |
353 | For complex issues, check the [project wiki](https://github.com/doobidoo/mcp-memory-service/wiki) or create an issue with the output from relevant diagnostic scripts.
```
--------------------------------------------------------------------------------
/scripts/maintenance/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Maintenance Scripts
2 |
3 | This directory contains maintenance and diagnostic scripts for the MCP Memory Service database.
4 |
5 | ## Quick Reference
6 |
7 | | Script | Purpose | Performance | Use Case |
8 | |--------|---------|-------------|----------|
9 | | [`check_memory_types.py`](#check_memory_typespy-new) | Display type distribution | <1s | Quick health check, pre/post-consolidation validation |
10 | | [`consolidate_memory_types.py`](#consolidate_memory_typespy-new) | Consolidate fragmented types | ~5s for 1000 updates | Type taxonomy cleanup, reduce fragmentation |
11 | | [`regenerate_embeddings.py`](#regenerate_embeddingspy) | Regenerate all embeddings | ~5min for 2600 memories | After cosine migration or embedding corruption |
12 | | [`fast_cleanup_duplicates.sh`](#fast_cleanup_duplicatessh) | Fast duplicate removal | <5s for 100+ duplicates | Bulk duplicate cleanup |
13 | | [`find_all_duplicates.py`](#find_all_duplicatespy) | Detect near-duplicates | <2s for 2000 memories | Duplicate detection and analysis |
14 | | [`find_duplicates.py`](#find_duplicatespy) | API-based duplicate finder | Slow (~90s/duplicate) | Detailed duplicate analysis via API |
15 | | [`repair_sqlite_vec_embeddings.py`](#repair_sqlite_vec_embeddingspy) | Fix embedding corruption | Varies | Repair corrupted embeddings |
16 | | [`repair_zero_embeddings.py`](#repair_zero_embeddingspy) | Fix zero-valued embeddings | Varies | Repair zero embeddings |
17 | | [`cleanup_corrupted_encoding.py`](#cleanup_corrupted_encodingpy) | Fix encoding issues | Varies | Repair encoding corruption |
18 | | [`cleanup_association_memories.py`](#cleanup_association_memoriespy) | Remove association memories (local) | <5s | After graph migration (SQLite backend) |
19 | | [`cleanup_association_memories_hybrid.py`](#cleanup_association_memories_hybridpy-new) | Remove association memories (hybrid) | ~30s | After graph migration (hybrid backend, multi-PC) |
20 | | [`backfill_graph_table.py`](#backfill_graph_tablepy) | Migrate associations to graph | <10s | Graph database migration |
21 |
22 | ## Detailed Documentation
23 |
24 | ### `check_memory_types.py` 🆕
25 |
26 | **Purpose**: Quick diagnostic tool to display memory type distribution in the database.
27 |
28 | **When to Use**:
29 | - Before running consolidation to see what needs cleanup
30 | - After consolidation to verify results
31 | - Regular health checks to monitor type fragmentation
32 | - When investigating memory organization issues
33 |
34 | **Usage**:
35 | ```bash
36 | # Display type distribution (Windows)
37 | python scripts/maintenance/check_memory_types.py
38 |
39 | # On macOS/Linux, update the database path in the script first
40 | ```
41 |
42 | **Output Example**:
43 | ```
44 | Memory Type Distribution
45 | ============================================================
46 | Total memories: 1,978
47 | Unique types: 128
48 |
49 | Memory Type Count %
50 | ------------------------------------------------------------
51 | note 609 30.8%
52 | session 89 4.5%
53 | fix 67 3.4%
54 | milestone 60 3.0%
55 | reference 45 2.3%
56 | ...
57 | ```
58 |
59 | **Performance**: < 1 second for any database size (read-only SQL query)
60 |
61 | **Features**:
62 | - Shows top 30 types by frequency
63 | - Displays total memory count and unique type count
64 | - Identifies NULL/empty types as "(empty/NULL)"
65 | - Percentage calculation for easy analysis
66 | - Zero risk (read-only operation)
67 |
68 | **Workflow Integration**:
69 | 1. Run `check_memory_types.py` to identify fragmentation
70 | 2. If types > 150, consider running consolidation
71 | 3. Run `consolidate_memory_types.py --dry-run` to preview
72 | 4. Execute `consolidate_memory_types.py` to clean up
73 | 5. Run `check_memory_types.py` again to verify improvement
74 |
75 | ### `consolidate_memory_types.py` 🆕
76 |
77 | **Purpose**: Consolidates fragmented memory types into a standardized 24-type taxonomy.
78 |
79 | **When to Use**:
80 | - Type fragmentation (e.g., `bug-fix`, `bugfix`, `technical-fix` all coexisting)
81 | - Many types with only 1-2 memories
82 | - Inconsistent naming across similar concepts
83 | - After importing memories from external sources
84 | - Monthly maintenance to prevent type proliferation
85 |
86 | **Usage**:
87 | ```bash
88 | # Preview changes (safe, read-only)
89 | python scripts/maintenance/consolidate_memory_types.py --dry-run
90 |
91 | # Execute consolidation
92 | python scripts/maintenance/consolidate_memory_types.py
93 |
94 | # Use custom mapping configuration
95 | python scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json
96 | ```
97 |
98 | **Performance**: ~5 seconds for 1,000 memory updates (Nov 2025 real-world test: 1,049 updates in 5s)
99 |
100 | **Safety Features**:
101 | - ✅ Automatic timestamped backup before execution
102 | - ✅ Dry-run mode shows preview without changes
103 | - ✅ Transaction safety (atomic with rollback on error)
104 | - ✅ Database lock detection (prevents concurrent access)
105 | - ✅ HTTP server warning (recommends stopping before execution)
106 | - ✅ Disk space verification (needs 2x database size)
107 | - ✅ Backup verification (size and existence checks)
108 |
109 | **Standard 24-Type Taxonomy**:
110 |
111 | **Content Types:** `note`, `reference`, `document`, `guide`
112 | **Activity Types:** `session`, `implementation`, `analysis`, `troubleshooting`, `test`
113 | **Artifact Types:** `fix`, `feature`, `release`, `deployment`
114 | **Progress Types:** `milestone`, `status`
115 | **Infrastructure Types:** `configuration`, `infrastructure`, `process`, `security`, `architecture`
116 | **Other Types:** `documentation`, `solution`, `achievement`, `technical`
117 |
118 | **Example Consolidations**:
119 | - NULL/empty → `note`
120 | - `bug-fix`, `bugfix`, `technical-fix` → `fix`
121 | - `session-summary`, `session-checkpoint` → `session`
122 | - `project-milestone`, `development-milestone` → `milestone`
123 | - All `technical-*` → base type (remove prefix)
124 | - All `project-*` → base type (remove prefix)
125 |
126 | **Typical Results** (from production database, Nov 2025):
127 | ```
128 | Before: 342 unique types, 609 NULL/empty, fragmented naming
129 | After: 128 unique types (63% reduction), all valid types
130 | Updated: 1,049 memories (59% of database)
131 | Time: ~5 seconds
132 | ```
133 |
134 | **Configuration**:
135 |
136 | Edit `consolidation_mappings.json` to customize behavior:
137 | ```json
138 | {
139 | "mappings": {
140 | "old-type-name": "new-type-name",
141 | "bug-fix": "fix",
142 | "technical-solution": "solution"
143 | }
144 | }
145 | ```
146 |
147 | **Prerequisites**:
148 | ```bash
149 | # 1. Stop HTTP server
150 | systemctl --user stop mcp-memory-http.service
151 |
152 | # 2. Disconnect MCP clients (Claude Code: /mcp command)
153 |
154 | # 3. Verify disk space (need 2x database size)
155 | df -h ~/.local/share/mcp-memory/
156 | ```
157 |
158 | **Recovery**:
159 | ```bash
160 | # If something goes wrong, restore from automatic backup
161 | cp ~/.local/share/mcp-memory/sqlite_vec.db.backup-TIMESTAMP ~/.local/share/mcp-memory/sqlite_vec.db
162 |
163 | # Verify restoration
164 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*), COUNT(DISTINCT memory_type) FROM memories;"
165 | ```
166 |
167 | **Notes**:
168 | - Creates timestamped backup automatically (e.g., `sqlite_vec.db.backup-20251101-202042`)
169 | - No data loss - only type reassignment
170 | - Safe to run multiple times (idempotent for same mappings)
171 | - Comprehensive reporting shows before/after statistics
172 | - See `consolidation_mappings.json` for full mapping list
173 |
174 | **Maintenance Schedule**:
175 | - Run `--dry-run` monthly to check fragmentation
176 | - Execute when unique types exceed 150
177 | - Review custom mappings quarterly
178 |
179 | ---
180 |
181 | ### `regenerate_embeddings.py`
182 |
183 | **Purpose**: Regenerates embeddings for all memories in the database after schema migrations or corruption.
184 |
185 | **When to Use**:
186 | - After cosine distance migration
187 | - When embeddings table is dropped but memories are preserved
188 | - After embedding corruption detected
189 |
190 | **Usage**:
191 | ```bash
192 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/regenerate_embeddings.py
193 | ```
194 |
195 | **Performance**: ~5 minutes for 2600 memories with all-MiniLM-L6-v2 model
196 |
197 | **Notes**:
198 | - Uses configured storage backend (hybrid, cloudflare, or sqlite_vec)
199 | - Creates embeddings using sentence-transformers model
200 | - Shows progress every 100 memories
201 | - Safe to run multiple times (idempotent)
202 |
203 | ---
204 |
205 | ### `fast_cleanup_duplicates.sh`
206 |
207 | **Purpose**: Fast duplicate removal using direct SQL access instead of API calls.
208 |
209 | **When to Use**:
210 | - Bulk duplicate cleanup after detecting duplicates
211 | - When API-based deletion is too slow (>1min per duplicate)
212 | - Production cleanup without extended downtime
213 |
214 | **Usage**:
215 | ```bash
216 | bash scripts/maintenance/fast_cleanup_duplicates.sh
217 | ```
218 |
219 | **Performance**: <5 seconds for 100+ duplicates
220 |
221 | **How It Works**:
222 | 1. Stops HTTP server to avoid database locking
223 | 2. Uses direct SQL DELETE with timestamp normalization
224 | 3. Keeps newest copy of each duplicate group
225 | 4. Restarts HTTP server automatically
226 |
227 | **Warnings**:
228 | - ⚠️ Requires systemd HTTP server setup (`mcp-memory-http.service`)
229 | - ⚠️ Brief service interruption during cleanup
230 | - ⚠️ Direct database access bypasses Cloudflare sync (background sync handles it later)
231 |
232 | ---
233 |
234 | ### `find_all_duplicates.py`
235 |
236 | **Purpose**: Fast duplicate detection using content normalization and hash comparison.
237 |
238 | **When to Use**:
239 | - Regular duplicate audits
240 | - Before running cleanup operations
241 | - Investigating duplicate memory issues
242 |
243 | **Usage**:
244 | ```bash
245 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_all_duplicates.py
246 | ```
247 |
248 | **Performance**: <2 seconds for 2000 memories
249 |
250 | **Detection Method**:
251 | - Normalizes content by removing timestamps (dates, ISO timestamps)
252 | - Groups memories by MD5 hash of normalized content
253 | - Reports duplicate groups with counts
254 |
255 | **Output**:
256 | ```
257 | Found 23 groups of duplicates
258 | Total memories to delete: 115
259 | Total memories after cleanup: 1601
260 | ```
261 |
262 | ---
263 |
264 | ### `find_duplicates.py`
265 |
266 | **Purpose**: Comprehensive duplicate detection via HTTP API with detailed analysis.
267 |
268 | **When to Use**:
269 | - Need detailed duplicate analysis with full metadata
270 | - API-based workflow required
271 | - Integration with external tools
272 |
273 | **Usage**:
274 | ```bash
275 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_duplicates.py
276 | ```
277 |
278 | **Performance**: Slow (~90 seconds per duplicate deletion)
279 |
280 | **Features**:
281 | - Loads configuration from Claude hooks config
282 | - Supports self-signed SSL certificates
283 | - Pagination support for large datasets
284 | - Detailed duplicate grouping and reporting
285 |
286 | **Notes**:
287 | - 15K script with comprehensive error handling
288 | - Useful for API integration scenarios
289 | - Slower than `find_all_duplicates.py` due to network overhead
290 |
291 | ---
292 |
293 | ### `repair_sqlite_vec_embeddings.py`
294 |
295 | **Purpose**: Repairs corrupted embeddings in the sqlite-vec virtual table.
296 |
297 | **When to Use**:
298 | - Embedding corruption detected
299 | - vec0 extension errors
300 | - Database integrity issues
301 |
302 | **Usage**:
303 | ```bash
304 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/repair_sqlite_vec_embeddings.py
305 | ```
306 |
307 | **Warnings**:
308 | - ⚠️ Requires vec0 extension to be properly installed
309 | - ⚠️ May drop and recreate embeddings table
310 |
311 | ---
312 |
313 | ### `repair_zero_embeddings.py`
314 |
315 | **Purpose**: Detects and fixes memories with zero-valued embeddings.
316 |
317 | **When to Use**:
318 | - Search results showing 0% similarity scores
319 | - After embedding regeneration failures
320 | - Embedding quality issues
321 |
322 | **Usage**:
323 | ```bash
324 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/repair_zero_embeddings.py
325 | ```
326 |
327 | ---
328 |
329 | ### `cleanup_corrupted_encoding.py`
330 |
331 | **Purpose**: Fixes encoding corruption issues in memory content.
332 |
333 | **When to Use**:
334 | - UTF-8 encoding errors
335 | - Display issues with special characters
336 | - After data migration from different encoding
337 |
338 | **Usage**:
339 | ```bash
340 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/cleanup_corrupted_encoding.py
341 | ```
342 |
343 | ---
344 |
345 | ### `cleanup_association_memories_hybrid.py` 🆕
346 |
347 | **Purpose**: Removes association memories from BOTH Cloudflare D1 AND local SQLite. Essential for hybrid backend with multi-PC setups where drift-sync can restore deleted associations.
348 |
349 | **When to Use**:
350 | - After graph migration (`backfill_graph_table.py`) when using **hybrid backend**
351 | - When `MCP_GRAPH_STORAGE_MODE=graph_only` is set
352 | - Multi-PC environments where associations were deleted on one PC but restored via Cloudflare sync
353 | - When `cleanup_association_memories.py` (local-only) doesn't prevent restoration
354 |
355 | **The Multi-PC Problem**:
356 | ```
357 | ┌─────────────┐ sync ┌─────────────┐ sync ┌─────────────┐
358 | │ Windows PC │ ◄──────────► │ Cloudflare │ ◄──────────► │ Linux PC │
359 | │ deleted 1441│ │ D1 still │ │ restored! │
360 | │ associations│ │ has them │ │ │
361 | └─────────────┘ └─────────────┘ └─────────────┘
362 | ```
363 |
364 | **The Solution**: Clean Cloudflare D1 FIRST, then local. Other PCs auto-sync the deletion.
365 |
366 | **Usage**:
367 | ```bash
368 | # Preview (always start with dry-run)
369 | python scripts/maintenance/cleanup_association_memories_hybrid.py --dry-run
370 |
371 | # Execute full cleanup
372 | python scripts/maintenance/cleanup_association_memories_hybrid.py --apply
373 |
374 | # Skip Vectorize cleanup (optional - orphaned vectors are harmless)
375 | python scripts/maintenance/cleanup_association_memories_hybrid.py --apply --skip-vectorize
376 |
377 | # Only clean Cloudflare (useful from any PC)
378 | python scripts/maintenance/cleanup_association_memories_hybrid.py --apply --cloudflare-only
379 |
380 | # Only clean local (if Cloudflare already cleaned)
381 | python scripts/maintenance/cleanup_association_memories_hybrid.py --apply --local-only
382 | ```
383 |
384 | **Performance**: ~30 seconds for 1,400 associations (Cloudflare API batching)
385 |
386 | **Safety Features**:
387 | - ✅ Dry-run mode with detailed preview
388 | - ✅ Automatic local database backup before deletion
389 | - ✅ Confirmation prompt before destructive operations
390 | - ✅ Graph table verification (aborts if graph missing)
391 | - ✅ Cloudflare D1 cleaned first (prevents sync restoration)
392 | - ✅ Robust Vectorize error handling (non-fatal errors)
393 |
394 | **Prerequisites**:
395 | 1. Graph table must exist: Run `backfill_graph_table.py` first
396 | 2. Set `MCP_GRAPH_STORAGE_MODE=graph_only` in environment
397 | 3. Cloudflare credentials configured (API token, account ID, D1 database ID)
398 |
399 | **Comparison with `cleanup_association_memories.py`**:
400 |
401 | | Script | Backend | Cleans | Multi-PC Safe |
402 | |--------|---------|--------|---------------|
403 | | `cleanup_association_memories.py` | SQLite-vec | Local only | ❌ No |
404 | | `cleanup_association_memories_hybrid.py` | Hybrid | Cloudflare + Local | ✅ Yes |
405 |
406 | **Typical Results** (from production, Dec 2025):
407 | ```
408 | Cloudflare D1: 1,441 memories deleted
409 | Cloudflare Vectorize: 1,441 vectors deleted (or skipped)
410 | Local SQLite: 1,441 memories deleted
411 | Space reclaimed: ~2.5 MB
412 | ```
413 |
414 | ---
415 |
416 | ## Best Practices
417 |
418 | ### Before Running Maintenance Scripts
419 |
420 | 1. **Backup your database**:
421 | ```bash
422 | cp ~/.local/share/mcp-memory/sqlite_vec.db ~/.local/share/mcp-memory/sqlite_vec.db.backup
423 | ```
424 |
425 | 2. **Check memory count**:
426 | ```bash
427 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*) FROM memories"
428 | ```
429 |
430 | 3. **Stop HTTP server if needed** (for direct database access):
431 | ```bash
432 | systemctl --user stop mcp-memory-http.service
433 | ```
434 |
435 | ### After Running Maintenance Scripts
436 |
437 | 1. **Verify results**:
438 | ```bash
439 | sqlite3 ~/.local/share/mcp-memory/sqlite_vec.db "SELECT COUNT(*) FROM memories"
440 | ```
441 |
442 | 2. **Check for duplicates**:
443 | ```bash
444 | /home/hkr/repositories/mcp-memory-service/venv/bin/python scripts/maintenance/find_all_duplicates.py
445 | ```
446 |
447 | 3. **Restart HTTP server**:
448 | ```bash
449 | systemctl --user start mcp-memory-http.service
450 | ```
451 |
452 | 4. **Test search functionality**:
453 | ```bash
454 | curl -s "http://127.0.0.1:8000/api/health"
455 | ```
456 |
457 | ### Performance Comparison
458 |
459 | | Operation | API-based | Direct SQL | Speedup |
460 | |-----------|-----------|------------|---------|
461 | | Delete 1 duplicate | ~90 seconds | ~0.05 seconds | **1800x faster** |
462 | | Delete 100 duplicates | ~2.5 hours | <5 seconds | **1800x faster** |
463 | | Find duplicates | ~30 seconds | <2 seconds | **15x faster** |
464 |
465 | **Recommendation**: Use direct SQL scripts (`fast_cleanup_duplicates.sh`, `find_all_duplicates.py`) for production maintenance. API-based scripts are useful for integration and detailed analysis.
466 |
467 | ## Troubleshooting
468 |
469 | ### "Database is locked"
470 |
471 | **Cause**: HTTP server or MCP server has open connection
472 |
473 | **Solution**:
474 | ```bash
475 | # Stop HTTP server
476 | systemctl --user stop mcp-memory-http.service
477 |
478 | # Disconnect MCP server in Claude Code
479 | # Type: /mcp
480 |
481 | # Run maintenance script
482 | bash scripts/maintenance/fast_cleanup_duplicates.sh
483 |
484 | # Restart services
485 | systemctl --user start mcp-memory-http.service
486 | ```
487 |
488 | ### "No such module: vec0"
489 |
490 | **Cause**: Python sqlite3 module doesn't load vec0 extension automatically
491 |
492 | **Solution**: Use scripts that work with the vec0-enabled environment:
493 | - ✅ Use: `fast_cleanup_duplicates.sh` (bash wrapper with Python)
494 | - ✅ Use: `/venv/bin/python` with proper storage backend
495 | - ❌ Avoid: Direct `sqlite3` Python module for virtual table operations
496 |
497 | ### Slow API Performance
498 |
499 | **Cause**: Hybrid backend syncs each operation to Cloudflare
500 |
501 | **Solution**: Use direct SQL scripts for bulk operations:
502 | ```bash
503 | bash scripts/maintenance/fast_cleanup_duplicates.sh # NOT Python API scripts
504 | ```
505 |
506 | ## Related Documentation
507 |
508 | - [Database Schema](../../docs/database-schema.md) - sqlite-vec table structure
509 | - [Storage Backends](../../CLAUDE.md#storage-backends) - Hybrid, Cloudflare, SQLite-vec
510 | - [Troubleshooting](../../docs/troubleshooting.md) - Common issues and solutions
511 |
512 | ## Contributing
513 |
514 | When adding new maintenance scripts:
515 |
516 | 1. Add comprehensive docstring explaining purpose and usage
517 | 2. Include progress indicators for long-running operations
518 | 3. Add error handling and validation
519 | 4. Document in this README with performance characteristics
520 | 5. Test with both sqlite_vec and hybrid backends
521 |
```