basic-memory-mcp
This server provides a persistent, Markdown-backed notebook for AI models, enabling them to manage a searchable knowledge base with full topic lifecycle control.
Discover & search topics: Browse topics with optional filtering by tag, keyword query (case-insensitive AND search across ID, title, tags, and body), phrase matching, and result limits; optionally include expired topics.
Read topics: Retrieve full Markdown content and YAML frontmatter of any topic by its slash-path ID (expired topics are still readable).
Write topics: Create new or completely replace existing topics with Markdown content. Supports optional titles, tags, and retention/expiry (permanent, session/today, week, month, or a specific ISO‑8601 date). Parent folders are auto‑created.
Edit topics: Perform exact string replacements within a topic’s content—replace first occurrence or all occurrences.
Append to topics: Add text to an existing topic without overwriting, optionally under a specified
##heading; can extend (but never shorten) expiry.Rename / move topics: Move a topic to a new ID and automatically rewrite
[[wiki-links]]pointing to it across all topics.Delete topics: Soft‑delete a topic by moving it to a timestamped
.trash/folder (manually recoverable); empty parent folders are pruned automatically.Sweep expired topics: List or soft‑delete topics whose retention has passed, with a dry‑run mode to preview changes.
Track relationships: Report outbound and inbound wiki‑link connections for any topic.
Read‑only mode: Optionally restrict to discovery and reading only.
Multi‑tenancy (optional): Namespace topics per authenticated user in ATLAS deployments.
Git‑friendly storage: All data is stored as UTF‑8 Markdown files with YAML frontmatter, editable with any text editor and easily versioned.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@basic-memory-mcp Create a note about the Atlas ports refactor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_userparameter exists anywhere, and behavior is byte-identical to a single-user server.On: every tool grows a trailing
_atlas_user: str | None = Noneparameter ("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, anddiscover_topicsare scoped to the calling tenant.memory://resources are disabled in this mode (resources get no_atlas_userinjection, so they cannot be scoped to the caller).Accepted slug collision:
a.b@c.danda_b@c_dsanitize 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 pytestAvailable Tools
9 toolsappendADestructive
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
deleteADestructive
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_topicsARead-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
editADestructive
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
readARead-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
renameADestructive
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
sweepADestructive
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
writeADestructive
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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
An MCP server that used to create notes
Related MCP Servers
- AlicenseAqualityDmaintenanceA simple note-taking MCP server for recording and managing notes with AI models.429 npm37GPL 2.0
- FlicenseAqualityBmaintenanceA local MCP server for managing Markdown notes, enabling create, list, read, search, summarize, and delete operations through natural language.61-
- AlicenseNot gradedqualityCmaintenanceA local-first MCP server that gives AI assistants long-term memory by storing, searching, and recalling notes as Markdown files on your machine.4 npmMIT
- AlicenseAqualityDmaintenanceAn 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.5MIT