[BUG] Support per-project variables and automated setup in mcp.json for basic-memory MCP

[jpmurray]

Feature Description

Enable the mcp.json configuration for basic-memory to support per-project variables, allowing users to specify project names and memory root paths directly in the configuration file. This will allow users to easily copy, modify, and reuse these configurations across different projects, with support for arguments like --project and --memory_home.

Problem This Feature Solves

Currently, mcp.json only supports a generic setup, which is limiting in multi-project environments. Users cannot specify different project roots or memory paths per project, making it harder to reuse and adapt configurations for different projects. I'm guessing this can be applied to other editor, but I'd use that with Roo Code + VSCode.

Proposed Solution

Allow mcp.json to accept variables such as --project and --memory_home in the args array, e.g.:

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "--project=project", "--memory_home=~/path", "mcp"]
    }
  }
}

• The system should recognize and use these variables per project.
• If the project or path does not exist, it should be created automatically.
• Make it easy to copy/paste the configuration for use in other projects with minimal adjustments.

Alternative Solutions

Manual editing of the configuration and setup of project directories, but this is cumbersome and error-prone. We could also try and use env variables (like BASIC_MEMORY_HOME if #219 gets resolved!)

Additional Context

This change would streamline workflows for users managing multiple projects and simplify onboarding for new projects by reducing manual setup.

Impact

Improves flexibility, portability, and user experience in multi-project workflows with basic-memory MCP.

[x45dev]

Bump/support for this request. I want my projects to live in Git, so the basic-memory configuration needs to be able to be supplied/overridden at a project-level, regardless of whats in ~/.basic-memory/config.json.

[phernandez]

I think this is more of a bug than a feature, FYI. The --project flag should be working, as well as the BASIC_MEMORY_HOME env var.

[x45dev]

Okay, that's good to know, thanks.

The only env cars I've seen documented are casual mentions in the Docker config examples. What others are available?

[jpmurray]

I think this is more of a bug than a feature, FYI. The --project flag should be working, as well as the BASIC_MEMORY_HOME env var.

The --project flag does work if the project was created before via cli, otherwise the server fails to start. The idea here was also to have it created automatically if it wasn't already. That way we can use uvx without resorting to also having to go in terminal to create the project.

[bdmayes]

@jpmurray I think there are actually two problems here:

1. The use of the equal sign between the project argument and the name. The command should be "args": ["basic-memory", "--project", "my-awesome-project-name", "mcp"]
2. The code is currently configured to raise a ValueError if it does not locate the project. We can change this behavior if that is the way to go, though the project add command requires two arguments, both a name a path. I'm not sure why you might want those 2 to be different though currently they can be. If we are going to let it create projects then we could default to passing that same string as both the name and path of the project.

@phernandez instead of raising a ValueError in get_project_config() (and/or we can make a call to os.path.exists() to confirm that the project is not there), what do you think about instead calling the add_project() function, and repeating the argument given to --project as both the name and the path passed?

In other words, right now, the code deliberately bails out if there is no such matching project. You can simply try it now with bm --project a-real-project mcp and it will fail. We could make it such that under the covers it detects that the project doesn't exist, and then do:

add_project("a-real-project", "a-real-project")
return ProjectConfig(name="a-real-project", home=Path("a-real-project"))

This would cause it to create a-real-project and then return its config and carry on, rather than raising the ValueError as it does now.

[phernandez]

@jope-bm is currently in the middle of un-f**cking the project config logic. Lets hear his thoughts. The --project arg is super weird in typer the say it can be used for every command, supposedly. But apparently it doesn't work. I'm for whatever makes the behavior clear and easy to understand, and simplifies the code.

[bdmayes]

It's not just typer being weird, it's the automatic creation of a non-existent project that is being requested. It's implicit project creation vs explicit creation, and I'm not sure if that is something that you want to support.

[phernandez]

@x45dev I don't quite understand what you are asking for here:

I want my projects to live in Git, so the basic-memory configuration needs to be able to be supplied/overridden at a project-level, regardless of whats in ~/.basic-memory/config.json.

Can you give an example? Are you trying to override a particular property in the config? You can do that via BASIC_MEMORY_<PROPERTYNAME>=value. This is pydantic config settings magic.

[jope-bm]

@jope-bm is currently in the middle of un-f**cking the project config logic. Lets hear his thoughts. The --project arg is super weird in typer the say it can be used for every command, supposedly. But apparently it doesn't work. I'm for whatever makes the behavior clear and easy to understand, and simplifies the code.

It's going to be a major undertaking move projects out of the config. My current plan is to create a "move project" CLI command that will take a name and path, and update the project path in the config and database. This will go along with removing BASIC_MEMORY_HOME envvar.

So to have projects live in git, you can provide a path when creating the new memory project. The create_memory_project MCP tool supports a path parameter that can be anywhere.

If you decide you want to move that BM project to a different location at a later date, we'll have a move project CLI command that will update the BM config and db, then you manually move your files to that new location.

[x45dev]

@x45dev I don't quite understand what you are asking for here:

I want my projects to live in Git, so the basic-memory configuration needs to be able to be supplied/overridden at a project-level, regardless of whats in ~/.basic-memory/config.json.

Can you give an example? Are you trying to override a particular property in the config? You can do that via BASIC_MEMORY_<PROPERTYNAME>=value. This is pydantic config settings magic.

Hello, thank you for engaging on this. I was unaware of the extent of your available env vars, so I will experiment with that too, but in the interim I'll explain what I meant.

What I was hoping for is a config loading approach based on the directory that the basic-memory process is launched from. The logic would be something like: "Check the $pwd/ and $pwd/.config/ directories for the presence of a basic-memory config file. If they exist, use those, otherwise fall back to ~/. basic-memory/".

As a side note, please support XDG_CONFIG conventions, including project-level .config/ directories (as mentioned above). User home and project directories are cluttered enough these days without adding more top-level configs per app. 🙏☺️

[phernandez]

@claude is there a pythonic way to support XDG_CONFIG? As in a lib already available?

[claude]

Claude finished @phernandez's task —— View job

---

Python Libraries for XDG Configuration Support

Todo List:

• Research available Python libraries for XDG config support
• Provide recommendations and analysis
• Suggest integration approach for basic-memory

---

Yes, there are several excellent Python libraries for XDG Base Directory specification support. Here's my analysis and recommendation:

Recommended: platformdirs

Why platformdirs is the best choice:

• Most popular: ~1.8k GitHub stars, maintained by PyPA (Python Packaging Authority)
• Cross-platform: Works on Linux, macOS, and Windows
• XDG compliant: Follows XDG spec on Unix systems
• Lightweight: ~50KB, no external dependencies
• Type hints: Full type annotations included
• Actively maintained: Regular updates and bug fixes

Installation:

uv add platformdirs

Current Basic Memory Configuration Structure

Looking at your current config.py, you're using:

• Hardcoded ~/.basic-memory directory (line 19: DATA_DIR_NAME = ".basic-memory")
• Manual Path.home() construction (line 166)
• Single directory for both config and data

Proposed XDG Integration

With platformdirs, Basic Memory would use proper XDG directories:

Type	Linux	macOS	Windows
Config	~/.config/basic-memory/	~/Library/Preferences/basic-memory/	%APPDATA%/basic-memory/
Data	~/.local/share/basic-memory/	~/Library/Application Support/basic-memory/	%LOCALAPPDATA%/basic-memory/
Cache	~/.cache/basic-memory/	~/Library/Caches/basic-memory/	%LOCALAPPDATA%/basic-memory/Cache/

Code changes needed in ConfigManager (config.py:157):

from platformdirs import user_config_dir, user_data_dir

class ConfigManager:
    def __init__(self) -> None:
        # XDG-compliant directories
        self.config_dir = Path(user_config_dir("basic-memory"))
        self.data_dir = Path(user_data_dir("basic-memory"))
        self.config_file = self.config_dir / CONFIG_FILE_NAME
        
        # Ensure directories exist
        self.config_dir.mkdir(parents=True, exist_ok=True)
        self.data_dir.mkdir(parents=True, exist_ok=True)

Update database path (config.py:112):

@property
def app_database_path(self) -> Path:
    from platformdirs import user_data_dir
    database_path = Path(user_data_dir("basic-memory")) / APP_DATABASE_NAME
    if not database_path.exists():
        database_path.parent.mkdir(parents=True, exist_ok=True)
        database_path.touch()
    return database_path

Other Libraries Considered

• appdirs: Legacy predecessor to platformdirs (not recommended)
• pyxdg: Linux-only, heavier with full XDG spec (overkill)
• xdg-base-dirs: Minimal but less mature ecosystem

Benefits for Basic Memory

1. Standards compliance: Users expect config files in ~/.config/
2. System integration: Better backup/dotfile manager support
3. Directory separation: Config, data, and cache properly separated
4. Cross-platform: Handles platform differences correctly
5. Project-level configs: Could enable the requested .config/ directory support

Migration Strategy

This would be a breaking change requiring:

1. Migration script to move existing ~/.basic-memory/ to XDG locations
2. Fallback logic to check old location if new doesn't exist
3. Clear documentation for users

Recommendation: Add platformdirs>=4.0.0 to your dependencies for robust, cross-platform XDG support that integrates seamlessly with your existing Pydantic configuration system.

---

[jpmurray]

I don't know about others, but I hate when tools go into the ~/Library. Especially config, I really love ~/.folders for that...