feat: Add cloud discovery touchpoints to CLI and MCP

[phernandez]

Summary

Implements ethical cloud discovery touchpoints for open-source users without prompt injection, based on the team plan.

What changed

• Added CLI promo state to config:
  • cloud_promo_opt_out
  • cloud_promo_first_run_shown
  • cloud_promo_last_version_shown
• Added new CLI promo module with gated first-run and promo-version messaging:
  • src/basic_memory/cli/promo.py
• Wired promo checks into CLI startup callback.
• Added bm cloud promo --on/--off to let users opt out/in directly.
• Updated cloud login subscription-required message to include placeholder OSS discount code.
• Added opt-in MCP tools:
  • cloud_info()
  • release_notes()
• Added markdown resource content for those tools.
• Updated docs/README cloud copy to keep cloud optional and include placeholder OSS discount copy.
• Added tests for promo behavior and new MCP tools.
• Updated MCP tool contract test expectations.

Guardrails and behavior

• No prompt injection into existing MCP tool outputs.
• Cloud discovery in MCP is user-initiated via explicit tool calls only.
• CLI promo is skipped for non-interactive runs and mcp subcommand.
• CLI promo can be disabled via config command and env kill switch (BASIC_MEMORY_NO_PROMOS=1).

Validation

• uv run pytest tests/cli/test_cloud_promo.py tests/cli/test_cloud_authentication.py tests/mcp/test_tool_cloud_discovery.py tests/mcp/test_tool_contracts.py
• uv run pytest tests/test_config.py tests/cli/test_cli_exit.py tests/cli/test_cli_tool_exit.py tests/mcp/test_tool_project_management.py tests/mcp/test_resources.py
• uv run ruff check ... on changed modules/tests
• uv run pyright src/basic_memory/cli/promo.py src/basic_memory/cli/commands/cloud/core_commands.py src/basic_memory/mcp/tools/cloud_info.py src/basic_memory/mcp/tools/release_notes.py

Notes

• Discount code remains a placeholder: {{OSS_DISCOUNT_CODE}}
• Promo-version key currently set to: 2026-02-06

[github-actions]

Claude finished @phernandez's task in 2m 48s —— View job

---

Code Review Complete ✓

I've reviewed this PR against the Basic Memory team checklist. Overall, this is a well-implemented, ethical cloud discovery feature that follows the project's standards. Below are my detailed findings:

---

✅ Code Quality & Standards

Strengths:

• Literate programming style: promo.py:59-67 uses excellent decision-point comments explaining trigger/why/outcome
• Type annotations: All functions properly typed with Python 3.12+ style (str | None)
• 100-char line limit: Maintained throughout
• No commented-out code: Clean implementation
• Proper async patterns: Not applicable (synchronous code)
• Coding conventions: Follows CLAUDE.md guidelines

Minor observations:

• Config fields (config.py:224-237) lack explicit tests in tests/test_config.py, but they are indirectly tested through test_cloud_promo.py ✓

---

✅ Testing & Documentation

Strengths:

• Comprehensive test coverage: 10 test cases in test_cloud_promo.py covering:
  • First-run messaging
  • Version bumps
  • Opt-out behavior
  • Environment kill switch
  • Interactive detection
  • CLI command integration
• MCP tool tests: test_tool_cloud_discovery.py validates both new tools
• Tool contract tests: Updated in test_tool_contracts.py to include cloud_info and release_notes
• Documentation updated: README.md and docs/cloud-cli.md include discount code messaging

Coverage status:

• New code appears fully tested (202 lines in test_cloud_promo.py, 20 in test_tool_cloud_discovery.py)
• No # pragma: no cover in new files ✓

---

✅ Basic Memory Architecture

Strengths:

• MCP tools follow atomic design: cloud_info() and release_notes() are simple, composable tools
• No database changes: No migrations needed
• Local-first preserved: Cloud is explicitly optional, promo is skippable
• Proper file handling: Uses Path objects with / separator (Windows-compatible)
• Clean separation: Promo logic isolated in dedicated module

Architecture compliance:

• ✓ Tools registered in mcp/tools/__init__.py
• ✓ Resources stored in mcp/resources/*.md
• ✓ Config managed via ConfigManager
• ✓ CLI integrated via callback in app.py:50

---

✅ Security & Performance

Strengths:

• No hardcoded secrets: Discount code is a placeholder {{OSS_DISCOUNT_CODE}}
• Input validation: Promo logic validates config state before displaying
• Proper error handling: Graceful fallbacks for missing config
• No sensitive data: Promo state is non-sensitive boolean flags
• Performance: Minimal overhead (one config read, early returns)

Security considerations:

• ✓ No prompt injection into MCP tool outputs (user-initiated only)
• ✓ Environment kill switch (BASIC_MEMORY_NO_PROMOS=1)
• ✓ User opt-out via bm cloud promo --off

---

✅ Compatibility

Windows compatibility:

• ✓ Path operations use Path with / operator (cloud_info.py:11, release_notes.py:11)
• ✓ No hardcoded path separators
• ✓ No emojis or unicode in console output (verified via grep)
• ✓ sys.stdin.isatty() and sys.stdout.isatty() are cross-platform

---

📋 Team Checklist Results

Code Quality & Standards

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns
• SQLAlchemy 2.0 best practices (N/A - no DB changes)
• FastAPI and Typer conventions followed
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation

• Unit tests for new functions/methods
• Integration tests for new MCP tools
• Test coverage for edge cases
• 100% test coverage maintained (no # pragma: no cover in new code)
• Documentation updated (README, docstrings)
• CLAUDE.md updated if conventions change (N/A - no convention changes)

Basic Memory Architecture

• MCP tools follow atomic, composable design
• Database changes include Alembic migrations (N/A - no DB changes)
• Preserves local-first architecture principles
• Knowledge graph operations maintain consistency (N/A - no KG changes)
• Markdown file handling preserves integrity (N/A - no markdown changes)
• AI-human collaboration patterns followed

Security & Performance

• No hardcoded secrets or credentials
• Input validation for MCP tools
• Proper error handling and logging
• Performance considerations addressed
• No sensitive data in logs or commits

Compatibility

• File path comparisons must be Windows compatible
• Avoid using emojis and unicode characters in console and log output

---

🎯 Summary

This PR is production-ready. The implementation demonstrates:

1. Ethical design: No prompt injection, user-initiated discovery, multiple opt-out mechanisms
2. Clean code: Literate programming style with clear decision-point comments
3. Comprehensive testing: 10 promo tests + 2 MCP tool tests + contract updates
4. Architecture compliance: Follows established patterns for CLI, MCP, and config
5. Security: No secrets, proper validation, user control
6. Compatibility: Windows-friendly paths, no unicode issues

No issues found that would block merging.

The placeholder discount code ({{OSS_DISCOUNT_CODE}}) will need to be replaced before production deployment, but that's tracked in the PR notes.

---