Skip to main content
Glama

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

Available Tools

9 tools
appendA
Destructive

Append text to an existing topic without rewriting the whole body.

Inserts with exactly one blank line between the old body and the new text. If heading is supplied, appends under an existing ## heading or creates it at the end. Fails if the topic does not exist. Bumps the 'updated' timestamp. A retention argument only extends the current expiry; it never shortens it.

Inputs: text (required), topic_id (required), heading, retention. Returns: result

deleteA
Destructive

Soft-delete a topic, moving it to /.trash//.md.

Returns the trash path so it can be manually restored. Parent folders are pruned if empty. Topics are never unlinked.

Inputs: topic_id (required). Returns: result

discover_topicsA
Read-only

List available topics. Call this before read/write/edit/delete/append/rename/sweep.

Returns a JSON list of {id, title, tags, updated, size, snippet, outbound_links, expires, match_reason}, newest first. With a query, snippets are centered on the first body match. Expired topics are hidden by default; pass include_expired=true to reveal them, marked with "expired": true. Reports when results are truncated by limit or when expired topics were hidden.

Inputs: tag, limit, query, include_expired. Returns: result

editA
Destructive

Exact-string replacement inside an existing topic, like the Claude Code Edit tool.

Fails if the topic does not exist. Fails if 'old' is not found. Fails if 'old' appears more than once and replace_all is false. Bumps the 'updated' timestamp. To change title, tags, or expiry, use write instead.

Inputs: new (required), old (required), topic_id (required), replace_all. Returns: result

readA
Read-only

Read a single topic in full, including its YAML frontmatter.

Errors with a clear message if the topic does not exist; call discover_topics first. Expired topics are still readable by id.

Inputs: topic_id (required). Returns: result

renameA
Destructive

Move a topic and rewrite wiki links that pointed to it.

Also rewrites prefix links: renaming scratch/ → archive/scratch/ fixes [[scratch/x]] links. Refuses if new_id already exists. Returns the count of rewritten links so the model knows the blast radius.

Inputs: new_id (required), old_id (required). Returns: result

sweepA
Destructive

List or soft-delete topics whose expiry has passed.

dry_run=true returns the list without changing anything; the model should review it and then call sweep(dry_run=false) to move the topics into .trash.

Inputs: dry_run. Returns: result

writeA
Destructive

Create or replace a topic. Overwrites existing topics without asking; use edit for targeted changes.

Parent folders are created implicitly. Returns the resolved id and whether the topic was created or replaced. Rejects content over approximately 1 MB; split large memories into multiple topics. Retention controls expiry: permanent means never; session/today means 24 hours; week means 7 days; month means 30 days.

Inputs: content (required), topic_id (required), tags, title, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: discover_topics for listing, read for full content, related for links, write for full replacement, edit for targeted string changes, append for adding text, rename for moving, delete for trash, and sweep for expired cleanup. No two tools overlap in function.

    Naming Consistency3/5

    Most tools use single-word verbs (read, write, edit, append, rename, delete, sweep), but discover_topics introduces an underscore and related is an adjective rather than a verb. This mixed convention breaks the otherwise predictable verb-only pattern.

    Tool Count5/5

    The 9 tools are well-scoped for a personal memory server, covering the full lifecycle of topics from discovery to deletion without unnecessary redundancy. Each tool addresses a distinct need and the count feels appropriate.

    Completeness5/5

    The tool surface is comprehensive: create, read, update (via edit, append, rename), delete, list, relationship traversal, and expiration cleanup are all covered. There are no discernible gaps for the stated purpose of managing topics in a knowledge base.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A local-first MCP server that gives AI assistants long-term memory by storing, searching, and recalling notes as Markdown files on your machine.
      4 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that stores notes as Markdown files on your machine, enabling you to save, search, and manage notes through natural language with Claude Code or Claude Desktop.
      5
      MIT