basic-memory MCP in mcp.json: why does --project make the server fail to start?

Question

I'm configuring the basic-memory MCP server (run via uvx) in mcp.json for Roo Code + VS Code, and I want per-project memory roots instead of one global config. When I pass --project in the args, the server fails to start if that project doesn't exist yet. What is the correct args syntax, and do I need to create the project first? The thread doesn't state a basic-memory version or OS.

Originally asked on GitHub: https://github.com/basicmachines-co/basic-memory/issues/220

AgentArmorHQ team · Accepted Answer

**Status: explained.** The issue is closed as completed, and the thread shows the correct syntax and the current limits; it does not show automatic project creation shipping.

Two things caused failures with the JSON approach:

1. The equals-sign form (`--project=project`) is not the right syntax. A collaborator says the args should be space-separated:

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "--project", "my-awesome-project-name", "mcp"]
    }
  }
}
```

2. `--project` only works for a project that already exists. If the project can't be found, the code raises a `ValueError` and the server won't start (confirmed by a user who hit it, and by a collaborator describing the code). Create the project first via the CLI — `project add` takes both a name and a path. So far there's no automatic creation in the thread.

Alternatives suggested by a maintainer and a contributor:

- Override config properties with `BASIC_MEMORY_<PROPERTYNAME>=value` environment variables (pydantic config settings behavior) — suggested by a maintainer, not verified in the thread.
- The `create_memory_project` MCP tool accepts a `path` parameter, so the memory root can live anywhere, including a Git repo.
- `BASIC_MEMORY_HOME` is planned for removal, with a future `move project` CLI command to relocate a project and update the config/db.

General advice: if you put env vars in a committed `mcp.json`, don't put credentials in there.

AgentArmorHQ team · Answer

**What @bdmayes tried on GitHub** (Outcome unclear)

A collaborator proposed the space-separated form `--project my-awesome-project-name` in the args array and suggested auto-creating a missing project by calling add_project with the same string as name and path. The thread doesn't confirm this was implemented.

Source: https://github.com/basicmachines-co/basic-memory/issues/220#issuecomment-3105316475

AgentArmorHQ team · Answer

**What @jpmurray tried on GitHub** (Partly worked)

A user confirmed `--project` works only if the project was created beforehand through the CLI; otherwise the server fails to start. They wanted automatic creation so a uvx setup works without a terminal step.

Source: https://github.com/basicmachines-co/basic-memory/issues/220#issuecomment-3059537346

AgentArmorHQ team · Answer

**What @phernandez tried on GitHub** (Outcome unclear)

A maintainer suggested overriding config properties with `BASIC_MEMORY_<PROPERTYNAME>=value` environment variables instead of per-project mcp.json settings. No one in the thread reported testing this.

Source: https://github.com/basicmachines-co/basic-memory/issues/220#issuecomment-3105455498

basic-memory MCP in mcp.json: why does --project make the server fail to start?

4 answers

Add your answer or comment

basic-memory MCP in mcp.json: why does --project make the server fail to start?

4 answers

Add your answer or comment

Related questions