This is page 2 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
│ ├── publish-dual.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-lite.toml
├── 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
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service
2 |
3 | [](https://opensource.org/licenses/Apache-2.0)
4 | [](https://pypi.org/project/mcp-memory-service/)
5 | [](https://pypi.org/project/mcp-memory-service/)
6 | [](https://github.com/doobidoo/mcp-memory-service/stargazers)
7 | [](https://claude.ai)
8 | [](https://cursor.sh)
9 |
10 | ## Stop Re-Explaining Your Project to AI Every Session
11 |
12 | <p align="center">
13 | <img width="240" alt="MCP Memory Service" src="https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555" />
14 | </p>
15 |
16 | Your AI assistant forgets everything when you start a new chat. After 50 tool uses, context explodes to 500k+ tokens—Claude slows down, you restart, and now it remembers nothing. You spend 10 minutes re-explaining your architecture. **Again.**
17 |
18 | **MCP Memory Service solves this.**
19 |
20 | It automatically captures your project context, architecture decisions, and code patterns. When you start fresh sessions, your AI already knows everything—no re-explaining, no context loss, no wasted time.
21 |
22 | ### ⚡ Works With Your Favorite AI Tools
23 |
24 | #### 🖥️ CLI & Terminal AI
25 | **Claude Code** · **Gemini Code Assist** · **Aider** · **GitHub Copilot CLI** · **Amp** · **Continue** · **Zed** · **Cody**
26 |
27 | #### 🎨 Desktop & IDE
28 | **Claude Desktop** · **VS Code** · **Cursor** · **Windsurf** · **Raycast** · **JetBrains** · **Sourcegraph** · **Qodo**
29 |
30 | **Works seamlessly with any MCP-compatible client** - whether you code in the terminal, IDE, or browser.
31 |
32 | ---
33 |
34 | ## 🚀 Get Started in 60 Seconds
35 |
36 | **Express Install** (recommended for most users):
37 |
38 | ```bash
39 | pip install mcp-memory-service
40 | # Auto-configure for Claude Desktop (macOS/Linux)
41 | python -m mcp_memory_service.scripts.installation.install --quick
42 | ```
43 |
44 | **What just happened?**
45 | - ✅ Installed memory service
46 | - ✅ Configured optimal backend (SQLite)
47 | - ✅ Set up Claude Desktop integration
48 | - ✅ Enabled automatic context capture
49 |
50 | **Next:** Restart Claude Desktop. Your AI now remembers everything across sessions.
51 |
52 | <details>
53 | <summary><strong>📦 Alternative: PyPI + Manual Configuration</strong></summary>
54 |
55 | ```bash
56 | pip install mcp-memory-service
57 | ```
58 |
59 | Then add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
60 | ```json
61 | {
62 | "mcpServers": {
63 | "memory": {
64 | "command": "memory",
65 | "args": ["server"]
66 | }
67 | }
68 | }
69 | ```
70 |
71 | </details>
72 |
73 | <details>
74 | <summary><strong>🔧 Advanced: Custom Backends & Team Setup</strong></summary>
75 |
76 | For production deployments, team collaboration, or cloud sync:
77 |
78 | ```bash
79 | git clone https://github.com/doobidoo/mcp-memory-service.git
80 | cd mcp-memory-service
81 | python scripts/installation/install.py
82 | ```
83 |
84 | Choose from:
85 | - **SQLite** (local, fast, single-user)
86 | - **Cloudflare** (cloud, multi-device sync)
87 | - **Hybrid** (best of both: 5ms local + background cloud sync)
88 |
89 | </details>
90 |
91 | ---
92 |
93 | ## 💡 Why You Need This
94 |
95 | ### The Problem
96 |
97 | | Session 1 | Session 2 (Fresh Start) |
98 | |-----------|-------------------------|
99 | | You: "We're building a Next.js app with Prisma and tRPC" | AI: "What's your tech stack?" ❌ |
100 | | AI: "Got it, I see you're using App Router" | You: *Explains architecture again for 10 minutes* 😤 |
101 | | You: "Add authentication with NextAuth" | AI: "Should I use Pages Router or App Router?" ❌ |
102 |
103 | ### The Solution
104 |
105 | | Session 1 | Session 2 (Fresh Start) |
106 | |-----------|-------------------------|
107 | | You: "We're building a Next.js app with Prisma and tRPC" | AI: "I remember—Next.js App Router with Prisma and tRPC. What should we build?" ✅ |
108 | | AI: "Got it, I see you're using App Router" | You: "Add OAuth login" |
109 | | You: "Add authentication with NextAuth" | AI: "I'll integrate NextAuth with your existing Prisma setup." ✅ |
110 |
111 | **Result:** Zero re-explaining. Zero context loss. Just continuous, intelligent collaboration.
112 |
113 | ---
114 |
115 | ## 🌐 SHODH Ecosystem Compatibility
116 |
117 | MCP Memory Service is **fully compatible** with the [SHODH Unified Memory API Specification v1.0.0](https://github.com/varun29ankuS/shodh-memory/blob/main/specs/openapi.yaml), enabling seamless interoperability across the SHODH ecosystem.
118 |
119 | ### Compatible Implementations
120 |
121 | | Implementation | Backend | Embeddings | Use Case |
122 | |----------------|---------|------------|----------|
123 | | **[shodh-memory](https://github.com/varun29ankuS/shodh-memory)** | RocksDB | MiniLM-L6-v2 (ONNX) | Reference implementation |
124 | | **[shodh-cloudflare](https://github.com/doobidoo/shodh-cloudflare)** | Cloudflare Workers + Vectorize | Workers AI (bge-small) | Edge deployment, multi-device sync |
125 | | **mcp-memory-service** (this) | SQLite-vec / Hybrid | MiniLM-L6-v2 (ONNX) | Desktop AI assistants (MCP) |
126 |
127 | ### Unified Schema Support
128 |
129 | All SHODH implementations share the same memory schema:
130 | - ✅ **Emotional Metadata**: `emotion`, `emotional_valence`, `emotional_arousal`
131 | - ✅ **Episodic Memory**: `episode_id`, `sequence_number`, `preceding_memory_id`
132 | - ✅ **Source Tracking**: `source_type`, `credibility`
133 | - ✅ **Quality Scoring**: `quality_score`, `access_count`, `last_accessed_at`
134 |
135 | **Interoperability Example:**
136 | Export memories from mcp-memory-service → Import to shodh-cloudflare → Sync across devices → Full fidelity preservation of emotional_valence, episode_id, and all spec fields.
137 |
138 | ---
139 |
140 | ## ✨ Key Features
141 |
142 | 🧠 **Persistent Memory** – Context survives across sessions with semantic search
143 | 🔍 **Smart Retrieval** – Finds relevant context automatically using AI embeddings
144 | ⚡ **5ms Speed** – Instant context injection, no latency
145 | 🔄 **Multi-Client** – Works across 13+ AI applications
146 | ☁️ **Cloud Sync** – Optional Cloudflare backend for team collaboration
147 | 🔒 **Privacy-First** – Local-first, you control your data
148 | 📊 **Web Dashboard** – Visualize and manage memories at `http://localhost:8000`
149 |
150 | ---
151 |
152 |
153 | ## 🆕 Latest Release: **v8.76.0** (Jan 12, 2026)
154 |
155 | **Official Lite Distribution - mcp-memory-service-lite Package**
156 |
157 | - 📦 **New Lite Package** - Official `mcp-memory-service-lite` package for ONNX-only installations (90% size reduction: 7.7GB → 805MB)
158 | - 🤖 **Automated Dual Publishing** - CI/CD workflow publishes both full and lite packages to PyPI automatically
159 | - 🔌 **Conditional Loading** - Transformers dependency becomes truly optional, loaded only when needed
160 | - 🐛 **Multi-Protocol Port Detection** - Fixed HTTP/HTTPS health check issues with cross-platform fallback (lsof → ss → netstat → ps)
161 |
162 | **Previous Releases**:
163 | - **v8.75.1** - Hook Installer Fix (flexible MCP server naming support, custom configurations)
164 | - **v8.75.0** - Lightweight ONNX Quality Scoring (90% installation size reduction: 7.7GB → 805MB, same quality scoring performance)
165 | - **v8.74.0** - Cross-Platform Orphan Process Cleanup (database lock prevention, automatic orphan detection after crashes)
166 | - **v8.73.0** - Universal Permission Request Hook (auto-approves safe operations, eliminates repetitive prompts for 12+ tools)
167 | - **v8.72.0** - Graph Traversal MCP Tools (find_connected_memories, find_shortest_path, get_memory_subgraph - 5-25ms, 30x faster)
168 | - **v8.71.0** - Memory Management APIs and Graceful Shutdown (cache cleanup, process monitoring, production-ready memory management)
169 | - **v8.70.0** - User Override Commands for Memory Hooks (`#skip`/`#remember` for manual memory control)
170 | - **v8.69.0** - MCP Tool Annotations for Improved LLM Decision-Making (readOnlyHint/destructiveHint, auto-approval for 12 tools)
171 | - **v8.68.2** - Platform Detection Improvements (Apple Silicon MPS support, 3-5x faster, comprehensive hardware detection)
172 | - **v8.68.1** - Critical Data Integrity Bug Fix - Hybrid Backend (ghost memories fixed, 5 method fixes)
173 | - **v8.68.0** - Update & Restart Automation (87% time reduction, <2 min workflow, cross-platform scripts)
174 | - **v8.62.13** - HTTP-MCP Bridge API Endpoint Fix (Remote deployments restored with POST endpoints)
175 | - **v8.62.12** - Quality Analytics UI Fixed ("Invalid Date" and "ID: undefined" bugs)
176 | - **v8.62.10** - Document Ingestion Bug Fixed (NameError in web console, circular import prevention)
177 | - **v8.62.8** - Environment Configuration Loading Bug Fixed (.env discovery, python-dotenv dependency)
178 | - **v8.62.7** - Windows SessionStart Hook Bug Fixed in Claude Code 2.0.76+ (no more Windows hanging)
179 | - **v8.62.6** - CRITICAL PRODUCTION HOTFIX: SQLite Pragmas Container Restart Bug (database locking errors after container restarts)
180 | - **v8.62.5** - Test Suite Stability: 40 Tests Fixed (99% pass rate, 68% → 99% improvement)
181 | - **v8.62.4** - CRITICAL BUGFIX: SQLite-Vec KNN Syntax Error (semantic search completely broken on sqlite-vec/hybrid backends)
182 | - **v8.62.3** - CRITICAL BUGFIX: Memory Recall Handler Import Error (time_parser import path correction)
183 | - **v8.62.2** - Test Infrastructure Improvements (5 test failures resolved, consolidation & performance suite stability)
184 | - **v8.62.1** - Critical Bug Fix: SessionEnd Hook Real Conversation Data (hardcoded mock data fix, robust transcript parsing)
185 | - **v8.62.0** - Comprehensive Test Coverage Infrastructure - 100% Handler Coverage Achievement (35 tests, 800+ lines, CI/CD gate)
186 | - **v8.61.2** - CRITICAL HOTFIX: delete_memory KeyError Fix (response parsing, validated delete flow)
187 | - **v8.61.1** - CRITICAL HOTFIX: Import Error Fix (5 MCP tools restored, relative import path correction)
188 | - **v8.60.0** - Health Check Strategy Pattern Refactoring - Phase 3.1 (78% complexity reduction, Strategy pattern)
189 | - **v8.59.0** - Server Architecture Refactoring - Phase 2 (40% code reduction, 29 handlers extracted, 5 specialized modules)
190 | - **v8.58.0** - Test Infrastructure Stabilization - 100% Pass Rate Achievement (81.6% → 100%, 52 tests fixed)
191 | - **v8.57.1** - Hotfix: Python -m Execution Support for CI/CD (server/__main__.py, --version/--help flags)
192 | - **v8.57.0** - Test Infrastructure Improvements - Major Stability Boost (+6% pass rate, 32 tests fixed)
193 | - **v8.56.0** - Server Architecture Refactoring - Phase 1 (4 focused modules, -7% lines, backward compatible)
194 | - **v8.55.0** - AI-Optimized MCP Tool Descriptions (30-50% reduction in incorrect tool selection)
195 | - **v8.54.4** - Critical MCP Tool Bugfix (check_database_health method call correction)
196 | - **v8.54.3** - Chunked Storage Error Reporting Fix (accurate failure messages, partial success tracking)
197 | - **v8.54.2** - Offline Mode Fix (opt-in offline mode, first-time install support)
198 | - **v8.54.1** - UV Virtual Environment Support (installer compatibility fix)
199 | - **v8.54.0** - Smart Auto-Capture System (intelligent pattern detection, 6 memory types, bilingual support)
200 | - **v8.53.0** - Windows Service Management (Task Scheduler support, auto-startup, watchdog monitoring, 819 lines PowerShell automation)
201 | - **v8.52.2** - Hybrid Backend Maintenance Enhancement (multi-PC association cleanup, drift prevention, Vectorize error handling)
202 | - **v8.52.1** - Windows Embedding Fallback & Script Portability (DLL init failure fix, MCP_HTTP_PORT support)
203 | - **v8.52.0** - Time-of-Day Emoji Icons (8 time-segment indicators, dark mode support, automatic timezone)
204 | - **v8.51.0** - Graph Database Architecture (30x query performance, 97% storage reduction for associations)
205 | - **v8.50.1** - Critical Bug Fixes (MCP_EMBEDDING_MODEL fix, installation script backend support, i18n quality analytics complete)
206 | - **v8.50.0** - Fallback Quality Scoring (DeBERTa + MS-MARCO hybrid, technical content rescue, 20/20 tests passing)
207 | - **v8.49.0** - DeBERTa Quality Classifier (absolute quality assessment, eliminates self-matching bias)
208 | - **v8.48.4** - Cloudflare D1 Drift Detection Performance (10-100x faster queries, numeric comparison fix)
209 | - **v8.48.3** - Code Execution Hook Fix - 75% token reduction now working (fixed time_filter parameter, Python warnings, venv detection)
210 | - **v8.48.2** - HTTP Server Auto-Start & Time Parser Improvements (smart service management, "last N periods" support)
211 | - **v8.48.1** - Critical Hotfix - Startup Failure Fix (redundant calendar import removed, immediate upgrade required)
212 | - **v8.48.0** - CSV-Based Metadata Compression (78% size reduction, 100% sync success, metadata validation)
213 | - **v8.47.1** - ONNX Quality Evaluation Bug Fixes (self-match fix, association pollution, sync queue overflow, realistic distribution)
214 | - **v8.47.0** - Association-Based Quality Boost (connection-based enhancement, network effect leverage, metadata persistence)
215 | - **v8.46.3** - Quality Score Persistence Fix (ONNX scores in hybrid backend, metadata normalization)
216 | - **v8.46.2** - Session-Start Hook Crash Fix + Hook Installer Improvements (client-side tag filtering, isolated version metadata)
217 | - **v8.46.1** - Windows Hooks Installer Fix + Quality System Integration (UTF-8 console configuration, backend quality scoring)
218 | - **v8.45.3** - ONNX Ranker Model Export Fix (automatic model export, offline mode support, 7-16ms CPU performance)
219 | - **v8.45.2** - Dashboard Dark Mode Consistency Fixes (global CSS overrides, Chart.js dark mode support)
220 | - **v8.45.1** - Quality System Test Infrastructure Fixes (HTTP API router, storage retrieval, async test client)
221 | - **v8.45.0** - Memory Quality System - AI-Driven Automatic Quality Scoring (ONNX-powered local SLM, multi-tier fallback, quality-based retention)
222 | - **v8.44.0** - Multi-Language Expansion (Japanese, Korean, German, French, Spanish - 359 keys each, complete i18n coverage)
223 | - **v8.43.0** - Internationalization & Quality Automation (English/Chinese i18n, Claude branch automation, quality gates)
224 | - **v8.42.1** - MCP Resource Handler Fix (`AttributeError` with Pydantic AnyUrl objects)
225 | - **v8.42.0** - Memory Awareness Enhancements (visible memory injection, quality session summaries, LLM-powered summarization)
226 | - **v8.41.2** - Hook Installer Utility File Deployment (ALL 14 utilities copied, future-proof glob pattern)
227 | - **v8.41.1** - Context Formatter Memory Sorting (recency sorting within categories, newest first)
228 | - **v8.41.0** - Session Start Hook Reliability Improvements (error suppression, clean output, memory filtering, classification fixes)
229 | - **v8.40.0** - Session Start Version Display (automatic version comparison, PyPI status labels)
230 | - **v8.39.1** - Dashboard Analytics Bug Fixes: Three critical fixes (top tags filtering, recent activity display, storage report fields)
231 | - **v8.39.0** - Performance Optimization: Storage-layer date-range filtering (10x faster analytics, 97% data transfer reduction)
232 | - **v8.38.1** - Critical Hotfix: HTTP MCP JSON-RPC 2.0 compliance fix (Claude Code/Desktop connection failures resolved)
233 | - **v8.38.0** - Code Quality: Phase 2b COMPLETE (~176-186 lines duplicate code eliminated, 10 consolidations)
234 | - **v8.37.0** - Code Quality: Phase 2a COMPLETE (5 duplicate high-complexity functions eliminated)
235 | - **v8.36.1** - Critical Hotfix: HTTP server startup crash fix (forward reference error in analytics.py)
236 | - **v8.36.0** - Code Quality: Phase 2 COMPLETE (100% of target achieved, -39 complexity points)
237 | - **v8.35.0** - Code Quality: Phase 2 Batch 1 (install.py, cloudflare.py, -15 complexity points)
238 | - **v8.34.0** - Code Quality: Phase 2 Complexity Reduction (analytics.py refactored, 11 → 6-7 complexity)
239 | - **v8.33.0** - Critical Installation Bug Fix + Code Quality Improvements (dead code cleanup, automatic MCP setup)
240 | - **v8.32.0** - Code Quality Excellence: pyscn Static Analysis Integration (multi-layer QA workflow)
241 | - **v8.31.0** - Revolutionary Batch Update Performance (21,428x faster memory consolidation)
242 | - **v8.30.0** - Analytics Intelligence: Adaptive Charts & Critical Data Fixes (accurate trend visualization)
243 | - **v8.28.1** - Critical HTTP MCP Transport JSON-RPC 2.0 Compliance Fix (Claude Code compatibility)
244 | - **v8.28.0** - Cloudflare AND/OR Tag Filtering (unified search API, 3-5x faster hybrid sync)
245 | - **v8.27.1** - Critical Hotfix: Timestamp Regression (created_at preservation during metadata sync)
246 | - **v8.26.0** - Revolutionary MCP Performance (534,628x faster tools, 90%+ cache hit rate)
247 | - **v8.25.0** - Hybrid Backend Drift Detection (automatic metadata sync, bidirectional awareness)
248 | - **v8.24.4** - Code Quality Improvements from Gemini Code Assist (regex sanitization, DOM caching)
249 | - **v8.24.3** - Test Coverage & Release Agent Improvements (tag+time filtering tests, version history fix)
250 | - **v8.24.2** - CI/CD Workflow Fixes (bash errexit handling, exit code capture)
251 | - **v8.24.1** - Test Infrastructure Improvements (27 test failures resolved, 63% → 71% pass rate)
252 | - **v8.24.0** - PyPI Publishing Enabled (automated package publishing via GitHub Actions)
253 | - **v8.23.1** - Stale Virtual Environment Prevention System (6-layer developer protection)
254 | - **v8.23.0** - Consolidation Scheduler via Code Execution API (88% token reduction)
255 |
256 | **📖 Full Details**: [CHANGELOG.md](CHANGELOG.md#8222---2025-11-09) | [All Releases](https://github.com/doobidoo/mcp-memory-service/releases)
257 |
258 | ---
259 |
260 | ## 📚 Documentation & Resources
261 |
262 | - **[Installation Guide](docs/installation.md)** – Detailed setup instructions
263 | - **[Configuration Guide](docs/mastery/configuration-guide.md)** – Backend options and customization
264 | - **[Architecture Overview](docs/architecture.md)** – How it works under the hood
265 | - **[Team Setup Guide](docs/teams.md)** – OAuth and cloud collaboration
266 | - **[Troubleshooting](docs/troubleshooting/)** – Common issues and solutions
267 | - **[API Reference](docs/api.md)** – Programmatic usage
268 | - **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** – Complete documentation
269 | - [](https://deepwiki.com/doobidoo/mcp-memory-service) – AI-powered documentation assistant
270 |
271 | ---
272 |
273 | ## 🤝 Contributing
274 |
275 | We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
276 |
277 | **Quick Development Setup:**
278 | ```bash
279 | git clone https://github.com/doobidoo/mcp-memory-service.git
280 | cd mcp-memory-service
281 | pip install -e . # Editable install
282 | pytest tests/ # Run test suite
283 | ```
284 |
285 | ---
286 |
287 | ## ⭐ Support
288 |
289 | If this saves you time, give us a star! ⭐
290 |
291 | - **Issues**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)
292 | - **Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)
293 | - **Wiki**: [Documentation Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)
294 |
295 | ---
296 |
297 | ## 📄 License
298 |
299 | Apache 2.0 – See [LICENSE](LICENSE) for details.
300 |
301 | ---
302 |
303 | <p align="center">
304 | <strong>Never explain your project to AI twice.</strong><br/>
305 | Start using MCP Memory Service today.
306 | </p>
307 |
308 | ## ⚠️ v6.17.0+ Script Migration Notice
309 |
310 | **Updating from an older version?** Scripts have been reorganized for better maintainability:
311 | - **Recommended**: Use `python -m mcp_memory_service.server` in your Claude Desktop config (no path dependencies!)
312 | - **Alternative 1**: Use `uv run memory server` with UV tooling
313 | - **Alternative 2**: Update path from `scripts/run_memory_server.py` to `scripts/server/run_memory_server.py`
314 | - **Backward compatible**: Old path still works with a migration notice
315 |
316 | ## ⚠️ First-Time Setup Expectations
317 |
318 | On your first run, you'll see some warnings that are **completely normal**:
319 |
320 | - **"WARNING: Failed to load from cache: No snapshots directory"** - The service is checking for cached models (first-time setup)
321 | - **"WARNING: Using TRANSFORMERS_CACHE is deprecated"** - Informational warning, doesn't affect functionality
322 | - **Model download in progress** - The service automatically downloads a ~25MB embedding model (takes 1-2 minutes)
323 |
324 | These warnings disappear after the first successful run. The service is working correctly! For details, see our [First-Time Setup Guide](docs/first-time-setup.md).
325 |
326 | ### 🐍 Python 3.13 Compatibility Note
327 |
328 | **sqlite-vec** may not have pre-built wheels for Python 3.13 yet. If installation fails:
329 | - The installer will automatically try multiple installation methods
330 | - Consider using Python 3.12 for the smoothest experience: `brew install [email protected]`
331 | - Alternative: Use Cloudflare backend with `--storage-backend cloudflare`
332 | - See [Troubleshooting Guide](docs/troubleshooting/general.md#python-313-sqlite-vec-issues) for details
333 |
334 | ### 🍎 macOS SQLite Extension Support
335 |
336 | **macOS users** may encounter `enable_load_extension` errors with sqlite-vec:
337 | - **System Python** on macOS lacks SQLite extension support by default
338 | - **Solution**: Use Homebrew Python: `brew install python && rehash`
339 | - **Alternative**: Use pyenv: `PYTHON_CONFIGURE_OPTS='--enable-loadable-sqlite-extensions' pyenv install 3.12.0`
340 | - **Fallback**: Use Cloudflare or Hybrid backend: `--storage-backend cloudflare` or `--storage-backend hybrid`
341 | - See [Troubleshooting Guide](docs/troubleshooting/general.md#macos-sqlite-extension-issues) for details
342 |
343 | ## 🎯 Memory Awareness in Action
344 |
345 | **Intelligent Context Injection** - See how the memory service automatically surfaces relevant information at session start:
346 |
347 | <img src="docs/assets/images/memory-awareness-hooks-example.png" alt="Memory Awareness Hooks in Action" width="100%" />
348 |
349 | **What you're seeing:**
350 | - 🧠 **Automatic memory injection** - 8 relevant memories found from 2,526 total
351 | - 📂 **Smart categorization** - Recent Work, Current Problems, Additional Context
352 | - 📊 **Git-aware analysis** - Recent commits and keywords automatically extracted
353 | - 🎯 **Relevance scoring** - Top memories scored at 100% (today), 89% (8d ago), 84% (today)
354 | - ⚡ **Fast retrieval** - SQLite-vec backend with 5ms read performance
355 | - 🔄 **Background sync** - Hybrid backend syncing to Cloudflare
356 |
357 | **Result**: Claude starts every session with full project context - no manual prompting needed.
358 |
359 | ## 📚 Complete Documentation
360 |
361 | **👉 Visit our comprehensive [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) for detailed guides:**
362 |
363 | ### 🧠 v7.1.3 Natural Memory Triggers (Latest)
364 | - **[Natural Memory Triggers v7.1.3 Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)** - Intelligent automatic memory awareness
365 | - ✅ **85%+ trigger accuracy** with semantic pattern detection
366 | - ✅ **Multi-tier performance** (50ms instant → 150ms fast → 500ms intensive)
367 | - ✅ **CLI management system** for real-time configuration
368 | - ✅ **Git-aware context** integration for enhanced relevance
369 | - ✅ **Zero-restart installation** with dynamic hook loading
370 |
371 | ### 🆕 v7.0.0 OAuth & Team Collaboration
372 | - **[🔐 OAuth 2.1 Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/OAuth-2.1-Setup-Guide)** - **NEW!** Complete OAuth 2.1 Dynamic Client Registration guide
373 | - **[🔗 Integration Guide](https://github.com/doobidoo/mcp-memory-service/wiki/03-Integration-Guide)** - Claude Desktop, **Claude Code HTTP transport**, VS Code, and more
374 | - **[🛡️ Advanced Configuration](https://github.com/doobidoo/mcp-memory-service/wiki/04-Advanced-Configuration)** - **Updated!** OAuth security, enterprise features
375 |
376 | ### 🧬 v8.23.0+ Memory Consolidation
377 | - **[📊 Memory Consolidation System Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Consolidation-System-Guide)** - **NEW!** Automated memory maintenance with real-world performance metrics
378 | - ✅ **Dream-inspired consolidation** (decay scoring, association discovery, compression, archival)
379 | - ✅ **24/7 automatic scheduling** (daily/weekly/monthly via HTTP server)
380 | - ✅ **Token-efficient Code Execution API** (90% token reduction vs MCP tools)
381 | - ✅ **Real-world performance data** (4-6 min for 2,495 memories with hybrid backend)
382 | - ✅ **Three manual trigger methods** (HTTP API, MCP tools, Python API)
383 |
384 | ### 🚀 Setup & Installation
385 | - **[📋 Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** - Complete installation for all platforms and use cases
386 | - **[🖥️ Platform Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/02-Platform-Setup-Guide)** - Windows, macOS, and Linux optimizations
387 | - **[⚡ Performance Optimization](https://github.com/doobidoo/mcp-memory-service/wiki/05-Performance-Optimization)** - Speed up queries, optimize resources, scaling
388 |
389 | ### 🧠 Advanced Topics
390 | - **[👨💻 Development Reference](https://github.com/doobidoo/mcp-memory-service/wiki/06-Development-Reference)** - Claude Code hooks, API reference, debugging
391 | - **[🔧 Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)** - **Updated!** OAuth troubleshooting + common issues
392 | - **[❓ FAQ](https://github.com/doobidoo/mcp-memory-service/wiki/08-FAQ)** - Frequently asked questions
393 | - **[📝 Examples](https://github.com/doobidoo/mcp-memory-service/wiki/09-Examples)** - Practical code examples and workflows
394 |
395 | ### 📂 Internal Documentation
396 | - **[📊 Repository Statistics](docs/statistics/REPOSITORY_STATISTICS.md)** - 10 months of development metrics, activity patterns, and insights
397 | - **[🏗️ Architecture Specs](docs/architecture/)** - Search enhancement specifications and design documents
398 | - **[👩💻 Development Docs](docs/development/)** - AI agent instructions, release checklist, refactoring notes
399 | - **[🚀 Deployment Guides](docs/deployment/)** - Docker, dual-service, and production deployment
400 | - **[📚 Additional Guides](docs/guides/)** - Storage backends, migration, mDNS discovery
401 |
402 | ## ✨ Key Features
403 |
404 | ### 🏆 **Production-Ready Reliability** 🆕 v8.9.0
405 | - **Hybrid Backend** - Fast 5ms local SQLite + background Cloudflare sync (RECOMMENDED default)
406 | - Zero user-facing latency for cloud operations
407 | - Automatic multi-device synchronization
408 | - Graceful offline operation
409 | - **Zero Database Locks** - Concurrent HTTP + MCP server access works flawlessly
410 | - Auto-configured SQLite pragmas (`busy_timeout=15000,cache_size=20000`)
411 | - WAL mode with proper multi-client coordination
412 | - Tested: 5/5 concurrent writes succeeded with no errors
413 | - **Auto-Configuration** - Installer handles everything
414 | - SQLite pragmas for concurrent access
415 | - Cloudflare credentials with connection testing
416 | - Claude Desktop integration with hybrid backend
417 | - Graceful fallback to sqlite_vec if cloud setup fails
418 |
419 | ### 📄 **Document Ingestion System** v8.6.0
420 | - **Interactive Web UI** - Drag-and-drop document upload with real-time progress
421 | - **Multiple Formats** - PDF, TXT, MD, JSON with intelligent chunking
422 | - **Document Viewer** - Browse chunks, view metadata, search content
423 | - **Smart Tagging** - Automatic tagging with length validation (max 100 chars)
424 | - **Optional semtools** - Enhanced PDF/DOCX/PPTX parsing with LlamaParse
425 | - **Security Hardened** - Path traversal protection, XSS prevention, input validation
426 | - **7 New Endpoints** - Complete REST API for document management
427 |
428 | ### 🔐 **Enterprise Authentication & Team Collaboration**
429 | - **OAuth 2.1 Dynamic Client Registration** - RFC 7591 & RFC 8414 compliant
430 | - **Claude Code HTTP Transport** - Zero-configuration team collaboration
431 | - **JWT Authentication** - Enterprise-grade security with scope validation
432 | - **Auto-Discovery Endpoints** - Seamless client registration and authorization
433 | - **Multi-Auth Support** - OAuth + API keys + optional anonymous access
434 |
435 | ### 🧠 **Intelligent Memory Management**
436 | - **Semantic search** with vector embeddings
437 | - **Natural language time queries** ("yesterday", "last week")
438 | - **Tag-based organization** with smart categorization
439 | - **Memory consolidation** with dream-inspired algorithms
440 | - **Document-aware search** - Query across uploaded documents and manual memories
441 |
442 | ### 🔗 **Universal Compatibility**
443 | - **Claude Desktop** - Native MCP integration
444 | - **Claude Code** - **HTTP transport** + Memory-aware development with hooks
445 | - 🪟 **Windows Support**: `/session-start` command for manual session initialization (workaround for issue #160)
446 | - 🍎 **macOS/Linux**: Full automatic SessionStart hooks + slash command
447 | - **VS Code, Cursor, Continue** - IDE extensions
448 | - **13+ AI applications** - REST API compatibility
449 |
450 | ### 💾 **Flexible Storage**
451 | - **Hybrid** 🌟 (RECOMMENDED) - Fast local SQLite + background Cloudflare sync (v8.9.0 default)
452 | - 5ms local reads with zero user-facing latency
453 | - Multi-device synchronization
454 | - Zero database locks with auto-configured pragmas
455 | - Automatic backups and cloud persistence
456 | - **SQLite-vec** - Local-only storage (lightweight ONNX embeddings, 5ms reads)
457 | - Good for single-user offline use
458 | - No cloud dependencies
459 | - **Cloudflare** - Cloud-only storage (global edge distribution with D1 + Vectorize)
460 | - Network-dependent performance
461 |
462 | > **Note**: All heavy ML dependencies (PyTorch, sentence-transformers) are now optional to dramatically reduce build times and image sizes. SQLite-vec uses lightweight ONNX embeddings by default. Install with `--with-ml` for full ML capabilities.
463 |
464 | ### 🚀 **Production Ready**
465 | - **Cross-platform** - Windows, macOS, Linux
466 | - **Service installation** - Auto-start background operation
467 | - **HTTPS/SSL** - Secure connections with OAuth 2.1
468 | - **Docker support** - Easy deployment with team collaboration
469 | - **Interactive Dashboard** - Web UI at http://127.0.0.1:8000/ for complete management
470 |
471 | ## 💡 Basic Usage
472 |
473 | ### 📄 **Document Ingestion** (v8.6.0+)
474 | ```bash
475 | # Start HTTP dashboard server (separate from MCP server)
476 | uv run python scripts/server/run_http_server.py
477 |
478 | # Access interactive dashboard
479 | open http://127.0.0.1:8000/
480 |
481 | # Upload documents via CLI
482 | curl -X POST http://127.0.0.1:8000/api/documents/upload \
483 | -F "[email protected]" \
484 | -F "tags=documentation,reference"
485 |
486 | # Search document content
487 | curl -X POST http://127.0.0.1:8000/api/search \
488 | -H "Content-Type: application/json" \
489 | -d '{"query": "authentication flow", "limit": 10}'
490 | ```
491 |
492 | ### 🔗 **Team Collaboration with OAuth** (v7.0.0+)
493 | ```bash
494 | # Start OAuth-enabled HTTP server for team collaboration
495 | export MCP_OAUTH_ENABLED=true
496 | uv run python scripts/server/run_http_server.py
497 |
498 | # Claude Code team members connect via HTTP transport
499 | claude mcp add --transport http memory-service http://your-server:8000/mcp
500 | # → Automatic OAuth discovery, registration, and authentication
501 | ```
502 |
503 | ### 🧠 **Memory Operations**
504 | ```bash
505 | # Store a memory
506 | uv run memory store "Fixed race condition in authentication by adding mutex locks"
507 |
508 | # Search for relevant memories
509 | uv run memory recall "authentication race condition"
510 |
511 | # Search by tags
512 | uv run memory search --tags python debugging
513 |
514 | # Check system health (shows OAuth status)
515 | uv run memory health
516 | ```
517 |
518 | ## 🔧 Configuration
519 |
520 | ### Claude Desktop Integration
521 | **Recommended approach** - Add to your Claude Desktop config (`~/.claude/config.json`):
522 |
523 | ```json
524 | {
525 | "mcpServers": {
526 | "memory": {
527 | "command": "python",
528 | "args": ["-m", "mcp_memory_service.server"],
529 | "env": {
530 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
531 | }
532 | }
533 | }
534 | }
535 | ```
536 |
537 | **Alternative approaches:**
538 | ```json
539 | // Option 1: UV tooling (if using UV)
540 | {
541 | "mcpServers": {
542 | "memory": {
543 | "command": "uv",
544 | "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
545 | "env": {
546 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
547 | }
548 | }
549 | }
550 | }
551 |
552 | // Option 2: Direct script path (v6.17.0+)
553 | {
554 | "mcpServers": {
555 | "memory": {
556 | "command": "python",
557 | "args": ["/path/to/mcp-memory-service/scripts/server/run_memory_server.py"],
558 | "env": {
559 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
560 | }
561 | }
562 | }
563 | }
564 | ```
565 |
566 | ### Environment Variables
567 |
568 | **Hybrid Backend (v8.9.0+ RECOMMENDED):**
569 | ```bash
570 | # Hybrid backend with auto-configured pragmas
571 | export MCP_MEMORY_STORAGE_BACKEND=hybrid
572 | export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"
573 |
574 | # Cloudflare credentials (required for hybrid)
575 | export CLOUDFLARE_API_TOKEN="your-token"
576 | export CLOUDFLARE_ACCOUNT_ID="your-account"
577 | export CLOUDFLARE_D1_DATABASE_ID="your-db-id"
578 | export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index"
579 |
580 | # Enable HTTP API
581 | export MCP_HTTP_ENABLED=true
582 | export MCP_HTTP_PORT=8000
583 |
584 | # Security
585 | export MCP_API_KEY="your-secure-key"
586 | ```
587 |
588 | **SQLite-vec Only (Local):**
589 | ```bash
590 | # Local-only storage
591 | export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec
592 | export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"
593 | ```
594 |
595 | ## 🏗️ Architecture
596 |
597 | ```
598 | ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
599 | │ AI Clients │ │ MCP Memory │ │ Storage Backend │
600 | │ │ │ Service v8.9 │ │ │
601 | │ • Claude Desktop│◄──►│ • MCP Protocol │◄──►│ • Hybrid 🌟 │
602 | │ • Claude Code │ │ • HTTP Transport│ │ (5ms local + │
603 | │ (HTTP/OAuth) │ │ • OAuth 2.1 Auth│ │ cloud sync) │
604 | │ • VS Code │ │ • Memory Store │ │ • SQLite-vec │
605 | │ • Cursor │ │ • Semantic │ │ • Cloudflare │
606 | │ • 13+ AI Apps │ │ Search │ │ │
607 | │ • Web Dashboard │ │ • Doc Ingestion │ │ Zero DB Locks ✅│
608 | │ (Port 8000) │ │ • Zero DB Locks │ │ Auto-Config ✅ │
609 | └─────────────────┘ └─────────────────┘ └─────────────────┘
610 | ```
611 |
612 | ## 🛠️ Development
613 |
614 | ### Project Structure
615 | ```
616 | mcp-memory-service/
617 | ├── src/mcp_memory_service/ # Core application
618 | │ ├── models/ # Data models
619 | │ ├── storage/ # Storage backends
620 | │ ├── web/ # HTTP API & dashboard
621 | │ └── server.py # MCP server
622 | ├── scripts/ # Utilities & installation
623 | ├── tests/ # Test suite
624 | └── tools/docker/ # Docker configuration
625 | ```
626 |
627 | ### Contributing
628 | 1. Fork the repository
629 | 2. Create a feature branch
630 | 3. Make your changes with tests
631 | 4. Submit a pull request
632 |
633 | See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
634 |
635 | ## 🆘 Support
636 |
637 | - **📖 Documentation**: [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) - Comprehensive guides
638 | - **🐛 Bug Reports**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)
639 | - **💬 Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)
640 | - **🔧 Troubleshooting**: [Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)
641 | - **✅ Configuration Validator**: Run `python scripts/validation/validate_configuration_complete.py` to check your setup
642 | - **🔄 Backend Sync Tools**: See [scripts/README.md](scripts/README.md#backend-synchronization) for Cloudflare↔SQLite sync
643 |
644 | ## 📊 In Production
645 |
646 | **Real-world metrics from active deployments:**
647 | - **1700+ memories** stored and actively used across teams
648 | - **5ms local reads** with hybrid backend (v8.9.0)
649 | - **Zero database locks** with concurrent HTTP + MCP access (v8.9.0)
650 | - Tested: 5/5 concurrent writes succeeded
651 | - Auto-configured pragmas prevent lock errors
652 | - **<500ms response time** for semantic search (local & HTTP transport)
653 | - **65% token reduction** in Claude Code sessions with OAuth collaboration
654 | - **96.7% faster** context setup (15min → 30sec)
655 | - **100% knowledge retention** across sessions and team members
656 | - **Zero-configuration** setup success rate: **98.5%** (OAuth + hybrid backend)
657 |
658 | ## 🏆 Recognition
659 |
660 | - [](https://smithery.ai/server/@doobidoo/mcp-memory-service) **Verified MCP Server**
661 | - [](https://glama.ai/mcp/servers/bzvl3lz34o) **Featured AI Tool**
662 | - **Production-tested** across 13+ AI applications
663 | - **Community-driven** with real-world feedback and improvements
664 |
665 | ## 📄 License
666 |
667 | Apache License 2.0 - see [LICENSE](LICENSE) for details.
668 |
669 | ---
670 |
671 | **Ready to supercharge your AI workflow?** 🚀
672 |
673 | 👉 **[Start with our Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** or explore the **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** for comprehensive documentation.
674 |
675 | *Transform your AI conversations into persistent, searchable knowledge that grows with you.*
676 | ---
677 |
678 | ## Memory Maintenance & Cleanup
679 |
680 | ### Quick Reference
681 |
682 | | Task | Method | Time | Notes |
683 | |------|--------|------|-------|
684 | | Retag single memory | Dashboard UI | 30s | Click memory → Edit → Save |
685 | | Retag 10+ memories | Dashboard bulk | 5m | Edit each individually |
686 | | Retag 100+ memories | `retag_valuable_memories.py` | 2m | Automatic, semantic tagging |
687 | | Delete test data | `delete_test_memories.py` | 1m | Bulk deletion with confirmation |
688 |
689 | ### Workflow: Clean Up Untagged Memories
690 |
691 | After experiencing sync issues (like hybrid Cloudflare race conditions), untagged memories may accumulate:
692 |
693 | ```bash
694 | # 1. Start dashboard
695 | ./start_all_servers.sh
696 |
697 | # 2. Retag valuable memories automatically
698 | python3 retag_valuable_memories.py
699 | # → 340+ memories retagged
700 | # → 0 failures
701 | ```
702 |
703 | ```bash
704 | # 3. Delete remaining test data
705 | python3 delete_test_memories.py
706 | # → 209 test memories deleted
707 | # → Database reduced from 5359 → 5150 memories
708 | ```
709 |
710 | ### Dashboard Memory Edit
711 |
712 | Open http://127.0.0.1:8000
713 |
714 | **To edit a single memory:**
715 | 1. Find memory (search or filter)
716 | 2. Click to view details
717 | 3. Click "Edit Memory"
718 | 4. Modify tags (comma-separated)
719 | 5. Click "Update Memory"
720 |
721 | **Example:**
722 | ```
723 | Before: "needs-categorization"
724 | After: "release, v8.64, bug-fix, sync"
725 | ```
726 |
727 | ### Automatic Tag Suggestions
728 |
729 | The `retag_valuable_memories.py` script uses intelligent pattern matching:
730 |
731 | **Keywords detected:**
732 | - Versions: `release`, `v8`, `v1`
733 | - Technologies: `api`, `cloudflare`, `sync`
734 | - Document types: `documentation`, `setup-guide`, `tutorial`
735 | - Projects: `shodh`, `secondbrain`, `mcp-memory-service`
736 | - Status: `important`, `needs-categorization`
737 |
738 | **Content analysis:**
739 | - Content > 500 chars → `important`
740 | - Recognizes: release notes, API docs, setup guides, session summaries
741 |
742 | ### Preventing Future Cleanup Issues
743 |
744 | **Version 8.64.0+:**
745 | - ✅ Soft-delete with tombstone support (v8.64.0)
746 | - ✅ Bidirectional sync race condition fix (v8.64.0)
747 | - ✅ Cloudflare hybrid sync validation (v8.64.1)
748 |
749 | **Best practices:**
750 | 1. Use meaningful tags from the start
751 | 2. Review untagged memories regularly
752 | 3. Run cleanup scripts after major changes
753 | 4. Verify tags in Dashboard before deletion
754 |
755 | ### See Also
756 | - [AGENTS.md](AGENTS.md) - Memory cleanup commands reference
757 | - Scripts in `scripts/maintenance/` - Auto-retagging and cleanup tools
758 |
759 |
```
--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP Memory Service - Agent Guidelines
2 |
3 | ## Available Agents
4 |
5 | ### amp-bridge
6 | **Purpose**: Leverage Amp CLI capabilities (research, code analysis, web search) without consuming Claude Code credits.
7 |
8 | **Usage**: `Use @agent-amp-bridge to research XYZ`
9 |
10 | **How it works**:
11 | 1. Agent creates concise prompt in `.claude/amp/prompts/pending/{uuid}.json`
12 | 2. Shows you command: `amp @{prompt-file}`
13 | 3. You run command in your authenticated Amp session (free tier)
14 | 4. Amp writes response to `.claude/amp/responses/ready/{uuid}.json`
15 | 5. Agent detects, reads, and presents results
16 |
17 | **Key principle**: Agent creates SHORT, focused prompts (2-4 sentences) to conserve Amp credits.
18 |
19 | **Example**:
20 | - ❌ Bad: "Research TypeScript 5.0 in detail covering: 1. Const params... 2. Decorators... 3. Export modifiers..."
21 | - ✅ Good: "Research TypeScript 5.0's key new features with brief code examples."
22 |
23 | ## Build/Lint/Test Commands
24 | - **Run all tests**: `pytest tests/`
25 | - **Run single test**: `pytest tests/test_filename.py::test_function_name -v`
26 | - **Run specific test class**: `pytest tests/test_filename.py::TestClass -v`
27 | - **Run with markers**: `pytest -m "unit or integration"`
28 | - **MCP Server startup**: `uv run memory server`
29 | - **HTTP Dashboard startup**: `python run_server.py` or `./start_all_servers.sh`
30 | - **Install dependencies**: `python scripts/installation/install.py`
31 |
32 | ## Server Management Commands
33 | - **Start all servers**: `./start_all_servers.sh` (both MCP + HTTP Dashboard)
34 | - **Stop all servers**: `./stop_all_servers.sh`
35 | - **Check server status**: `./status_servers.sh`
36 | - **View HTTP logs**: `tail -f http_server.log`
37 | - **View MCP logs**: `tail -f mcp_server.log`
38 |
39 | ## Memory Cleanup & Auto-Tagging Commands
40 |
41 | ### Individual Memory Auto-Tagging
42 | - **Auto-retag single memory (replace)**: `python3 auto_retag_memory.py --search "query"` or `python3 auto_retag_memory.py {hash}`
43 | - Analyzes content, generates tags, replaces all old tags
44 | - Best for untagged memories
45 |
46 | - **Auto-retag single memory (merge)**: `python3 auto_retag_memory_merge.py --search "query"` or `python3 auto_retag_memory_merge.py {hash}` ⭐ **RECOMMENDED**
47 | - Analyzes content, generates tags, merges with existing (preserves v8.x, project names, tech-specific)
48 | - Best for memories with some existing tags
49 | - Shows diff before applying
50 |
51 | ### Bulk Memory Operations
52 | - **Bulk retag valuable untagged memories**: `python3 retag_valuable_memories.py`
53 | - Analyzes content, identifies valuable vs. test, applies semantic tags
54 | - Skips test data automatically
55 | - ~340+ memories retagged, ~0 failures per run
56 |
57 | - **Bulk delete test memories**: `python3 delete_test_memories.py`
58 | - Identifies test data by pattern matching
59 | - Shows samples before deletion
60 | - Requires confirmation
61 | - ~209 test memories deleted per run
62 |
63 | ### Manual Editing
64 | - **Dashboard UI retagging**: http://127.0.0.1:8000
65 | - Click memory → Edit Memory → Modify tags → Save
66 | - Perfect for 1-3 memories per session
67 | - Full manual control
68 |
69 | ### See Also
70 | - Scripts located in `scripts/maintenance/` directory
71 | - Dashboard UI at http://127.0.0.1:8000 for manual editing
72 |
73 | ## Architecture & Codebase Structure
74 | - **Main package**: `src/mcp_memory_service/` - Core MCP server implementation
75 | - **Storage backends**: `storage/` (SQLite-Vec, Cloudflare, Hybrid) implementing abstract `MemoryStorage` class
76 | - **Web interface**: `web/` - FastAPI dashboard with real-time updates via SSE
77 | - **MCP protocol**: `server.py` - Model Context Protocol implementation with async handlers
78 | - **Memory consolidation**: `consolidation/` - Autonomous memory management and deduplication
79 | - **Document ingestion**: `ingestion/` - PDF/DOCX/PPTX loaders with optional semtools integration
80 | - **CLI tools**: `cli/` - Command-line interface for server management
81 |
82 | ## Code Style Guidelines
83 | - **Imports**: Absolute imports preferred, conditional imports for optional dependencies
84 | - **Types**: Python 3.10+ type hints throughout, TypedDict for MCP responses
85 | - **Async/await**: All I/O operations use async/await pattern
86 | - **Naming**: snake_case for functions/variables, PascalCase for classes, SCREAMING_SNAKE_CASE for constants
87 | - **Error handling**: Try/except blocks with specific exceptions, logging for debugging
88 | - **Memory types**: Use 24 core types from taxonomy (note, reference, session, implementation, etc.)
89 | - **Documentation**: NumPy-style docstrings, CLAUDE.md for project conventions
90 |
91 | ## Development Rules (from CLAUDE.md)
92 | - Follow MCP protocol specification for tool schemas and responses
93 | - Implement storage backends extending abstract base class
94 | - Use semantic commit messages with conventional commit format
95 | - Test both OAuth enabled/disabled modes for web interface
96 | - Validate search endpoints: semantic, tag-based, time-based queries
97 |
```
--------------------------------------------------------------------------------
/.claude/directives/agents.md:
--------------------------------------------------------------------------------
```markdown
1 | # Agent Integrations - Detailed Usage
2 |
3 | Workflow automation agents using Gemini CLI, Groq API, and Amp CLI.
4 |
5 | ## Agent Matrix
6 |
7 | | Agent | Tool | Purpose | Priority | Usage |
8 | |-------|------|---------|----------|-------|
9 | | **github-release-manager** | GitHub CLI | Complete release workflow | Production | Proactive on feature completion |
10 | | **amp-bridge** | Amp CLI | Research without Claude credits | Production | File-based prompts |
11 | | **code-quality-guard** | Gemini CLI / Groq API | Fast code quality analysis | Active | Pre-commit, pre-PR |
12 | | **gemini-pr-automator** | Gemini CLI | Automated PR review loops | Active | Post-PR creation |
13 |
14 | ## github-release-manager
15 |
16 | **Purpose**: Proactive release workflow automation with issue tracking, version management, and documentation updates.
17 |
18 | **Capabilities:**
19 | - **Version Management**: Four-file procedure (__init__.py → pyproject.toml → README.md → uv lock)
20 | - **CHANGELOG Management**: Format guidelines, conflict resolution
21 | - **Documentation Matrix**: Automatic CHANGELOG, CLAUDE.md, README.md updates
22 | - **Issue Tracking**: Auto-detects "fixes #", suggests closures with smart comments
23 | - **Release Procedure**: Merge → Tag → Push → Verify workflows
24 | - **Environment Detection** 🆕: Adapts workflow for local vs GitHub execution
25 |
26 | **Usage:**
27 | ```bash
28 | # Proactive (agent invokes automatically on feature completion)
29 | @agent github-release-manager "Check if we need a release"
30 |
31 | # Manual
32 | @agent github-release-manager "Create release for v8.20.0"
33 | ```
34 |
35 | **Post-Release Workflow**: Retrieves issues from release, suggests closures with PR links and CHANGELOG entries.
36 |
37 | See [`.claude/agents/github-release-manager.md`](../.claude/agents/github-release-manager.md) for complete workflows.
38 |
39 | ## code-quality-guard
40 |
41 | **Purpose**: Fast automated analysis for complexity scoring, security scanning, and refactoring suggestions.
42 |
43 | **Capabilities:**
44 | - Complexity check (Gemini CLI or Groq API)
45 | - Security scan (SQL injection, XSS, command injection)
46 | - TODO prioritization
47 | - Pre-commit hook integration
48 |
49 | **Usage:**
50 | ```bash
51 | # Complexity check (Gemini CLI - default)
52 | gemini "Complexity 1-10 per function, list high (>7) first: $(cat file.py)"
53 |
54 | # Complexity check (Groq API - 10x faster, default model)
55 | ./scripts/utils/groq "Complexity 1-10 per function: $(cat file.py)"
56 |
57 | # Security scan
58 | gemini "Security check (SQL injection, XSS): $(cat file.py)"
59 |
60 | # Pre-commit hook (Groq recommended - fast, non-interactive)
61 | export GROQ_API_KEY="your-groq-api-key"
62 | ln -s ../../scripts/hooks/pre-commit .git/hooks/pre-commit
63 | ```
64 |
65 | **LLM Priority:**
66 | 1. **Groq API** (Primary) - 200-300ms, no OAuth browser interruption
67 | 2. **Gemini CLI** (Fallback) - 2-3s, OAuth may interrupt commits
68 | 3. **Skip checks** - If neither available
69 |
70 | See [`.claude/agents/code-quality-guard.md`](../.claude/agents/code-quality-guard.md) for quality standards.
71 |
72 | ## gemini-pr-automator
73 |
74 | **Purpose**: Eliminates manual "Wait 1min → /gemini review" cycles with fully automated review iteration.
75 |
76 | **Capabilities:**
77 | - Full automated review (5 iterations, safe fixes enabled)
78 | - Quality gate checks before review
79 | - Test generation for new code
80 | - Breaking change detection
81 |
82 | **Usage:**
83 | ```bash
84 | # Full automated review
85 | bash scripts/pr/auto_review.sh <PR_NUMBER>
86 |
87 | # Quality gate checks
88 | bash scripts/pr/quality_gate.sh <PR_NUMBER>
89 |
90 | # Generate tests
91 | bash scripts/pr/generate_tests.sh <PR_NUMBER>
92 |
93 | # Breaking change detection
94 | bash scripts/pr/detect_breaking_changes.sh main <BRANCH>
95 | ```
96 |
97 | **Time Savings**: ~10-30 minutes per PR vs manual iteration.
98 |
99 | See [`.claude/agents/gemini-pr-automator.md`](../.claude/agents/gemini-pr-automator.md) for workflows.
100 |
101 | ## amp-bridge
102 |
103 | **Purpose**: File-based workflow for external research without consuming Claude Code credits.
104 |
105 | **Usage:**
106 | ```bash
107 | # Claude creates prompt → You run command → Amp writes response
108 | amp @.claude/amp/prompts/pending/{uuid}.json
109 | ```
110 |
111 | **Use cases**: Web research, codebase analysis, documentation generation.
112 |
113 | See [docs/amp-cli-bridge.md](../../docs/amp-cli-bridge.md) for architecture.
114 |
115 | ## Claude Branch Automation 🆕
116 |
117 | **Automated workflow** that completes Claude-generated branches with integrated quality checks before PR creation.
118 |
119 | **Workflow**: `.github/workflows/claude-branch-automation.yml`
120 |
121 | **Flow:**
122 | ```
123 | User: "@claude fix issue #254"
124 | ↓
125 | Claude: Fixes code + Auto-invokes github-release-manager
126 | ↓
127 | Agent: Creates claude/issue-254-xxx branch with version bump
128 | ↓
129 | GitHub Actions: Runs uv lock → Quality checks
130 | ↓
131 | ✅ PASS → Creates PR with quality report
132 | ❌ FAIL → Comments on issue, blocks PR
133 | ```
134 |
135 | **Quality Checks:**
136 | 1. Code complexity analysis (via Groq/Gemini LLM)
137 | 2. Security vulnerability scan
138 | 3. Blocks PR if complexity >8 OR security issues found
139 |
140 | **Benefits:**
141 | - ✅ Zero bad code in PRs
142 | - ✅ Automated enforcement
143 | - ✅ Fast feedback (<2 minutes)
144 | - ✅ GitHub-native annotations
145 |
146 | See workflow: `.github/workflows/claude-branch-automation.yml:95-133`
147 |
148 | ## Groq Bridge 🔥
149 |
150 | **Recommended**: Ultra-fast inference for code-quality-guard agent (~10x faster than Gemini, 200-300ms vs 2-3s).
151 |
152 | **Features:**
153 | - Supports multiple models including Kimi K2 (256K context)
154 | - Pre-commit hooks use Groq as primary LLM
155 | - Avoids OAuth browser authentication interruptions
156 |
157 | See [`docs/integrations/groq-bridge.md`](../../docs/integrations/groq-bridge.md) for setup.
158 |
```
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | We as members, contributors, and leaders pledge to make participation in our
6 | community a harassment-free experience for everyone, regardless of age, body
7 | size, visible or invisible disability, ethnicity, sex characteristics, gender
8 | identity and expression, level of experience, education, socio-economic status,
9 | nationality, personal appearance, race, caste, color, religion, or sexual
10 | identity and orientation.
11 |
12 | We pledge to act and interact in ways that contribute to an open, welcoming,
13 | diverse, inclusive, and healthy community.
14 |
15 | ## Our Standards
16 |
17 | Examples of behavior that contributes to a positive environment for our
18 | community include:
19 |
20 | * Demonstrating empathy and kindness toward other people
21 | * Being respectful of differing opinions, viewpoints, and experiences
22 | * Giving and gracefully accepting constructive feedback
23 | * Accepting responsibility and apologizing to those affected by our mistakes,
24 | and learning from the experience
25 | * Focusing on what is best not just for us as individuals, but for the overall
26 | community
27 |
28 | Examples of unacceptable behavior include:
29 |
30 | * The use of sexualized language or imagery, and sexual attention or advances of
31 | any kind
32 | * Trolling, insulting or derogatory comments, and personal or political attacks
33 | * Public or private harassment
34 | * Publishing others' private information, such as a physical or email address,
35 | without their explicit permission
36 | * Other conduct which could reasonably be considered inappropriate in a
37 | professional setting
38 |
39 | ## Enforcement Responsibilities
40 |
41 | Community leaders are responsible for clarifying and enforcing our standards of
42 | acceptable behavior and will take appropriate and fair corrective action in
43 | response to any behavior that they deem inappropriate, threatening, offensive,
44 | or harmful.
45 |
46 | Community leaders have the right and responsibility to remove, edit, or reject
47 | comments, commits, code, wiki edits, issues, and other contributions that are
48 | not aligned to this Code of Conduct, and will communicate reasons for moderation
49 | decisions when appropriate.
50 |
51 | ## Scope
52 |
53 | This Code of Conduct applies within all community spaces, and also applies when
54 | an individual is officially representing the community in public spaces.
55 | Examples of representing our community include using an official e-mail address,
56 | posting via an official social media account, or acting as an appointed
57 | representative at an online or offline event.
58 |
59 | ## Enforcement
60 |
61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
62 | reported to the community leaders responsible for enforcement via:
63 |
64 | * **GitHub Issues**: For public concerns that warrant community discussion
65 | * **GitHub Discussions**: For questions about community standards
66 | * **Direct Contact**: For sensitive matters, contact the project maintainers directly
67 |
68 | All complaints will be reviewed and investigated promptly and fairly.
69 |
70 | All community leaders are obligated to respect the privacy and security of the
71 | reporter of any incident.
72 |
73 | ## Enforcement Guidelines
74 |
75 | Community leaders will follow these Community Impact Guidelines in determining
76 | the consequences for any action they deem in violation of this Code of Conduct:
77 |
78 | ### 1. Correction
79 |
80 | **Community Impact**: Use of inappropriate language or other behavior deemed
81 | unprofessional or unwelcome in the community.
82 |
83 | **Consequence**: A private, written warning from community leaders, providing
84 | clarity around the nature of the violation and an explanation of why the
85 | behavior was inappropriate. A public apology may be requested.
86 |
87 | ### 2. Warning
88 |
89 | **Community Impact**: A violation through a single incident or series of
90 | actions.
91 |
92 | **Consequence**: A warning with consequences for continued behavior. No
93 | interaction with the people involved, including unsolicited interaction with
94 | those enforcing the Code of Conduct, for a specified period of time. This
95 | includes avoiding interactions in community spaces as well as external channels
96 | like social media. Violating these terms may lead to a temporary or permanent
97 | ban.
98 |
99 | ### 3. Temporary Ban
100 |
101 | **Community Impact**: A serious violation of community standards, including
102 | sustained inappropriate behavior.
103 |
104 | **Consequence**: A temporary ban from any sort of interaction or public
105 | communication with the community for a specified period of time. No public or
106 | private interaction with the people involved, including unsolicited interaction
107 | with those enforcing the Code of Conduct, is allowed during this period.
108 | Violating these terms may lead to a permanent ban.
109 |
110 | ### 4. Permanent Ban
111 |
112 | **Community Impact**: Demonstrating a pattern of violation of community
113 | standards, including sustained inappropriate behavior, harassment of an
114 | individual, or aggression toward or disparagement of classes of individuals.
115 |
116 | **Consequence**: A permanent ban from any sort of public interaction within the
117 | community.
118 |
119 | ## Attribution
120 |
121 | This Code of Conduct is adapted from the [Contributor Covenant][homepage],
122 | version 2.1, available at
123 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
124 |
125 | Community Impact Guidelines were inspired by
126 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
127 |
128 | For answers to common questions about this code of conduct, see the FAQ at
129 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
130 | [https://www.contributor-covenant.org/translations][translations].
131 |
132 | [homepage]: https://www.contributor-covenant.org
133 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
134 | [Mozilla CoC]: https://github.com/mozilla/diversity
135 | [FAQ]: https://www.contributor-covenant.org/faq
136 | [translations]: https://www.contributor-covenant.org/translations
137 |
```
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
```markdown
1 | # Security Policy
2 |
3 | ## Supported Versions
4 |
5 | We actively maintain and provide security updates for the following versions of MCP Memory Service:
6 |
7 | | Version | Supported | Notes |
8 | | ------- | ------------------ | ----- |
9 | | 8.x.x | :white_check_mark: | Current stable release - full support |
10 | | 7.x.x | :white_check_mark: | Previous stable - security fixes only |
11 | | < 7.0 | :x: | No longer supported |
12 |
13 | ## Reporting a Vulnerability
14 |
15 | We take the security of MCP Memory Service seriously. If you discover a security vulnerability, please report it responsibly.
16 |
17 | ### How to Report
18 |
19 | **For sensitive security issues**, please use one of these private reporting methods:
20 |
21 | 1. **GitHub Security Advisory** (Preferred):
22 | - Navigate to the [Security Advisories](https://github.com/doobidoo/mcp-memory-service/security/advisories) page
23 | - Click "Report a vulnerability"
24 | - Provide detailed information about the vulnerability
25 |
26 | 2. **Direct Contact**:
27 | - Open a GitHub Discussion with `[SECURITY]` prefix for initial contact
28 | - We'll provide a secure communication channel for details
29 |
30 | **For non-sensitive security concerns**, you may open a regular GitHub issue.
31 |
32 | ### What to Include
33 |
34 | When reporting a vulnerability, please include:
35 |
36 | 1. **Description**: Clear description of the vulnerability
37 | 2. **Impact**: Potential security impact and affected versions
38 | 3. **Reproduction**: Step-by-step instructions to reproduce the issue
39 | 4. **Environment**:
40 | - Python version
41 | - Operating system
42 | - Storage backend (SQLite-vec, Cloudflare, Hybrid)
43 | - Installation method (pip, Docker, source)
44 | 5. **Proof of Concept**: Code or commands demonstrating the vulnerability (if applicable)
45 | 6. **Suggested Fix**: Any ideas for fixing the issue (optional)
46 |
47 | ### Response Timeline
48 |
49 | We aim to respond to security reports according to the following timeline:
50 |
51 | - **Acknowledgment**: Within 48 hours of report
52 | - **Initial Assessment**: Within 5 business days
53 | - **Status Updates**: Weekly until resolved
54 | - **Fix Development**: 7-14 days for high-severity issues
55 | - **Patch Release**: As soon as fix is validated and tested
56 | - **Public Disclosure**: After patch is released (coordinated with reporter)
57 |
58 | ### Severity Classification
59 |
60 | We use the following severity levels to prioritize security issues:
61 |
62 | **Critical** 🔴
63 | - Remote code execution
64 | - Authentication bypass
65 | - Data exfiltration from other users' memories
66 | - Complete system compromise
67 |
68 | **High** 🟠
69 | - Privilege escalation
70 | - SQL injection
71 | - Cross-site scripting (XSS) in dashboard
72 | - Denial of service affecting all users
73 |
74 | **Medium** 🟡
75 | - Information disclosure (limited scope)
76 | - Cross-site request forgery (CSRF)
77 | - Local file access vulnerabilities
78 | - Resource exhaustion (single user)
79 |
80 | **Low** 🟢
81 | - Timing attacks
82 | - Security configuration issues
83 | - Low-impact information leaks
84 |
85 | ## Security Best Practices
86 |
87 | ### For Users
88 |
89 | 1. **Keep Updated**: Always use the latest stable version
90 | 2. **Secure Configuration**:
91 | - Use strong API keys (`openssl rand -base64 32`)
92 | - Enable HTTPS for HTTP server mode
93 | - Restrict network access to localhost unless needed
94 | 3. **Credential Management**:
95 | - Never commit `.env` files with credentials
96 | - Use environment variables for sensitive data
97 | - Rotate Cloudflare API tokens regularly
98 | 4. **Authentication**: Enable OAuth 2.1 for multi-user deployments
99 | 5. **Monitoring**: Review logs for suspicious activity
100 | 6. **Backups**: Regularly backup your memory database
101 |
102 | ### For Contributors
103 |
104 | 1. **Dependency Security**:
105 | - Review dependency updates for known vulnerabilities
106 | - Use `pip-audit` to scan for security issues
107 | - Keep dependencies up to date
108 | 2. **Input Validation**:
109 | - Sanitize all user input
110 | - Use parameterized queries (no string concatenation)
111 | - Validate file uploads and document ingestion
112 | 3. **Authentication & Authorization**:
113 | - Use secure session management
114 | - Implement proper access controls
115 | - Follow OAuth 2.1 security best practices
116 | 4. **Sensitive Data**:
117 | - Never log API keys, tokens, or passwords
118 | - Encrypt sensitive data at rest (user responsibility)
119 | - Use secure random number generation
120 | 5. **Code Review**: All PRs must pass security review before merge
121 |
122 | ## Known Security Considerations
123 |
124 | ### SQLite-vec Backend
125 | - **Local File Access**: Database file should have appropriate permissions (600)
126 | - **Concurrent Access**: Use proper locking to prevent corruption
127 | - **Backup Encryption**: User responsibility to encrypt backups
128 |
129 | ### Cloudflare Backend
130 | - **API Token Security**: Tokens have full account access - guard carefully
131 | - **Rate Limiting**: Cloudflare enforces rate limits (10k requests/min)
132 | - **Data Residency**: Data stored in Cloudflare's network per your account settings
133 |
134 | ### Hybrid Backend
135 | - **Synchronization**: Ensure secure sync between local and cloud storage
136 | - **Credential Exposure**: Both SQLite and Cloudflare credentials needed
137 |
138 | ### Web Dashboard
139 | - **HTTPS Recommended**: Use HTTPS in production environments
140 | - **XSS Protection**: All user input is escaped before rendering
141 | - **CSRF Protection**: Implement for state-changing operations
142 | - **Session Security**: Enable secure cookies in production
143 |
144 | ### MCP Protocol
145 | - **Local Access Only**: MCP server typically runs locally via stdin/stdout
146 | - **Process Isolation**: Each client gets isolated server process
147 | - **No Network Exposure**: By default, MCP mode has no network attack surface
148 |
149 | ## Security Updates
150 |
151 | Security patches are released as:
152 | - **Patch versions** (8.x.Y) for low/medium severity
153 | - **Minor versions** (8.X.0) for high severity requiring API changes
154 | - **Out-of-band releases** for critical vulnerabilities
155 |
156 | Security advisories are published at:
157 | - [GitHub Security Advisories](https://github.com/doobidoo/mcp-memory-service/security/advisories)
158 | - [CHANGELOG.md](CHANGELOG.md) with `[SECURITY]` tag
159 | - Release notes for affected versions
160 |
161 | ## Disclosure Policy
162 |
163 | We follow **coordinated disclosure**:
164 |
165 | 1. Vulnerability reported privately
166 | 2. We confirm and develop a fix
167 | 3. Security advisory drafted (private)
168 | 4. Patch released with security note
169 | 5. Public disclosure 7 days after patch release
170 | 6. Reporter credited (if desired)
171 |
172 | We appreciate security researchers following responsible disclosure practices and will acknowledge contributors in our security advisories.
173 |
174 | ## Security Hall of Fame
175 |
176 | We recognize security researchers who help make MCP Memory Service more secure:
177 |
178 | <!-- Security contributors will be listed here -->
179 | *No security vulnerabilities have been publicly disclosed to date.*
180 |
181 | ## Contact
182 |
183 | For security concerns that don't fit the above categories:
184 | - **General Security Questions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)
185 | - **Project Security**: See reporting instructions above
186 |
187 | ---
188 |
189 | **Last Updated**: November 2025
190 | **Policy Version**: 1.0
191 |
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to MCP Memory Service
2 |
3 | Thank you for your interest in contributing to MCP Memory Service! 🎉
4 |
5 | This project provides semantic memory and persistent storage for AI assistants through the Model Context Protocol. We welcome contributions of all kinds - from bug fixes and features to documentation and testing.
6 |
7 | ## Table of Contents
8 |
9 | - [Code of Conduct](#code-of-conduct)
10 | - [Ways to Contribute](#ways-to-contribute)
11 | - [Getting Started](#getting-started)
12 | - [Development Process](#development-process)
13 | - [Coding Standards](#coding-standards)
14 | - [Testing Requirements](#testing-requirements)
15 | - [Documentation](#documentation)
16 | - [Submitting Changes](#submitting-changes)
17 | - [Reporting Issues](#reporting-issues)
18 | - [Community & Support](#community--support)
19 | - [Recognition](#recognition)
20 |
21 | ## Code of Conduct
22 |
23 | We are committed to providing a welcoming and inclusive environment for all contributors. Please:
24 |
25 | - Be respectful and considerate in all interactions
26 | - Welcome newcomers and help them get started
27 | - Focus on constructive criticism and collaborative problem-solving
28 | - Respect differing viewpoints and experiences
29 | - Avoid harassment, discrimination, or inappropriate behavior
30 |
31 | ## Ways to Contribute
32 |
33 | ### 🐛 Bug Reports
34 | Help us identify and fix issues by reporting bugs with detailed information.
35 |
36 | ### ✨ Feature Requests
37 | Suggest new features or improvements to existing functionality.
38 |
39 | ### 📝 Documentation
40 | Improve README, Wiki pages, code comments, or API documentation.
41 |
42 | ### 🧪 Testing
43 | Write tests, improve test coverage, or help with manual testing.
44 |
45 | ### 💻 Code Contributions
46 | Fix bugs, implement features, or improve performance.
47 |
48 | ### 🌍 Translations
49 | Help make the project accessible to more users (future goal).
50 |
51 | ### 💬 Community Support
52 | Answer questions in Issues, Discussions, or help other users.
53 |
54 | ## Getting Started
55 |
56 | ### Prerequisites
57 |
58 | - Python 3.10 or higher
59 | - Git
60 | - Platform-specific requirements:
61 | - **macOS**: Homebrew Python recommended for SQLite extension support
62 | - **Windows**: Visual Studio Build Tools for some dependencies
63 | - **Linux**: Build essentials package
64 |
65 | ### Setting Up Your Development Environment
66 |
67 | 1. **Fork the repository** on GitHub
68 |
69 | 2. **Clone your fork**:
70 | ```bash
71 | git clone https://github.com/YOUR_USERNAME/mcp-memory-service.git
72 | cd mcp-memory-service
73 | ```
74 |
75 | 3. **Install dependencies**:
76 | ```bash
77 | python install.py
78 | ```
79 | This will automatically detect your platform and install appropriate dependencies.
80 |
81 | 4. **Verify installation**:
82 | ```bash
83 | python scripts/verify_environment.py
84 | ```
85 |
86 | 5. **Run the service**:
87 | ```bash
88 | uv run memory server
89 | ```
90 |
91 | 6. **Test with MCP Inspector** (optional):
92 | ```bash
93 | npx @modelcontextprotocol/inspector uv run memory server
94 | ```
95 |
96 | ### Alternative: Docker Setup
97 |
98 | For a containerized environment:
99 | ```bash
100 | docker-compose up -d # For MCP mode
101 | docker-compose -f docker-compose.http.yml up -d # For HTTP API mode
102 | ```
103 |
104 | ## Development Process
105 |
106 | ### 1. Create a Feature Branch
107 |
108 | ```bash
109 | git checkout -b feature/your-feature-name
110 | # or
111 | git checkout -b fix/issue-description
112 | ```
113 |
114 | Use descriptive branch names:
115 | - `feature/` for new features
116 | - `fix/` for bug fixes
117 | - `docs/` for documentation
118 | - `test/` for test improvements
119 | - `refactor/` for code refactoring
120 |
121 | ### 2. Make Your Changes
122 |
123 | - Write clean, readable code
124 | - Follow the coding standards (see below)
125 | - Add/update tests as needed
126 | - Update documentation if applicable
127 | - Keep commits focused and atomic
128 |
129 | ### 3. Test Your Changes
130 |
131 | ```bash
132 | # Run all tests
133 | pytest tests/
134 |
135 | # Run specific test file
136 | pytest tests/test_server.py
137 |
138 | # Run with coverage
139 | pytest --cov=mcp_memory_service tests/
140 | ```
141 |
142 | ### 4. Commit Your Changes
143 |
144 | Use semantic commit messages:
145 | ```bash
146 | git commit -m "feat: add memory export functionality"
147 | git commit -m "fix: resolve timezone handling in memory search"
148 | git commit -m "docs: update installation guide for Windows"
149 | git commit -m "test: add coverage for storage backends"
150 | ```
151 |
152 | Format: `<type>: <description>`
153 |
154 | Types:
155 | - `feat`: New feature
156 | - `fix`: Bug fix
157 | - `docs`: Documentation changes
158 | - `test`: Test additions or changes
159 | - `refactor`: Code refactoring
160 | - `perf`: Performance improvements
161 | - `chore`: Maintenance tasks
162 |
163 | ### 5. Push to Your Fork
164 |
165 | ```bash
166 | git push origin your-branch-name
167 | ```
168 |
169 | ### 6. Create a Pull Request
170 |
171 | Open a PR from your fork to the main repository with:
172 | - Clear title describing the change
173 | - Description of what and why
174 | - Reference to any related issues
175 | - Screenshots/examples if applicable
176 |
177 | ## Coding Standards
178 |
179 | ### Python Style Guide
180 |
181 | - Follow PEP 8 with these modifications:
182 | - Line length: 88 characters (Black formatter default)
183 | - Use double quotes for strings
184 | - Use type hints for all function signatures
185 | - Write descriptive variable and function names
186 | - Add docstrings to all public functions/classes (Google style)
187 |
188 | ### Code Organization
189 |
190 | ```python
191 | # Import order
192 | import standard_library
193 | import third_party_libraries
194 | from mcp_memory_service import local_modules
195 |
196 | # Type hints
197 | from typing import Optional, List, Dict, Any
198 |
199 | # Async functions
200 | async def process_memory(content: str) -> Dict[str, Any]:
201 | """Process and store memory content.
202 |
203 | Args:
204 | content: The memory content to process
205 |
206 | Returns:
207 | Dictionary containing memory metadata
208 | """
209 | # Implementation
210 | ```
211 |
212 | ### Error Handling
213 |
214 | - Use specific exception types
215 | - Provide helpful error messages
216 | - Log errors appropriately
217 | - Never silently fail
218 |
219 | ```python
220 | try:
221 | result = await storage.store(memory)
222 | except StorageError as e:
223 | logger.error(f"Failed to store memory: {e}")
224 | raise MemoryServiceError(f"Storage operation failed: {e}") from e
225 | ```
226 |
227 | ## Testing Requirements
228 |
229 | ### Writing Tests
230 |
231 | - Place tests in `tests/` directory
232 | - Name test files with `test_` prefix
233 | - Use descriptive test names
234 | - Include both positive and negative test cases
235 | - Mock external dependencies
236 |
237 | Example test:
238 | ```python
239 | import pytest
240 | from mcp_memory_service.storage import SqliteVecStorage
241 |
242 | @pytest.mark.asyncio
243 | async def test_store_memory_success():
244 | """Test successful memory storage."""
245 | storage = SqliteVecStorage(":memory:")
246 | result = await storage.store("test content", tags=["test"])
247 | assert result is not None
248 | assert "hash" in result
249 | ```
250 |
251 | ### Test Coverage
252 |
253 | - Aim for >80% code coverage
254 | - Focus on critical paths and edge cases
255 | - Test error handling scenarios
256 | - Include integration tests where appropriate
257 |
258 | ## Documentation
259 |
260 | ### Code Documentation
261 |
262 | - Add docstrings to all public APIs
263 | - Include type hints
264 | - Provide usage examples in docstrings
265 | - Keep comments concise and relevant
266 |
267 | ### Project Documentation
268 |
269 | When adding features or making significant changes:
270 |
271 | 1. Update README.md if needed
272 | 2. Add/update Wiki pages for detailed guides
273 | 3. Update CHANGELOG.md following Keep a Changelog format
274 | 4. Update AGENTS.md or CLAUDE.md if development workflow changes
275 |
276 | **Advanced Workflow Automation**:
277 | - See [Context Provider Workflow Automation](https://github.com/doobidoo/mcp-memory-service/wiki/Context-Provider-Workflow-Automation) for automating development workflows with intelligent patterns
278 |
279 | ### API Documentation
280 |
281 | - Document new MCP tools in `docs/api/tools.md`
282 | - Include parameter descriptions and examples
283 | - Note any breaking changes
284 |
285 | ## Submitting Changes
286 |
287 | ### Pull Request Guidelines
288 |
289 | 1. **PR Title**: Use semantic format (e.g., "feat: add batch memory operations")
290 |
291 | 2. **PR Description Template**:
292 | ```markdown
293 | ## Description
294 | Brief description of changes
295 |
296 | ## Motivation
297 | Why these changes are needed
298 |
299 | ## Changes
300 | - List of specific changes
301 | - Breaking changes (if any)
302 |
303 | ## Testing
304 | - How you tested the changes
305 | - Test coverage added
306 |
307 | ## Screenshots
308 | (if applicable)
309 |
310 | ## Related Issues
311 | Fixes #123
312 | ```
313 |
314 | 3. **PR Checklist**:
315 | - [ ] Tests pass locally
316 | - [ ] Code follows style guidelines
317 | - [ ] Documentation updated
318 | - [ ] CHANGELOG.md updated
319 | - [ ] No sensitive data exposed
320 |
321 | ### Review Process
322 |
323 | - PRs require at least one review
324 | - Address review feedback promptly
325 | - Keep discussions focused and constructive
326 | - Be patient - reviews may take a few days
327 |
328 | ## Reporting Issues
329 |
330 | ### Bug Reports
331 |
332 | When reporting bugs, include:
333 |
334 | 1. **Environment**:
335 | - OS and version
336 | - Python version
337 | - MCP Memory Service version
338 | - Installation method (pip, Docker, source)
339 |
340 | 2. **Steps to Reproduce**:
341 | - Minimal code example
342 | - Exact commands run
343 | - Configuration used
344 |
345 | 3. **Expected vs Actual Behavior**:
346 | - What you expected to happen
347 | - What actually happened
348 | - Error messages/stack traces
349 |
350 | 4. **Additional Context**:
351 | - Screenshots if applicable
352 | - Relevant log output
353 | - Related issues
354 |
355 | ### Feature Requests
356 |
357 | For feature requests, describe:
358 |
359 | - The problem you're trying to solve
360 | - Your proposed solution
361 | - Alternative approaches considered
362 | - Potential impact on existing functionality
363 |
364 | ## Community & Support
365 |
366 | ### Getting Help
367 |
368 | - **Documentation**: Check the [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) first
369 | - **Issues**: Search existing [issues](https://github.com/doobidoo/mcp-memory-service/issues) before creating new ones
370 | - **Discussions**: Use [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions) for questions
371 | - **Response Time**: Maintainers typically respond within 2-3 days
372 |
373 | ### Communication Channels
374 |
375 | - **GitHub Issues**: Bug reports and feature requests
376 | - **GitHub Discussions**: General questions and community discussion
377 | - **Pull Requests**: Code contributions and reviews
378 |
379 | ### For AI Agents
380 |
381 | If you're an AI coding assistant, also check:
382 | - [AGENTS.md](AGENTS.md) - Generic AI agent instructions
383 | - [CLAUDE.md](CLAUDE.md) - Claude-specific guidelines
384 | - [Context Provider Workflow Automation](https://github.com/doobidoo/mcp-memory-service/wiki/Context-Provider-Workflow-Automation) - Automate development workflows with intelligent patterns
385 |
386 | ## Recognition
387 |
388 | We value all contributions! Contributors are:
389 |
390 | - Listed in release notes for their contributions
391 | - Mentioned in CHANGELOG.md entries
392 | - Credited in commit messages when providing fixes/solutions
393 | - Welcome to add themselves to a CONTRIBUTORS file (future)
394 |
395 | ### Types of Recognition
396 |
397 | - 🐛 Bug reporters who provide detailed, reproducible issues
398 | - 💻 Code contributors who submit PRs
399 | - 📝 Documentation improvers
400 | - 🧪 Test writers and reviewers
401 | - 💬 Community helpers who support other users
402 | - 🎨 UI/UX improvers (for dashboard contributions)
403 |
404 | ---
405 |
406 | Thank you for contributing to MCP Memory Service! Your efforts help make AI assistants more capable and useful for everyone. 🚀
407 |
408 | If you have questions not covered here, please open a [Discussion](https://github.com/doobidoo/mcp-memory-service/discussions) or check our [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki).
```
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
```markdown
1 | # CLAUDE.md
2 |
3 | This file provides guidance to Claude Code (claude.ai/code) when working with this MCP Memory Service repository.
4 |
5 | > **📝 Personal Customizations**: You can create `CLAUDE.local.md` (gitignored) for personal notes, custom workflows, or environment-specific instructions. This file contains shared project conventions.
6 |
7 | > **Information Lookup**: Files first, memory second, user last. See [`.claude/directives/memory-first.md`](.claude/directives/memory-first.md) for strategy. Comprehensive project context stored in memory with tags `claude-code-reference`.
8 |
9 | ## 🔴 Critical Directives
10 |
11 | **IMPORTANT**: Before working with this project, read:
12 | - **`.claude/directives/memory-tagging.md`** - MANDATORY: Always tag memories with `mcp-memory-service` as first tag
13 | - **`.claude/directives/README.md`** - Additional topic-specific directives
14 |
15 | ## ⚡ Quick Update & Restart (RECOMMENDED)
16 |
17 | **ALWAYS use these scripts after git pull to update dependencies and restart server:**
18 |
19 | ```bash
20 | # macOS/Linux - One command, <2 minutes
21 | ./scripts/update_and_restart.sh
22 |
23 | # Windows PowerShell
24 | .\scripts\service\windows\update_and_restart.ps1
25 | ```
26 |
27 | **Why?** These scripts automate the complete update workflow:
28 | - ✅ Git pull + auto-stash uncommitted changes
29 | - ✅ Install dependencies (editable mode: `pip install -e .`)
30 | - ✅ Restart HTTP server with version verification
31 | - ✅ Health check (ensures new version is running)
32 |
33 | **Without these scripts**, you risk running old code (common mistake: forget `pip install -e .` after pull).
34 |
35 | See [Essential Commands](#essential-commands) for options (--no-restart, --force).
36 |
37 | ## Overview
38 |
39 | MCP Memory Service is a Model Context Protocol server providing semantic memory and persistent storage for Claude Desktop with SQLite-vec, Cloudflare, and Hybrid storage backends.
40 |
41 | > **🆕 v8.76.0**: **Official Lite Distribution Support** - New `mcp-memory-service-lite` package with 90% size reduction (7.7GB → 805MB), automated dual publishing workflow, conditional transformers loading, and multi-protocol port detection fixes (HTTP/HTTPS health checks, cross-platform fallback chain: lsof → ss → netstat → ps). See [CHANGELOG.md](CHANGELOG.md) for full version history.
42 | >
43 | > **Note**: When releasing new versions, update this line with current version + brief description. Use `.claude/agents/github-release-manager.md` agent for complete release workflow.
44 |
45 | ## Essential Commands
46 |
47 | **Most Used:**
48 | - `./scripts/update_and_restart.sh` - Update & restart (ALWAYS after git pull)
49 | - `curl http://127.0.0.1:8000/api/health` - Health check
50 | - `bash scripts/pr/pre_pr_check.sh` - Pre-PR validation (MANDATORY)
51 | - `curl -X POST http://127.0.0.1:8000/api/consolidation/trigger -H "Content-Type: application/json" -d '{"time_horizon":"weekly"}'` - Trigger consolidation
52 |
53 | **Full command reference:** [scripts/README.md](scripts/README.md)
54 |
55 | ## Architecture
56 |
57 | **Core Components:**
58 | - **Server Layer**: MCP protocol with async handlers, global caches (`src/mcp_memory_service/server.py:1`)
59 | - **Storage Backends**: SQLite-Vec (5ms reads), Cloudflare (edge), Hybrid (local + cloud sync)
60 | - **Web Interface**: FastAPI dashboard at `http://127.0.0.1:8000/` with REST API
61 | - **Document Ingestion**: PDF, DOCX, PPTX loaders (see [docs/document-ingestion.md](docs/document-ingestion.md))
62 | - **Memory Hooks**: Natural Memory Triggers v7.1.3+ with 85%+ accuracy (see below)
63 |
64 | **Utility Modules** (v8.61.0 - Phase 3 Refactoring):
65 | - `utils/health_check.py` - Strategy Pattern for backend health checks (5 strategies)
66 | - `utils/startup_orchestrator.py` - Orchestrator Pattern for server startup (3 orchestrators)
67 | - `utils/directory_ingestion.py` - Processor Pattern for file ingestion (3 processors)
68 | - `utils/quality_analytics.py` - Analyzer Pattern for quality distribution (3 analyzers)
69 |
70 | **Key Patterns:**
71 | - Async/await for I/O, type safety (Python 3.10+), platform hardware optimization (CUDA/MPS/DirectML/ROCm)
72 | - Design Patterns: Strategy, Orchestrator, Processor, Analyzer (all complexity A-B grade)
73 |
74 | ## Document Ingestion
75 |
76 | Supports PDF, DOCX, PPTX, TXT/MD with optional [semtools](https://github.com/run-llama/semtools) for enhanced quality.
77 |
78 | ```bash
79 | claude /memory-ingest document.pdf --tags documentation
80 | claude /memory-ingest-dir ./docs --tags knowledge-base
81 | ```
82 |
83 | See [docs/document-ingestion.md](docs/document-ingestion.md) for full configuration and usage.
84 |
85 | ## Interactive Dashboard
86 |
87 | Web interface at `http://127.0.0.1:8000/` with CRUD operations, semantic/tag/time search, real-time updates (SSE), mobile responsive. Performance: 25ms page load, <100ms search.
88 |
89 | **API Endpoints:** `/api/search`, `/api/search/by-tag`, `/api/search/by-time`, `/api/events`, `/api/quality/*` (v8.45.0+)
90 |
91 | ## Memory Quality System (v8.45.0+)
92 |
93 | Local-first AI quality scoring (ONNX), zero-cost, privacy-preserving.
94 |
95 | **Features:**
96 | - Tier 1: Local ONNX (80-150ms CPU, $0 cost)
97 | - Quality-boosted search: `0.7×semantic + 0.3×quality`
98 | - Quality-based forgetting: High (365d), Medium (180d), Low (30-90d)
99 |
100 | **Config:** `export MCP_QUALITY_SYSTEM_ENABLED=true`
101 |
102 | → Details: [`.claude/directives/quality-system-details.md`](.claude/directives/quality-system-details.md)
103 | → Guide: [docs/guides/memory-quality-guide.md](docs/guides/memory-quality-guide.md)
104 |
105 | ## Memory Consolidation System
106 |
107 | Dream-inspired consolidation with automatic scheduling (v8.23.0+).
108 |
109 | **Quick Start:**
110 | ```bash
111 | curl -X POST http://127.0.0.1:8000/api/consolidation/trigger \
112 | -H "Content-Type: application/json" -d '{"time_horizon":"weekly"}'
113 | ```
114 |
115 | **Config:** `export MCP_CONSOLIDATION_ENABLED=true`
116 |
117 | → Details: [`.claude/directives/consolidation-details.md`](.claude/directives/consolidation-details.md)
118 | → Guide: [docs/guides/memory-consolidation-guide.md](docs/guides/memory-consolidation-guide.md)
119 |
120 | ## Environment Variables
121 |
122 | **Essential Configuration:**
123 | ```bash
124 | # Storage Backend (Hybrid is RECOMMENDED for production)
125 | export MCP_MEMORY_STORAGE_BACKEND=hybrid # hybrid|cloudflare|sqlite_vec
126 |
127 | # Cloudflare Configuration (REQUIRED for hybrid/cloudflare backends)
128 | export CLOUDFLARE_API_TOKEN="your-token" # Required for Cloudflare backend
129 | export CLOUDFLARE_ACCOUNT_ID="your-account" # Required for Cloudflare backend
130 | export CLOUDFLARE_D1_DATABASE_ID="your-d1-id" # Required for Cloudflare backend
131 | export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index" # Required for Cloudflare backend
132 |
133 | # Web Interface (Optional)
134 | export MCP_HTTP_ENABLED=true # Enable HTTP server
135 | export MCP_HTTPS_ENABLED=true # Enable HTTPS (production)
136 | export MCP_API_KEY="$(openssl rand -base64 32)" # Generate secure API key
137 | ```
138 |
139 | **Configuration Precedence:** Environment variables > .env file > Global Claude Config > defaults
140 |
141 | **✅ Automatic Configuration Loading (v6.16.0+):** The service now automatically loads `.env` files and respects environment variable precedence. CLI defaults no longer override environment configuration.
142 |
143 | **⚠️ Important:** When using hybrid or cloudflare backends, ensure Cloudflare credentials are properly configured. If health checks show "sqlite-vec" when you expect "cloudflare" or "hybrid", this indicates a configuration issue that needs to be resolved.
144 |
145 | **Platform Support:** macOS (MPS/CPU), Windows (CUDA/DirectML/CPU), Linux (CUDA/ROCm/CPU)
146 |
147 | ## Claude Code Hooks Configuration 🆕
148 |
149 | > **✅ Windows SessionStart Fixed** (Claude Code 2.0.76+): SessionStart hooks now work correctly on Windows. The subprocess lifecycle bug (#160) was fixed in Claude Code core. No workaround needed.
150 |
151 | **Natural Memory Triggers v7.1.3** - 85%+ trigger accuracy, multi-tier processing (50ms → 150ms → 500ms)
152 |
153 | **Installation:**
154 | ```bash
155 | cd claude-hooks && python install_hooks.py --natural-triggers
156 |
157 | # CLI Management
158 | node ~/.claude/hooks/memory-mode-controller.js status
159 | node ~/.claude/hooks/memory-mode-controller.js profile balanced
160 | ```
161 |
162 | **Performance Profiles:**
163 | - `speed_focused`: <100ms, minimal memory awareness
164 | - `balanced`: <200ms, optimal for general development (recommended)
165 | - `memory_aware`: <500ms, maximum context awareness
166 |
167 | → Complete configuration: [`.claude/directives/hooks-configuration.md`](.claude/directives/hooks-configuration.md)
168 |
169 | ## Storage Backends
170 |
171 | | Backend | Performance | Use Case | Installation |
172 | |---------|-------------|----------|--------------|
173 | | **Hybrid** ⚡ | Fast (5ms read) | **🌟 Production (Recommended)** | `--storage-backend hybrid` |
174 | | **Cloudflare** ☁️ | Network dependent | Cloud-only deployment | `--storage-backend cloudflare` |
175 | | **SQLite-Vec** 🪶 | Fast (5ms read) | Development, single-user | `--storage-backend sqlite_vec` |
176 |
177 | **Hybrid Backend Benefits:**
178 | - 5ms read/write + multi-device sync + graceful offline operation
179 |
180 | **Database Lock Prevention (v8.9.0+):**
181 | - After adding `MCP_MEMORY_SQLITE_PRAGMAS` to `.env`, **restart all servers**
182 | - SQLite pragmas are per-connection, not global
183 |
184 | → Complete details: [`.claude/directives/storage-backends.md`](.claude/directives/storage-backends.md)
185 |
186 | ## Development Guidelines
187 |
188 | **Read first:**
189 | → [`.claude/directives/development-setup.md`](.claude/directives/development-setup.md) - Editable install
190 | → [`.claude/directives/pr-workflow.md`](.claude/directives/pr-workflow.md) - Pre-PR checks
191 | → [`.claude/directives/refactoring-checklist.md`](.claude/directives/refactoring-checklist.md) - Refactoring safety
192 | → [`.claude/directives/version-management.md`](.claude/directives/version-management.md) - Release workflow
193 |
194 | **Quick:**
195 | - `pip install -e .` (dev mode)
196 | - `bash scripts/pr/pre_pr_check.sh` (before PR, MANDATORY)
197 | - Use github-release-manager agent for releases
198 | - Tag memories with `mcp-memory-service` as first tag
199 |
200 | ## Code Quality Monitoring
201 |
202 | **Three-layer strategy:**
203 | 1. **Pre-commit** (<5s) - Groq/Gemini complexity + security (blocks: complexity >8, any security issues)
204 | 2. **PR Quality Gate** (10-60s) - `quality_gate.sh --with-pyscn` (blocks: security, health <50)
205 | 3. **Periodic Review** (weekly) - pyscn analysis + trend tracking
206 |
207 | **Health Score Thresholds:**
208 | - <50: 🔴 Release blocker (cannot merge)
209 | - 50-69: 🟡 Action required (refactor within 2 weeks)
210 | - 70+: ✅ Continue development
211 |
212 | → Complete workflow: [`.claude/directives/code-quality-workflow.md`](.claude/directives/code-quality-workflow.md)
213 |
214 | ## Configuration Management
215 |
216 | **Quick Validation:**
217 | ```bash
218 | python scripts/validation/validate_configuration_complete.py # Comprehensive validation
219 | python scripts/validation/diagnose_backend_config.py # Cloudflare diagnostics
220 | ```
221 |
222 | **Configuration Hierarchy:**
223 | - Global: `~/.claude.json` (authoritative)
224 | - Project: `.env` file (Cloudflare credentials)
225 | - **Avoid**: Local `.mcp.json` overrides
226 |
227 | **Common Issues & Quick Fixes:**
228 |
229 | | Issue | Quick Fix |
230 | |-------|-----------|
231 | | Wrong backend showing | `python scripts/validation/diagnose_backend_config.py` |
232 | | Port mismatch (hooks timeout) | Verify same port in `~/.claude/hooks/config.json` and server (default: 8000) |
233 | | Schema validation errors after PR merge | Run `/mcp` in Claude Code to reconnect with new schema |
234 | | Accidental `data/memory.db` | Delete safely: `rm -rf data/` (gitignored) |
235 |
236 | See [docs/troubleshooting/hooks-quick-reference.md](docs/troubleshooting/hooks-quick-reference.md) for comprehensive troubleshooting.
237 |
238 | ## Hook Troubleshooting
239 |
240 | **SessionEnd Hooks:**
241 | - Trigger on `/exit`, terminal close (NOT Ctrl+C)
242 | - Require 100+ characters, confidence > 0.1
243 | - Memory creation: topics, decisions, insights, code changes
244 |
245 | **Windows SessionStart (Fixed in Claude Code 2.0.76+):**
246 | - ✅ SessionStart hooks now work correctly on Windows
247 | - The subprocess lifecycle bug (#160) was fixed in Claude Code core
248 |
249 | See [docs/troubleshooting/hooks-quick-reference.md](docs/troubleshooting/hooks-quick-reference.md) for full troubleshooting guide.
250 |
251 | ## Agent Integrations
252 |
253 | Workflow automation: `@agent github-release-manager`, `./scripts/utils/groq "task"`, `bash scripts/pr/auto_review.sh <PR>`
254 |
255 | **Agents:** github-release-manager (releases), amp-bridge (refactoring), code-quality-guard (quality), gemini-pr-automator (PRs)
256 |
257 | → Workflows: [`.claude/directives/agents.md`](.claude/directives/agents.md)
258 |
259 | > **For detailed troubleshooting, architecture, and deployment guides:**
260 | > - **Backend Configuration Issues**: See [Wiki Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING#backend-configuration-issues) for comprehensive solutions to missing memories, environment variable issues, Cloudflare auth, hooks timeouts, and more
261 | > - **Historical Context**: Retrieve memories tagged with `claude-code-reference`
262 | > - **Quick Diagnostic**: Run `python scripts/validation/diagnose_backend_config.py`
263 |
```
--------------------------------------------------------------------------------
/claude-hooks/utilities/session-cache.json:
--------------------------------------------------------------------------------
```json
1 |
```
--------------------------------------------------------------------------------
/tests/consolidation/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Consolidation tests module
```
--------------------------------------------------------------------------------
/archive/deployment-configs/empty_config.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Empty Litestream config
2 | dbs: []
```
--------------------------------------------------------------------------------
/.metrics/baseline_mi_install_hooks.txt:
--------------------------------------------------------------------------------
```
1 | claude-hooks/install_hooks.py - C (2.38)
2 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/_version.py:
--------------------------------------------------------------------------------
```python
1 | """Version information for MCP Memory Service."""
2 |
3 | __version__ = "8.76.0"
4 |
```
--------------------------------------------------------------------------------
/scripts/run/run-with-uv.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "Running MCP Memory Service with UV..."
3 | python uv_wrapper.py "$@"
4 |
```
--------------------------------------------------------------------------------
/scripts/linux/service_status.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "MCP Memory Service Status:"
3 | echo "-" | tr '-' '='
4 | systemctl --user status mcp-memory
5 |
```
--------------------------------------------------------------------------------
/scripts/linux/view_logs.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "Viewing MCP Memory Service logs (press Ctrl+C to exit)..."
3 | journalctl -u mcp-memory -f
4 |
```
--------------------------------------------------------------------------------
/docs/statistics/data/activity_by_hour.csv:
--------------------------------------------------------------------------------
```
1 | hour,commits
2 | 00,22
3 | 01,6
4 | 06,19
5 | 07,76
6 | 08,90
7 | 09,73
8 | 10,43
9 | 11,71
10 | 12,73
11 | 13,92
12 | 14,97
13 | 15,41
14 | 16,73
15 | 17,85
16 | 18,65
17 | 19,98
18 | 20,138
19 | 21,160
20 | 22,150
21 | 23,64
22 |
```
--------------------------------------------------------------------------------
/docs/statistics/data/contributors.csv:
--------------------------------------------------------------------------------
```
1 | contributor,commits,percentage
2 | Heinrich Krupp,1418,94.8%
3 | zod,20,1.3%
4 | Salih Ergüt,16,1.1%
5 | 3dyuval,10,0.7%
6 | muxammadreza,8,0.5%
7 | Henry Mao,6,0.4%
8 |
```
--------------------------------------------------------------------------------
/tests/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | Test suite for MCP Memory Service.
3 | This package contains all test modules for verifying the functionality
4 | of the memory service components.
5 | """
```
--------------------------------------------------------------------------------
/docs/statistics/data/activity_by_day.csv:
--------------------------------------------------------------------------------
```
1 | day_of_week,commits,percentage
2 | Sunday,314,20.4%
3 | Saturday,285,18.6%
4 | Monday,271,17.6%
5 | Friday,231,15.0%
6 | Tuesday,177,11.5%
7 | Thursday,131,8.5%
8 | Wednesday,127,8.3%
9 |
```
--------------------------------------------------------------------------------
/docs/statistics/data/monthly_activity.csv:
--------------------------------------------------------------------------------
```
1 | month,commits,releases
2 | 2024-12,55,1
3 | 2025-01,34,0
4 | 2025-02,2,0
5 | 2025-03,66,0
6 | 2025-04,102,0
7 | 2025-05,4,0
8 | 2025-06,36,0
9 | 2025-07,351,9
10 | 2025-08,330,64
11 | 2025-09,246,34
12 | 2025-10,310,65
13 |
```
--------------------------------------------------------------------------------
/scripts/linux/stop_service.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "Stopping MCP Memory Service..."
3 | systemctl --user stop mcp-memory
4 | if [ $? -eq 0 ]; then
5 | echo "✅ Service stopped successfully!"
6 | else
7 | echo "❌ Failed to stop service"
8 | fi
9 |
```
--------------------------------------------------------------------------------
/scripts/linux/start_service.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "Starting MCP Memory Service..."
3 | systemctl --user start mcp-memory
4 | if [ $? -eq 0 ]; then
5 | echo "✅ Service started successfully!"
6 | else
7 | echo "❌ Failed to start service"
8 | fi
9 |
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/requirements-cloudflare.txt:
--------------------------------------------------------------------------------
```
1 | # Additional dependencies for Cloudflare backend support
2 | # These are installed automatically when using the cloudflare backend
3 |
4 | # HTTP client for Cloudflare API calls
5 | httpx>=0.24.0
6 |
7 | # Optional: Cloudflare Python SDK (if available)
8 | # cloudflare>=2.15.0
```
--------------------------------------------------------------------------------
/pytest.ini:
--------------------------------------------------------------------------------
```
1 | [pytest]
2 | asyncio_mode = auto
3 | testpaths = tests
4 | python_files = test_*.py
5 | python_classes = Test*
6 | python_functions = test_*
7 | markers =
8 | unit: unit tests
9 | integration: integration tests
10 | performance: performance tests
11 | asyncio: mark test as async
12 |
```
--------------------------------------------------------------------------------
/test_document.txt:
--------------------------------------------------------------------------------
```
1 | This is a test document for MCP Memory Service document ingestion.
2 |
3 | It contains some sample content to test the chunking and embedding functionality.
4 |
5 | Features:
6 | - Multiple paragraphs
7 | - Some technical content
8 | - Test data for verification
9 |
10 | End of document.
11 |
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/litestream_replica_simple.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Simple Litestream replica configuration
2 | # Note: Litestream replicas typically push TO destinations, not pull FROM them
3 | # For pulling from HTTP, we'll use restore commands instead
4 | dbs:
5 | - path: /Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/services/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | Services package for MCP Memory Service.
3 |
4 | This package contains shared business logic services that provide
5 | consistent behavior across different interfaces (API, MCP tools).
6 | """
7 |
8 | from .memory_service import MemoryService, MemoryResult
9 |
10 | __all__ = ["MemoryService", "MemoryResult"]
11 |
```
--------------------------------------------------------------------------------
/examples/claude-desktop-http-config.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "memory": {
4 | "command": "node",
5 | "args": ["/path/to/mcp-memory-service/examples/http-mcp-bridge.js"],
6 | "env": {
7 | "MCP_MEMORY_HTTP_ENDPOINT": "http://your-server:8000/api",
8 | "MCP_MEMORY_API_KEY": "your-secure-api-key"
9 | }
10 | }
11 | }
12 | }
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/litestream_replica_config.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Litestream Replica Configuration for local macOS machine
2 | # This configuration syncs from the remote master at narrowbox.local
3 | dbs:
4 | - path: /Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db
5 | replicas:
6 | - type: file
7 | url: http://10.0.1.30:8080/mcp-memory
8 | sync-interval: 10s
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/embeddings/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """Embedding generation modules for MCP Memory Service."""
2 |
3 | from .onnx_embeddings import (
4 | ONNXEmbeddingModel,
5 | get_onnx_embedding_model,
6 | ONNX_AVAILABLE,
7 | TOKENIZERS_AVAILABLE
8 | )
9 |
10 | __all__ = [
11 | 'ONNXEmbeddingModel',
12 | 'get_onnx_embedding_model',
13 | 'ONNX_AVAILABLE',
14 | 'TOKENIZERS_AVAILABLE'
15 | ]
```
--------------------------------------------------------------------------------
/examples/config/claude_desktop_config.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "memory": {
4 | "command": "python",
5 | "args": [
6 | "-m",
7 | "mcp_memory_service.server"
8 | ],
9 | "env": {
10 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
11 | "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\heinrich.krupp\\AppData\\Local\\mcp-memory"
12 | }
13 | }
14 | }
15 | }
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/litestream_replica_config_fixed.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Litestream Replica Configuration for local macOS machine (FIXED)
2 | # This configuration syncs from the remote master at 10.0.1.30:8080
3 | dbs:
4 | - path: /Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db
5 | replicas:
6 | - name: "remote-master"
7 | type: "http"
8 | url: http://10.0.1.30:8080/mcp-memory
9 | sync-interval: 10s
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/quality/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """Quality scoring system for memory evaluation."""
2 | from .scorer import QualityScorer
3 | from .onnx_ranker import ONNXRankerModel
4 | from .ai_evaluator import QualityEvaluator
5 | from .implicit_signals import ImplicitSignalsEvaluator
6 | from .config import QualityConfig
7 |
8 | __all__ = [
9 | 'QualityScorer',
10 | 'ONNXRankerModel',
11 | 'QualityEvaluator',
12 | 'ImplicitSignalsEvaluator',
13 | 'QualityConfig'
14 | ]
15 |
```
--------------------------------------------------------------------------------
/scripts/.claude/settings.local.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "permissions": {
3 | "allow": [
4 | "mcp__code-context__index_codebase",
5 | "Bash(git commit:*)",
6 | "Bash(gh pr edit:*)",
7 | "Bash(gh api:*)",
8 | "Bash(git checkout:*)",
9 | "Bash(git pull:*)",
10 | "Bash(cat:*)",
11 | "Bash(git tag:*)",
12 | "Bash(git push:*)",
13 | "Bash(gh pr view:*)",
14 | "Bash(uv lock:*)",
15 | "Bash(git add:*)"
16 | ],
17 | "deny": [],
18 | "ask": []
19 | }
20 | }
```
--------------------------------------------------------------------------------
/scripts/testing/run_memory_test.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | set -e
3 |
4 | # Activate virtual environment
5 | source ./venv/bin/activate
6 |
7 | # Set environment variables
8 | export MCP_MEMORY_STORAGE_BACKEND="sqlite_vec"
9 | export MCP_MEMORY_SQLITE_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db"
10 | export MCP_MEMORY_BACKUPS_PATH="/Users/hkr/Library/Application Support/mcp-memory/backups"
11 | export MCP_MEMORY_USE_ONNX="1"
12 |
13 | # Run the memory server
14 | python -m mcp_memory_service.server
```
--------------------------------------------------------------------------------
/scripts/service/update_service.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | echo "Updating MCP Memory Service configuration..."
4 |
5 | # Copy the updated service file
6 | sudo cp mcp-memory.service /etc/systemd/system/
7 |
8 | # Set proper permissions
9 | sudo chmod 644 /etc/systemd/system/mcp-memory.service
10 |
11 | # Reload systemd daemon
12 | sudo systemctl daemon-reload
13 |
14 | echo "✅ Service updated successfully!"
15 | echo ""
16 | echo "Now try starting the service:"
17 | echo " sudo systemctl start mcp-memory"
18 | echo " sudo systemctl status mcp-memory"
```
--------------------------------------------------------------------------------
/scripts/pr/run_quality_checks.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # scripts/pr/run_quality_checks.sh - Run quality checks on a PR
3 | # Wrapper for quality_gate.sh to maintain consistent naming in workflows
4 | #
5 | # Usage: bash scripts/pr/run_quality_checks.sh <PR_NUMBER>
6 |
7 | set -e
8 |
9 | PR_NUMBER=$1
10 |
11 | if [ -z "$PR_NUMBER" ]; then
12 | echo "Usage: $0 <PR_NUMBER>"
13 | exit 1
14 | fi
15 |
16 | # Get script directory
17 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
18 |
19 | # Run quality gate checks
20 | exec "$SCRIPT_DIR/quality_gate.sh" "$PR_NUMBER"
21 |
```
--------------------------------------------------------------------------------
/tests/bridge/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "mcp-bridge-tests",
3 | "version": "1.0.0",
4 | "description": "Unit tests for HTTP-MCP bridge",
5 | "main": "test_http_mcp_bridge.js",
6 | "scripts": {
7 | "test": "mocha test_http_mcp_bridge.js --reporter spec",
8 | "test:watch": "mocha test_http_mcp_bridge.js --reporter spec --watch"
9 | },
10 | "dependencies": {
11 | "mocha": "^10.0.0",
12 | "sinon": "^17.0.0"
13 | },
14 | "devDependencies": {},
15 | "keywords": ["mcp", "bridge", "testing"],
16 | "author": "",
17 | "license": "Apache-2.0"
18 | }
```
--------------------------------------------------------------------------------
/scripts/development/setup-git-merge-drivers.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Setup script for git merge drivers
3 | # Run this once after cloning the repository
4 |
5 | echo "Setting up git merge drivers for uv.lock..."
6 |
7 | # Configure the uv.lock merge driver
8 | git config merge.uv-lock-merge.driver './scripts/uv-lock-merge.sh %O %A %B %L %P'
9 | git config merge.uv-lock-merge.name 'UV lock file merge driver'
10 |
11 | # Make the merge script executable
12 | chmod +x scripts/uv-lock-merge.sh
13 |
14 | echo "✓ Git merge drivers configured successfully!"
15 | echo " uv.lock conflicts will now be resolved automatically"
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/litestream_master_config.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Litestream Master Configuration for narrowbox.local
2 | # This configuration sets up the remote server as the master database
3 | dbs:
4 | - path: /home/user/.local/share/mcp-memory/sqlite_vec.db
5 | replicas:
6 | # Local file replica for serving via HTTP
7 | - type: file
8 | path: /var/www/litestream/mcp-memory
9 | sync-interval: 10s
10 |
11 | # Local backup
12 | - type: file
13 | path: /backup/litestream/mcp-memory
14 | sync-interval: 1m
15 |
16 | # Performance settings
17 | checkpoint-interval: 30s
18 | wal-retention: 10m
```
--------------------------------------------------------------------------------
/tests/integration/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "mcp-integration-tests",
3 | "version": "1.0.0",
4 | "description": "Integration tests for HTTP-MCP bridge",
5 | "main": "test_bridge_integration.js",
6 | "scripts": {
7 | "test": "mocha test_bridge_integration.js --reporter spec --timeout 10000",
8 | "test:watch": "mocha test_bridge_integration.js --reporter spec --timeout 10000 --watch"
9 | },
10 | "dependencies": {
11 | "mocha": "^10.0.0",
12 | "sinon": "^17.0.0"
13 | },
14 | "devDependencies": {},
15 | "keywords": ["mcp", "bridge", "integration", "testing"],
16 | "author": "",
17 | "license": "Apache-2.0"
18 | }
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
```yaml
1 | blank_issues_enabled: false
2 | contact_links:
3 | - name: 📚 Documentation & Wiki
4 | url: https://github.com/doobidoo/mcp-memory-service/wiki
5 | about: Check the Wiki for setup guides, troubleshooting, and advanced usage
6 | - name: 💬 GitHub Discussions
7 | url: https://github.com/doobidoo/mcp-memory-service/discussions
8 | about: Ask questions, share ideas, or discuss general topics with the community
9 | - name: 🔍 Search Existing Issues
10 | url: https://github.com/doobidoo/mcp-memory-service/issues
11 | about: Check if your issue has already been reported or solved
12 |
```
--------------------------------------------------------------------------------
/scripts/linux/uninstall_service.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "This will uninstall MCP Memory Service."
3 | read -p "Are you sure? (y/N): " confirm
4 | if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
5 | exit 0
6 | fi
7 |
8 | echo "Stopping service..."
9 | systemctl --user stop mcp-memory 2>/dev/null
10 | systemctl --user disable mcp-memory 2>/dev/null
11 |
12 | echo "Removing service files..."
13 | if [ -f "$HOME/.config/systemd/user/mcp-memory.service" ]; then
14 | rm -f "$HOME/.config/systemd/user/mcp-memory.service"
15 | systemctl --user daemon-reload
16 | else
17 | sudo rm -f /etc/systemd/system/mcp-memory.service
18 | sudo systemctl daemon-reload
19 | fi
20 |
21 | echo "✅ Service uninstalled"
22 |
```
--------------------------------------------------------------------------------
/archive/litestream-configs-v6.3.0/litestream_master_config_fixed.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Litestream Master Configuration for narrowbox.local (FIXED)
2 | # This configuration sets up the remote server as the master database
3 | dbs:
4 | - path: /home/hkr/.local/share/mcp-memory/sqlite_vec.db
5 | replicas:
6 | # HTTP replica for serving to clients
7 | - name: "http-replica"
8 | type: file
9 | path: /var/www/litestream/mcp-memory
10 | sync-interval: 10s
11 |
12 | # Local backup
13 | - name: "backup-replica"
14 | type: file
15 | path: /backup/litestream/mcp-memory
16 | sync-interval: 1m
17 |
18 | # Performance settings
19 | checkpoint-interval: 30s
20 | wal-retention: 10m
```
--------------------------------------------------------------------------------
/tests/api/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """Tests for code execution API."""
16 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/web/api/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | API routes for the HTTP interface.
17 | """
```
--------------------------------------------------------------------------------
/tools/docker/docker-compose.pythonpath.yml:
--------------------------------------------------------------------------------
```yaml
1 | services:
2 | memory-service:
3 | image: python:3.10-slim
4 | working_dir: /app
5 | stdin_open: true
6 | tty: true
7 | ports:
8 | - "8000:8000"
9 | volumes:
10 | - .:/app
11 | - ${CHROMA_DB_PATH:-$HOME/mcp-memory/chroma_db}:/app/chroma_db
12 | - ${BACKUPS_PATH:-$HOME/mcp-memory/backups}:/app/backups
13 | environment:
14 | - MCP_MEMORY_CHROMA_PATH=/app/chroma_db
15 | - MCP_MEMORY_BACKUPS_PATH=/app/backups
16 | - LOG_LEVEL=INFO
17 | - MAX_RESULTS_PER_QUERY=10
18 | - SIMILARITY_THRESHOLD=0.7
19 | - PYTHONPATH=/app/src:/app
20 | - PYTHONUNBUFFERED=1
21 | restart: unless-stopped
22 | build:
23 | context: .
24 | dockerfile: Dockerfile
25 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/models/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from .memory import Memory, MemoryQueryResult
16 |
17 | __all__ = ['Memory', 'MemoryQueryResult']
```
--------------------------------------------------------------------------------
/verify_compression.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | echo "=== Metadata Compression Verification ==="
3 | echo
4 |
5 | echo "1. Sync Status:"
6 | curl -s http://127.0.0.1:8000/api/sync/status | python3 -c "import sys, json; d=json.load(sys.stdin); print(f\" Failed: {d['operations_failed']} (should be 0)\")"
7 |
8 | echo
9 | echo "2. Quality Distribution:"
10 | curl -s http://127.0.0.1:8000/api/quality/distribution | python3 -c "import sys, json; d=json.load(sys.stdin); print(f\" ONNX scored: {d['provider_breakdown'].get('onnx_local', 0)}\")"
11 |
12 | echo
13 | echo "3. Recent Logs (compression activity):"
14 | tail -20 /tmp/mcp-http-server.log | grep -i "compress\|too large" || echo " No compression warnings (good!)"
15 |
16 | echo
17 | echo "✅ Verification complete!"
18 |
```
--------------------------------------------------------------------------------
/tools/docker/docker-compose.uv.yml:
--------------------------------------------------------------------------------
```yaml
1 | services:
2 | memory-service:
3 | image: python:3.10-slim
4 | working_dir: /app
5 | stdin_open: true
6 | tty: true
7 | ports:
8 | - "8000:8000"
9 | volumes:
10 | - .:/app
11 | - ${CHROMA_DB_PATH:-$HOME/mcp-memory/chroma_db}:/app/chroma_db
12 | - ${BACKUPS_PATH:-$HOME/mcp-memory/backups}:/app/backups
13 | environment:
14 | - MCP_MEMORY_CHROMA_PATH=/app/chroma_db
15 | - MCP_MEMORY_BACKUPS_PATH=/app/backups
16 | - LOG_LEVEL=INFO
17 | - MAX_RESULTS_PER_QUERY=10
18 | - SIMILARITY_THRESHOLD=0.7
19 | - PYTHONPATH=/app
20 | - PYTHONUNBUFFERED=1
21 | - UV_ACTIVE=1
22 | - CHROMA_TELEMETRY_IMPL=none
23 | - ANONYMIZED_TELEMETRY=false
24 | restart: unless-stopped
25 | build:
26 | context: .
27 | dockerfile: Dockerfile
28 |
```
--------------------------------------------------------------------------------
/scripts/sync/litestream/init_staging_db.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Initialize staging database for offline memory changes
3 |
4 | STAGING_DB="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec_staging.db"
5 | INIT_SQL="$(dirname "$0")/deployment/staging_db_init.sql"
6 |
7 | echo "$(date): Initializing staging database..."
8 |
9 | # Create directory if it doesn't exist
10 | mkdir -p "$(dirname "$STAGING_DB")"
11 |
12 | # Initialize database with schema
13 | sqlite3 "$STAGING_DB" < "$INIT_SQL"
14 |
15 | if [ $? -eq 0 ]; then
16 | echo "$(date): Staging database initialized at: $STAGING_DB"
17 | echo "$(date): Database size: $(du -h "$STAGING_DB" | cut -f1)"
18 | else
19 | echo "$(date): ERROR: Failed to initialize staging database"
20 | exit 1
21 | fi
22 |
23 | # Set permissions
24 | chmod 644 "$STAGING_DB"
25 |
26 | echo "$(date): Staging database ready for use"
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/utils/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | from .hashing import generate_content_hash
16 | from .document_processing import create_memory_from_chunk, _process_and_store_chunk
17 |
18 | __all__ = ['generate_content_hash', 'create_memory_from_chunk', '_process_and_store_chunk']
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/backup/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | Automatic backup module for MCP Memory Service.
17 |
18 | Provides scheduled backups and backup management functionality.
19 | """
20 |
21 | from .scheduler import BackupScheduler, BackupService
22 |
23 | __all__ = ['BackupScheduler', 'BackupService']
24 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/cli/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | Command Line Interface for MCP Memory Service
17 |
18 | Provides CLI commands for document ingestion, memory management, and database operations.
19 | """
20 |
21 | from .ingestion import add_ingestion_commands
22 |
23 | __all__ = ['add_ingestion_commands']
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/web/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | Web interface for MCP Memory Service.
17 |
18 | Provides HTTP REST API and Server-Sent Events (SSE) interface
19 | using FastAPI and SQLite-vec backend.
20 | """
21 |
22 | # Import version from main package to maintain consistency
23 | from .. import __version__
```
--------------------------------------------------------------------------------
/tools/docker/docker-compose.standalone.yml:
--------------------------------------------------------------------------------
```yaml
1 | services:
2 | memory-service:
3 | image: python:3.10-slim
4 | working_dir: /app
5 | stdin_open: true
6 | tty: true
7 | ports:
8 | - "8000:8000"
9 | volumes:
10 | - .:/app
11 | - ${CHROMA_DB_PATH:-$HOME/mcp-memory/chroma_db}:/app/chroma_db
12 | - ${BACKUPS_PATH:-$HOME/mcp-memory/backups}:/app/backups
13 | environment:
14 | - MCP_MEMORY_CHROMA_PATH=/app/chroma_db
15 | - MCP_MEMORY_BACKUPS_PATH=/app/backups
16 | - LOG_LEVEL=INFO
17 | - MAX_RESULTS_PER_QUERY=10
18 | - SIMILARITY_THRESHOLD=0.7
19 | - PYTHONPATH=/app
20 | - PYTHONUNBUFFERED=1
21 | - UV_ACTIVE=1
22 | - MCP_STANDALONE_MODE=1
23 | - CHROMA_TELEMETRY_IMPL=none
24 | - ANONYMIZED_TELEMETRY=false
25 | restart: unless-stopped
26 | build:
27 | context: .
28 | dockerfile: Dockerfile
29 | entrypoint: ["/usr/local/bin/docker-entrypoint-persistent.sh"]
```
--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
```yaml
1 | # These are supported funding model platforms
2 |
3 | # github: doobidoo # Uncomment when enrolled in GitHub Sponsors
4 | # patreon: # Replace with a single Patreon username
5 | # open_collective: # Replace with a single Open Collective username
6 | ko_fi: doobidoo # Replace with a single Ko-fi username
7 | # tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
8 | # community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
9 | # liberapay: # Replace with a single Liberapay username
10 | # issuehunt: # Replace with a single IssueHunt username
11 | # lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
12 | custom: ['https://www.buymeacoffee.com/doobidoo', 'https://paypal.me/heinrichkrupp1'] # Replace with up to 4 custom
13 | # sponsorship URLs e.g., ['', 'link2']
14 |
```
--------------------------------------------------------------------------------
/archive/deployment-configs/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
1 | # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
2 |
3 | startCommand:
4 | type: stdio
5 | configSchema:
6 | # JSON Schema defining the configuration options for the MCP.
7 | type: object
8 | required:
9 | - chromaDbPath
10 | - backupsPath
11 | properties:
12 | chromaDbPath:
13 | type: string
14 | description: Path to ChromaDB storage.
15 | backupsPath:
16 | type: string
17 | description: Path for backups.
18 | commandFunction:
19 | # A function that produces the CLI command to start the MCP on stdio.
20 | |-
21 | (config) => ({
22 | command: 'python',
23 | args: ['-m', 'mcp_memory_service.server'],
24 | env: {
25 | MCP_MEMORY_CHROMA_PATH: config.chromaDbPath,
26 | MCP_MEMORY_BACKUPS_PATH: config.backupsPath,
27 | PYTHONUNBUFFERED: '1',
28 | PYTORCH_ENABLE_MPS_FALLBACK: '1'
29 | }
30 | })
```
--------------------------------------------------------------------------------
/examples/claude_desktop_config_template.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "memory": {
4 | "_comment": "Recommended: Use Python module approach (most stable, no path dependencies)",
5 | "command": "python",
6 | "args": [
7 | "-m",
8 | "mcp_memory_service.server"
9 | ],
10 | "_alternative_approaches": [
11 | "Option 1 (UV): command='uv', args=['--directory', '${PROJECT_PATH}', 'run', 'memory', 'server']",
12 | "Option 2 (New script path): command='python', args=['${PROJECT_PATH}/scripts/server/run_memory_server.py']",
13 | "Option 3 (Legacy, shows migration notice): command='python', args=['${PROJECT_PATH}/scripts/run_memory_server.py']"
14 | ],
15 | "env": {
16 | "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
17 | "MCP_MEMORY_BACKUPS_PATH": "${USER_DATA_PATH}/mcp-memory/backups",
18 | "PYTORCH_ENABLE_MPS_FALLBACK": "1",
19 | "PYTORCH_CUDA_ALLOC_CONF": "max_split_size_mb:128"
20 | }
21 | }
22 | }
23 | }
```
--------------------------------------------------------------------------------
/scripts/server/start_http_server.bat:
--------------------------------------------------------------------------------
```
1 | @echo off
2 | REM Start the MCP Memory Service HTTP server in the background on Windows
3 |
4 | echo Starting MCP Memory Service HTTP server...
5 |
6 | REM Check if server is already running
7 | uv run python scripts\server\check_http_server.py -q
8 | if %errorlevel% == 0 (
9 | echo HTTP server is already running!
10 | uv run python scripts\server\check_http_server.py
11 | exit /b 0
12 | )
13 |
14 | REM Start the server in a new window
15 | start "MCP Memory HTTP Server" uv run python scripts\server\run_http_server.py
16 |
17 | REM Wait up to 5 seconds for the server to start
18 | FOR /L %%i IN (1,1,5) DO (
19 | timeout /t 1 /nobreak >nul
20 | uv run python scripts\server\check_http_server.py -q
21 | if %errorlevel% == 0 (
22 | echo.
23 | echo [OK] HTTP server started successfully!
24 | uv run python scripts\server\check_http_server.py
25 | goto :eof
26 | )
27 | )
28 |
29 | echo.
30 | echo [WARN] Server did not start within 5 seconds. Check the server window for errors.
31 |
```
--------------------------------------------------------------------------------
/scripts/sync/litestream/sync_from_remote.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Sync script to pull latest database from remote master
3 |
4 | DB_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db"
5 | REMOTE_URL="http://10.0.1.30:8080/mcp-memory"
6 | BACKUP_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db.backup"
7 |
8 | echo "$(date): Starting sync from remote master..."
9 |
10 | # Create backup of current database
11 | if [ -f "$DB_PATH" ]; then
12 | cp "$DB_PATH" "$BACKUP_PATH"
13 | echo "$(date): Created backup at $BACKUP_PATH"
14 | fi
15 |
16 | # Restore from remote
17 | litestream restore -o "$DB_PATH" "$REMOTE_URL"
18 |
19 | if [ $? -eq 0 ]; then
20 | echo "$(date): Successfully synced database from remote master"
21 | # Remove backup on success
22 | rm -f "$BACKUP_PATH"
23 | else
24 | echo "$(date): ERROR: Failed to sync from remote master"
25 | # Restore backup on failure
26 | if [ -f "$BACKUP_PATH" ]; then
27 | mv "$BACKUP_PATH" "$DB_PATH"
28 | echo "$(date): Restored backup"
29 | fi
30 | exit 1
31 | fi
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/server/handlers/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | Handler modules for MCP Memory Service.
17 |
18 | Extracted from monolithic server_impl.py for better maintainability.
19 | Each module contains related handler functions for specific functionality.
20 | """
21 |
22 | from . import memory, consolidation, utility, documents, quality, graph
23 |
24 | __all__ = ['memory', 'consolidation', 'utility', 'documents', 'quality', 'graph']
25 |
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/discovery/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | mDNS service discovery module for MCP Memory Service.
17 |
18 | This module provides mDNS service advertisement and discovery capabilities
19 | for the MCP Memory Service HTTP/HTTPS interface.
20 | """
21 |
22 | from .mdns_service import ServiceAdvertiser, ServiceDiscovery
23 | from .client import DiscoveryClient
24 |
25 | __all__ = ['ServiceAdvertiser', 'ServiceDiscovery', 'DiscoveryClient']
```
--------------------------------------------------------------------------------
/scripts/development/uv-lock-merge.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Git merge driver for uv.lock files
3 | # Automatically resolves conflicts and regenerates the lock file
4 |
5 | # Arguments from git:
6 | # %O = ancestor's version
7 | # %A = current version
8 | # %B = other version
9 | # %L = conflict marker length
10 | # %P = path to file
11 |
12 | ANCESTOR="$1"
13 | CURRENT="$2"
14 | OTHER="$3"
15 | MARKER_LENGTH="$4"
16 | PATH="$5"
17 |
18 | echo "Auto-resolving uv.lock conflict by regenerating lock file..."
19 |
20 | # Accept the incoming version first (this resolves the conflict)
21 | cp "$OTHER" "$PATH"
22 |
23 | # Check if uv is available
24 | if command -v uv >/dev/null 2>&1; then
25 | echo "Running uv sync to regenerate lock file..."
26 | # Regenerate the lock file based on pyproject.toml
27 | uv sync --quiet
28 | if [ $? -eq 0 ]; then
29 | echo "✓ uv.lock regenerated successfully"
30 | exit 0
31 | else
32 | echo "⚠ Warning: uv sync failed, using incoming version"
33 | exit 0
34 | fi
35 | else
36 | echo "⚠ Warning: uv not found, using incoming version"
37 | exit 0
38 | fi
```
--------------------------------------------------------------------------------
/.github/workflows/dockerfile-lint.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: Dockerfile Lint
2 |
3 | on:
4 | push:
5 | paths:
6 | - 'tools/docker/Dockerfile*'
7 | - '.github/workflows/dockerfile-lint.yml'
8 | pull_request:
9 | paths:
10 | - 'tools/docker/Dockerfile*'
11 | - '.github/workflows/dockerfile-lint.yml'
12 |
13 | jobs:
14 | hadolint:
15 | runs-on: ubuntu-latest
16 | steps:
17 | - name: Checkout repository
18 | uses: actions/checkout@v4
19 |
20 | - name: Lint Dockerfile (main)
21 | uses: hadolint/[email protected]
22 | with:
23 | dockerfile: tools/docker/Dockerfile
24 | failure-threshold: warning
25 |
26 | - name: Lint Dockerfile.slim
27 | uses: hadolint/[email protected]
28 | with:
29 | dockerfile: tools/docker/Dockerfile.slim
30 | failure-threshold: warning
31 |
32 | unused-args:
33 | runs-on: ubuntu-latest
34 | steps:
35 | - name: Checkout repository
36 | uses: actions/checkout@v4
37 |
38 | - name: Check for unused Docker ARGs
39 | run: bash scripts/ci/check_dockerfile_args.sh
40 |
```
--------------------------------------------------------------------------------
/archive/deployment/deploy_fastmcp_fixed.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | echo "🚀 Deploying Fixed FastMCP Server v4.0.0-alpha.1..."
4 |
5 | # Stop current service
6 | echo "⏹️ Stopping current service..."
7 | sudo systemctl stop mcp-memory
8 |
9 | # Install the fixed FastMCP service configuration
10 | echo "📝 Installing fixed FastMCP service configuration..."
11 | sudo cp /tmp/fastmcp-server-fixed.service /etc/systemd/system/mcp-memory.service
12 |
13 | # Reload systemd daemon
14 | echo "🔄 Reloading systemd daemon..."
15 | sudo systemctl daemon-reload
16 |
17 | # Start the FastMCP server
18 | echo "▶️ Starting FastMCP server..."
19 | sudo systemctl start mcp-memory
20 |
21 | # Wait a moment for startup
22 | sleep 3
23 |
24 | # Check status
25 | echo "🔍 Checking service status..."
26 | sudo systemctl status mcp-memory --no-pager
27 |
28 | echo ""
29 | echo "📊 Service logs (last 10 lines):"
30 | sudo journalctl -u mcp-memory -n 10 --no-pager
31 |
32 | echo ""
33 | echo "✅ FastMCP Server deployment complete!"
34 | echo "🔗 Native MCP Protocol should be available on port 8000"
35 | echo "📋 Monitor logs: sudo journalctl -u mcp-memory -f"
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/storage/migrations/008_add_graph_table.sql:
--------------------------------------------------------------------------------
```sql
1 | -- Migration 008: Add graph-based memory associations table
2 | -- Supports triple storage modes: memories_only (backward compat), dual_write (migration), graph_only (future)
3 | -- Connection types: semantic (0.3-0.7), temporal (<24h), causal (explicit refs), thematic (shared tags)
4 |
5 | CREATE TABLE IF NOT EXISTS memory_graph (
6 | source_hash TEXT NOT NULL,
7 | target_hash TEXT NOT NULL,
8 | similarity REAL NOT NULL,
9 | connection_types TEXT NOT NULL, -- JSON array: ["semantic", "temporal", "causal", "thematic"]
10 | metadata TEXT, -- JSON object: {discovery_date, confidence, context}
11 | created_at REAL NOT NULL,
12 | PRIMARY KEY (source_hash, target_hash)
13 | );
14 |
15 | -- Optimize bidirectional traversal (A→B and B→A queries)
16 | -- Note: PRIMARY KEY already creates an index on (source_hash, target_hash)
17 | CREATE INDEX IF NOT EXISTS idx_graph_source ON memory_graph(source_hash);
18 | CREATE INDEX IF NOT EXISTS idx_graph_target ON memory_graph(target_hash);
19 |
```
--------------------------------------------------------------------------------
/archive/development/test_fastmcp.py:
--------------------------------------------------------------------------------
```python
1 | #!/usr/bin/env python3
2 | """Simple test of FastMCP server structure for memory service."""
3 |
4 | import sys
5 | import os
6 | from pathlib import Path
7 |
8 | # Add src to path
9 | sys.path.insert(0, 'src')
10 |
11 | from mcp.server.fastmcp import FastMCP
12 |
13 | # Create a simple FastMCP server for testing
14 | mcp = FastMCP("Test Memory Service")
15 |
16 | @mcp.tool()
17 | def test_store_memory(content: str, tags: list[str] = None) -> dict:
18 | """Test memory storage function."""
19 | return {
20 | "success": True,
21 | "message": f"Stored: {content}",
22 | "tags": tags or []
23 | }
24 |
25 | @mcp.tool()
26 | def test_health() -> dict:
27 | """Test health check."""
28 | return {
29 | "status": "healthy",
30 | "version": "4.0.0-alpha.1"
31 | }
32 |
33 | if __name__ == "__main__":
34 | print("FastMCP Memory Service Test")
35 | print("Server configured with basic tools")
36 | print("Available tools:")
37 | print("- test_store_memory")
38 | print("- test_health")
39 | print("\nTo run server: mcp.run(transport='streamable-http')")
```
--------------------------------------------------------------------------------
/src/mcp_memory_service/sync/__init__.py:
--------------------------------------------------------------------------------
```python
1 | # Copyright 2024 Heinrich Krupp
2 | #
3 | # Licensed under the Apache License, Version 2.0 (the "License");
4 | # you may not use this file except in compliance with the License.
5 | # You may obtain a copy of the License at
6 | #
7 | # http://www.apache.org/licenses/LICENSE-2.0
8 | #
9 | # Unless required by applicable law or agreed to in writing, software
10 | # distributed under the License is distributed on an "AS IS" BASIS,
11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | # See the License for the specific language governing permissions and
13 | # limitations under the License.
14 |
15 | """
16 | Database synchronization module for MCP Memory Service.
17 |
18 | This module provides tools for synchronizing SQLite-vec databases across
19 | multiple machines using JSON export/import and Litestream replication.
20 | """
21 |
22 | from .exporter import MemoryExporter
23 | from .importer import MemoryImporter
24 | from .litestream_config import LitestreamManager
25 |
26 | __all__ = ['MemoryExporter', 'MemoryImporter', 'LitestreamManager']
```
--------------------------------------------------------------------------------
/start_http_server.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | # Load .env file if it exists
4 | if [ -f .env ]; then
5 | set -a
6 | source .env
7 | set +a
8 | fi
9 |
10 | export MCP_MEMORY_STORAGE_BACKEND=hybrid
11 | export MCP_MEMORY_SQLITE_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db"
12 | export MCP_HTTP_ENABLED=true
13 | export MCP_OAUTH_ENABLED=false
14 | export CLOUDFLARE_API_TOKEN="Y9qwW1rYkwiE63iWYASxnzfTQlIn-mtwCihRTwZa"
15 | export CLOUDFLARE_ACCOUNT_ID="be0e35a26715043ef8df90253268c33f"
16 | export CLOUDFLARE_D1_DATABASE_ID="f745e9b4-ba8e-4d47-b38f-12af91060d5a"
17 | export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index"
18 |
19 | cd /Users/hkr/Documents/GitHub/mcp-memory-service
20 |
21 | # Detect Python command
22 | if command -v python3 &> /dev/null; then
23 | PYTHON_CMD=python3
24 | elif command -v python &> /dev/null; then
25 | PYTHON_CMD=python
26 | else
27 | echo "Error: Python not found in PATH"
28 | exit 1
29 | fi
30 |
31 | # Use MCP_HTTP_PORT environment variable, default to 8000
32 | PORT=${MCP_HTTP_PORT:-8000}
33 |
34 | $PYTHON_CMD -m uvicorn mcp_memory_service.web.app:app --host 127.0.0.1 --port $PORT --reload
35 |
```
--------------------------------------------------------------------------------
/docs/images/dashboard-placeholder.md:
--------------------------------------------------------------------------------
```markdown
1 | # Dashboard Screenshot Placeholder
2 |
3 | This directory will contain screenshots of the MCP Memory Service dashboard.
4 |
5 | ## v3.3.0 Dashboard Features
6 |
7 | The new dashboard includes:
8 |
9 | - **Modern Design**: Gradient backgrounds with professional card layout
10 | - **Live Statistics**: Real-time server metrics and memory counts
11 | - **Interactive Endpoints**: Organized API documentation with hover effects
12 | - **Tech Stack Badges**: Visual representation of FastAPI, SQLite-vec, PyTorch, etc.
13 | - **Responsive Layout**: Works on desktop and mobile devices
14 | - **Auto-Refresh**: Stats update every 30 seconds
15 |
16 | ## Access URLs
17 |
18 | - Dashboard: http://localhost:8000
19 | - mDNS: http://mcp-memory-service.local:8000
20 | - API Docs: http://localhost:8000/api/docs
21 | - ReDoc: http://localhost:8000/api/redoc
22 |
23 | ## Screenshot Instructions
24 |
25 | To capture the dashboard:
26 |
27 | 1. Ensure the HTTP server is running
28 | 2. Open browser to http://localhost:8000
29 | 3. Wait for stats to load (shows actual memory count)
30 | 4. Take full-page screenshot
31 | 5. Save as `dashboard-v3.3.0.png` in this directory
```
--------------------------------------------------------------------------------
/tests/unit/test_import.py:
--------------------------------------------------------------------------------
```python
1 | #!/usr/bin/env python3
2 | """
3 | Test script to verify the memory service can be imported and run.
4 | """
5 | import sys
6 | import os
7 |
8 | # Add the src directory to the Python path
9 | script_dir = os.path.dirname(os.path.abspath(__file__))
10 | src_dir = os.path.join(script_dir, "src")
11 | sys.path.insert(0, src_dir)
12 |
13 | try:
14 | from mcp_memory_service.server import main
15 | print("SUCCESS: Successfully imported mcp_memory_service.server.main")
16 |
17 | # Test basic configuration
18 | from mcp_memory_service.config import (
19 | SERVER_NAME,
20 | SERVER_VERSION,
21 | STORAGE_BACKEND,
22 | DATABASE_PATH
23 | )
24 | print(f"SUCCESS: Server name: {SERVER_NAME}")
25 | print(f"SUCCESS: Server version: {SERVER_VERSION}")
26 | print(f"SUCCESS: Storage backend: {STORAGE_BACKEND}")
27 | print(f"SUCCESS: Database path: {DATABASE_PATH}")
28 |
29 | print("SUCCESS: All imports successful - the memory service is ready to use!")
30 |
31 | except ImportError as e:
32 | print(f"ERROR: Import failed: {e}")
33 | sys.exit(1)
34 | except Exception as e:
35 | print(f"ERROR: Error: {e}")
36 | sys.exit(1)
37 |
```
--------------------------------------------------------------------------------
/archive/docs-removed-2025-08-23/development/CLEANUP_README.md:
--------------------------------------------------------------------------------
```markdown
1 | # MCP-MEMORY-SERVICE Cleanup and Organization
2 |
3 | This branch contains cleanup and reorganization changes for the MCP-MEMORY-SERVICE project.
4 |
5 | ## Changes Implemented
6 |
7 | 1. **Code Organization**
8 | - Restructured test files into proper directories
9 | - Organized documentation into a docs/ directory
10 | - Archived old backup files
11 |
12 | 2. **Documentation Updates**
13 | - Updated CHANGELOG.md with v1.2.0 entries
14 | - Created comprehensive documentation structure
15 | - Added READMEs for each directory
16 |
17 | 3. **Test Infrastructure**
18 | - Created proper pytest configuration
19 | - Added fixtures for common test scenarios
20 | - Organized tests by type (unit, integration, performance)
21 |
22 | ## Running the Cleanup Script
23 |
24 | To apply these changes, run:
25 |
26 | ```bash
27 | cd C:\REPOSITORIES\mcp-memory-service
28 | python scripts/cleanup_organize.py
29 | ```
30 |
31 | ## Testing on Different Hardware
32 |
33 | After organization is complete, create a hardware testing branch:
34 |
35 | ```bash
36 | git checkout -b test/hardware-validation
37 | ```
38 |
39 | The changes have been tracked in the memory system with the tag `memory-driven-development`.
40 |
```
--------------------------------------------------------------------------------
/scripts/server/start_http_server.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/usr/bin/env bash
2 | # Start the MCP Memory Service HTTP server in the background on Unix/macOS
3 |
4 | set -e
5 |
6 | echo "Starting MCP Memory Service HTTP server..."
7 |
8 | # Check if server is already running
9 | if uv run python scripts/server/check_http_server.py -q; then
10 | echo "✅ HTTP server is already running!"
11 | uv run python scripts/server/check_http_server.py -v
12 | exit 0
13 | fi
14 |
15 | # Start the server in the background
16 | nohup uv run python scripts/server/run_http_server.py > /tmp/mcp-http-server.log 2>&1 &
17 | SERVER_PID=$!
18 |
19 | echo "Server started with PID: $SERVER_PID"
20 | echo "Logs available at: /tmp/mcp-http-server.log"
21 |
22 | # Wait up to 5 seconds for the server to start
23 | for i in {1..5}; do
24 | if uv run python scripts/server/check_http_server.py -q; then
25 | break
26 | fi
27 | sleep 1
28 | done
29 |
30 | # Check if it started successfully
31 | if uv run python scripts/server/check_http_server.py -v; then
32 | echo ""
33 | echo "✅ HTTP server started successfully!"
34 | echo "PID: $SERVER_PID"
35 | else
36 | echo ""
37 | echo "⚠️ Server may still be starting... Check logs at /tmp/mcp-http-server.log"
38 | fi
39 |
```
--------------------------------------------------------------------------------
/claude-hooks/simple-test.js:
--------------------------------------------------------------------------------
```javascript
1 | #!/usr/bin/env node
2 |
3 | const { AdaptivePatternDetector } = require('./utilities/adaptive-pattern-detector');
4 |
5 | async function simpleTest() {
6 | const detector = new AdaptivePatternDetector({ sensitivity: 0.7 });
7 |
8 | const testCases = [
9 | { message: "What did we decide about the authentication approach?", shouldTrigger: true },
10 | { message: "Remind me how we handled user sessions", shouldTrigger: true },
11 | { message: "Remember when we discussed the database schema?", shouldTrigger: true },
12 | { message: "Just implementing a new feature", shouldTrigger: false }
13 | ];
14 |
15 | for (const testCase of testCases) {
16 | const result = await detector.detectPatterns(testCase.message);
17 | const actualTrigger = result.triggerRecommendation;
18 |
19 | console.log(`Message: "${testCase.message}"`);
20 | console.log(`Expected: ${testCase.shouldTrigger}, Actual: ${actualTrigger}`);
21 | console.log(`Confidence: ${result.confidence}`);
22 | console.log(`Matches: ${result.matches.length}`);
23 | console.log('---');
24 | }
25 | }
26 |
27 | simpleTest().catch(console.error);
```
--------------------------------------------------------------------------------
/scripts/sync/litestream/sync_from_remote_noconfig.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Sync script to pull latest database from remote master (no config file)
3 |
4 | DB_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db"
5 | REMOTE_URL="http://10.0.1.30:8080/mcp-memory"
6 | BACKUP_PATH="/Users/hkr/Library/Application Support/mcp-memory/sqlite_vec.db.backup"
7 |
8 | echo "$(date): Starting sync from remote master..."
9 |
10 | # Create backup of current database
11 | if [ -f "$DB_PATH" ]; then
12 | cp "$DB_PATH" "$BACKUP_PATH"
13 | echo "$(date): Created backup at $BACKUP_PATH"
14 | fi
15 |
16 | # Restore from remote (no config file)
17 | litestream restore -o "$DB_PATH" "$REMOTE_URL"
18 |
19 | if [ $? -eq 0 ]; then
20 | echo "$(date): Successfully synced database from remote master"
21 | # Remove backup on success
22 | rm -f "$BACKUP_PATH"
23 |
24 | # Show database info
25 | echo "$(date): Database size: $(du -h "$DB_PATH" | cut -f1)"
26 | echo "$(date): Database modified: $(stat -f "%Sm" "$DB_PATH")"
27 | else
28 | echo "$(date): ERROR: Failed to sync from remote master"
29 | # Restore backup on failure
30 | if [ -f "$BACKUP_PATH" ]; then
31 | mv "$BACKUP_PATH" "$DB_PATH"
32 | echo "$(date): Restored backup"
33 | fi
34 | exit 1
35 | fi
```
--------------------------------------------------------------------------------
/scripts/development/fix_mdns.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 |
3 | echo "=== Fixing mDNS Configuration ==="
4 |
5 | echo "1. Stopping any conflicting processes..."
6 | # Kill the old process that might be interfering
7 | pkill -f "/home/hkr/repositories/mcp-memory-service/.venv/bin/memory"
8 |
9 | echo "2. Stopping systemd service..."
10 | sudo systemctl stop mcp-memory
11 |
12 | echo "3. Updating systemd service configuration..."
13 | sudo cp mcp-memory.service /etc/systemd/system/
14 | sudo chmod 644 /etc/systemd/system/mcp-memory.service
15 |
16 | echo "4. Reloading systemd daemon..."
17 | sudo systemctl daemon-reload
18 |
19 | echo "5. Starting service with new configuration..."
20 | sudo systemctl start mcp-memory
21 |
22 | echo "6. Checking service status..."
23 | sudo systemctl status mcp-memory --no-pager -l
24 |
25 | echo ""
26 | echo "7. Testing mDNS resolution..."
27 | sleep 3
28 | echo "Checking avahi browse:"
29 | avahi-browse -t _http._tcp | grep memory
30 | echo ""
31 | echo "Testing memory.local resolution:"
32 | avahi-resolve-host-name memory.local
33 | echo ""
34 | echo "Testing HTTPS access:"
35 | curl -k -s https://memory.local:8000/api/health --connect-timeout 5 || echo "HTTPS test failed"
36 |
37 | echo ""
38 | echo "=== Fix Complete ==="
39 | echo "If memory.local resolves and HTTPS works, you're all set!"
```