Introduce BASIC_MEMORY_PROJECT_ROOT to replace cloud mode path constraints

[phernandez]

Problem

Currently, BASIC_MEMORY_HOME has dual, conflicting semantics:

1. Original intent: Path to the "main" (default) project directory
2. Cloud mode usage: Root directory where ALL projects must be created

This creates confusion and doesn't properly separate concerns.

Example of the Issue

With BASIC_MEMORY_HOME=/app/data/basic-memory:

• Main project files: /app/data/basic-memory/*.md (at the root)
• New project "test": /app/data/basic-memory/test/ (subdirectory)
• Result: Main project files and other project directories are mixed together

Current Cloud Mode Implementation

In PR #332, we implemented path validation that constrains projects to BASIC_MEMORY_HOME when cloud mode is enabled. However, this couples path restriction to cloud mode, when really it's about filesystem constraints.

Proposed Solution

Introduce a new environment variable that explicitly handles project path constraints:

BASIC_MEMORY_PROJECT_ROOT

Behavior:

• If set: ALL projects must be created underneath this directory (path sanitization enforced)
• If not set: Projects can be created anywhere (current default behavior)

Semantics:

• BASIC_MEMORY_HOME: Location of the "main" project (backward compatible, unchanged)
• BASIC_MEMORY_PROJECT_ROOT: Optional root directory for all projects

Benefits

1. ✅ Decouples path restriction from cloud mode (useful for any constrained environment)
2. ✅ Backward compatible - existing users with custom BASIC_MEMORY_HOME unaffected
3. ✅ More explicit - "project root" is clearer than overloading "home"
4. ✅ Flexible - works in both cloud and local constrained environments

Example Usage

Cloud Mode

BASIC_MEMORY_HOME=/app/data/basic-memory  # main project location
BASIC_MEMORY_PROJECT_ROOT=/app/data       # all projects must be under /app/data

Results:

• Input: /tmp/test → /app/data/tmp/test (sanitized)
• Input: test → /app/data/test
• Main project: /app/data/basic-memory/ (unchanged)

Local Mode with Constraints

BASIC_MEMORY_HOME=~/basic-memory          # main project
BASIC_MEMORY_PROJECT_ROOT=~/my-projects   # all projects under here

Local Mode Unrestricted (Default)

BASIC_MEMORY_HOME=~/basic-memory          # main project
# BASIC_MEMORY_PROJECT_ROOT not set - projects can be anywhere

Implementation Changes

1. config.py - Add BASIC_MEMORY_PROJECT_ROOT field to BasicMemoryConfig
2. project_service.py - Update add_project() to check BASIC_MEMORY_PROJECT_ROOT instead of cloud_mode_enabled
3. Dockerfile (basic-memory-cloud) - Set BASIC_MEMORY_PROJECT_ROOT=/app/data instead of BASIC_MEMORY_CLOUD_MODE
4. Tests - Update cloud mode tests to use BASIC_MEMORY_PROJECT_ROOT
5. Documentation - Update docs to explain the new variable and deprecation of relying on cloud mode for path constraints

Migration Path

• BASIC_MEMORY_HOME continues to work as-is (no breaking changes)
• Cloud deployments update to use BASIC_MEMORY_PROJECT_ROOT
• BASIC_MEMORY_CLOUD_MODE can remain for other cloud-specific behaviors if needed

Related

• PR fix: cloud mode path validation and sanitization (bmc-issue-103) #332 - Initial cloud mode path validation implementation
• Issue fix: preserve Chinese characters in permalinks #103 (basic-memory-cloud) - Original cloud path validation bug

cc: @phernandez

[claude]

Claude finished @phernandez's task —— View job

---

Issue Triage Analysis - Issue #333

Todo List:

• Gather context from codebase
• Review current implementation
• Classify issue type and priority
• Check for duplicates
• Add appropriate labels
• Provide triage analysis

---

Classification

Type: Enhancement (Architectural Improvement)

Priority: High

• Addresses architectural confusion in the codebase
• Impacts cloud deployments and any constrained environments
• Backward compatible, but important for clarity and maintainability

Component: Cloud, Configuration, Project Management

Complexity: Medium

• Well-defined scope with clear implementation plan
• Requires changes across 5-6 files
• Good test coverage exists for cloud mode behavior
• Migration path is straightforward

---

Analysis

This is a well-researched enhancement proposal that addresses a real architectural issue in the codebase.

Current State

I reviewed the implementation in PR #332 and found:

• cloud_mode_enabled in config.py:config.py:136-149 controls path validation
• add_project() in project_service.py:102-127 uses cloud_mode_enabled to determine path sanitization
• Cloud mode tests in test_project_service.py:721-809 validate the current behavior

The Problem

The issue correctly identifies that BASIC_MEMORY_HOME has dual semantics:

1. Location of the "main" project
2. Root directory for ALL projects (in cloud mode)

This couples filesystem constraints to "cloud mode" when it's really about where projects can be created.

Proposed Solution

Introducing BASIC_MEMORY_PROJECT_ROOT would:

• ✅ Decouple path restriction from cloud mode
• ✅ Be useful in any constrained environment (not just cloud)
• ✅ Maintain backward compatibility
• ✅ Make the configuration more explicit and clear

Implementation Impact

Files to modify:

1. src/basic_memory/config.py - Add BASIC_MEMORY_PROJECT_ROOT field
2. src/basic_memory/services/project_service.py - Update path validation logic
3. Dockerfile - Set BASIC_MEMORY_PROJECT_ROOT instead of relying on cloud mode
4. tests/services/test_project_service.py - Update cloud mode tests
5. Documentation files

Migration Path:

• Existing deployments continue to work unchanged
• Cloud deployments update environment variables
• BASIC_MEMORY_CLOUD_MODE can remain for other cloud-specific behaviors

---

Recommendation

Approve this enhancement for implementation.

This proposal:

• Solves a real architectural confusion
• Has a clear, well-thought-out implementation plan
• Maintains backward compatibility
• Improves code clarity and separation of concerns
• Comes with existing test infrastructure that can be adapted

The issue author has done excellent research and provided a complete implementation roadmap. This is ready to be worked on.

---

Next Steps

If you'd like me to implement this enhancement, I can:

1. Add the BASIC_MEMORY_PROJECT_ROOT configuration field
2. Update the path validation logic in add_project()
3. Update tests to use the new variable
4. Update the Dockerfile
5. Create a pull request with all changes

Just let me know if you'd like me to proceed with implementation!

---