basic-memory-mcp

An MCP server that gives a model a persistent notebook backed by a folder of Markdown files.

Tools

• discover_topics(query=None, tag=None, limit=50) — list topics, optionally filtered.

• read(topic_id) — return the full Markdown file including frontmatter.

• write(topic_id, content, title=None, tags=[]) — create or replace a topic.

• edit(topic_id, old, new, replace_all=False) — exact string replacement.

• delete(topic_id) — soft-delete into <root>/.trash/<timestamp>/....

Topic ids are slash-paths relative to --root without .md, e.g. projects/atlas-ports.

Related MCP server: Local Knowledge Desk

Usage

# stdio (default)
basic-memory-mcp --stdio --root ~/ATLAS-GROUP/basic-memory/memory

# HTTP
basic-memory-mcp --http --host 127.0.0.1 --port 8101 --root ...

Set BASIC_MEMORY_READ_ONLY=1 or --read-only to expose only discover_topics and read. Set BASIC_MEMORY_HARD_DELETE=1 or --hard-delete to unlink files instead of moving them (only for throwaway/test roots).

Multi-tenancy (ATLAS deployments only, off by default)

--multi-tenant (or BASIC_MEMORY_MULTI_TENANT=1) namespaces every topic per authenticated user, for the ATLAS deployment where the backend injects the caller's email into tool calls.

• Off (default): tool schemas are exactly as above — no _atlas_user parameter exists anywhere, and behavior is byte-identical to a single-user server.

• On: every tool grows a trailing _atlas_user: str | None = None parameter ("injected by the Atlas backend; do not supply"). ATLAS fills it from the authenticated session and strips anything the model supplies, so the LLM cannot impersonate another user. A call arriving without it is refused with a clear error — never silently mapped to a shared/default tenant.

• The email is sanitized to a filesystem-safe slug (lowercase, @ and . → _, must match [a-z0-9_-]+ afterward): garland3@gmail.com → garland3_gmail_com/. All topic ids then resolve under <root>/<slug>/, and the usual path-escape rules apply after prepending, so one tenant can never name another tenant's files.

• Each tenant gets their own .trash/; sweep, catalog priming, and discover_topics are scoped to the calling tenant. memory:// resources are disabled in this mode (resources get no _atlas_user injection, so they cannot be scoped to the caller).

• Accepted slug collision: a.b@c.d and a_b@c_d sanitize to the same slug and share a folder. Emails are the trust boundary and ATLAS authenticates them, so this requires two authenticated users with pathological addresses.

• This is namespacing for the trusted-ATLAS case, not security against a hostile client — stdio gives whoever spawns the process the whole folder anyway.

• No migration tool. Turning the flag on over an existing flat root leaves old topics invisible; move them under the tenant folder with a one-time mv <root>/projects <root>/<slug>/ (etc.) if you enable it later.

Storage

Files are UTF-8 Markdown with YAML frontmatter; only .md files are visible. The server manages created and updated; the model supplies title and tags. The memory folder is plain files, so git and ordinary editors work.

Development

uv sync
uv run pytest