Basic Memory

Long-term memory as plain Markdown files you own.

Started in our test
★ 4.4K GitHub stars
15.7K downloads a week
Last commit 26 Oct 2026

At a glance

Basic Memory writes notes as ordinary Markdown in a folder on your machine (by default ~/basic-memory) and indexes the links between them. The assistant can write notes, search them and follow connections in later conversations.

Because the notes are just files, you can open them in Obsidian or any editor and edit them yourself.

Made by: Basic Machines
Licence: AGPL-3.0-or-later
Latest version: 0.24.1 (23 Oct 2026)
PyPI package: basic-memory
GitHub stars: 4.4K
Downloads: 15.7K a week
Last commit: 26 Oct 2026
Tools: 27
Runs on: Your computer

Our check: We ran this exact config on 26 Oct 2026: it started and answered with 27 tools.

What's in the pod: its tools

We found 27 tools when we started it on 26 Oct 2026. 21 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

Changes things6 tools · Can create, edit, send or delete.

Tool	What it is for
`create_memory_project`	Starts a new notes project in a folder you choose.
`delete_note`	Deletes a note.
`delete_project`	Removes a project from Basic Memory without deleting your files.
`edit_note`	Changes part of a note: append, prepend, swap a section or find and replace.
`move_note`	Moves or renames a note and keeps its links working.
`write_note`	Creates or overwrites a Markdown note with facts, tags and links to other notes.

Only reads21 tools · Looks things up and changes nothing.

Tool	What it is for
`basic_memory_diagnostics`	Reports the installed version, Python and settings, for bug reports.
`build_context`	Follows links out from a note to gather everything related, so a new chat can pick up the thread.
`cat`	Prints a note, or just a section or a range of lines from it.
`fetch`	Returns one note in the format ChatGPT's connector expects.
`find`	Lists notes by file name pattern or by frontmatter values such as status.
`grep`	Finds notes that contain given words, or that match by meaning.
`list_directory`	Lists the folders and notes inside a project.
`list_memory_projects`	Lists your notes projects and which one is the default.
`list_workspaces`	Lists cloud workspaces you can reach, for team accounts.
`ls`	Lists one level of a folder, or all projects at the top.
`man`	Looks up Basic Memory's built-in manual.
`read_content`	Reads a file exactly as stored, including images, without note processing.
`read_note`	Reads a note by title, permalink or memory:// link.
`recent_activity`	Shows what changed lately across your notes.
`schema_diff`	Spots where notes of one type have drifted from their schema.
`schema_infer`	Suggests a schema by studying existing notes of one type.
`schema_validate`	Checks notes against the schema written for their type.
`search`	Returns top matches in the format ChatGPT's connector expects.
`search_notes`	Searches notes, facts and links by keyword, meaning or both, in one project or all of them.
`tail`	Lists the most recently changed notes.
`view_note`	Reads a note and asks the client to show it as a formatted document.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

Set it up

Pick your app for the exact snippet and where it goes.

Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)

Claude Desktop

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

Where it goes: Your terminal, in the project folder

Claude Code

claude mcp add-json basic-memory '{"command":"uvx","args":["basic-memory","mcp"]}'

Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

Cursor

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

Where it goes: .vscode/mcp.json in your project

VS Code

{
  "servers": {
    "basic-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

Where it goes: ~/.codeium/windsurf/mcp_config.json

Windsurf

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Settings

Names are exactly as the project spells them. Required ones are marked.

Setting	What it does
`uvx basic-memory mcp`Config · required	The command a client runs for a local install. Notes live in ~/basic-memory unless you make other projects.`"args": ["--prerelease=allow", "basic-memory", "mcp"]`
`BASIC_MEMORY_NO_PROMOS`Environment variable	Set to 1 to hide cloud promotions and switch off telemetry.`1`
`BASIC_MEMORY_LOG_LEVEL`Environment variable	How much it logs: DEBUG, INFO, WARNING or ERROR.`DEBUG`
`BASIC_MEMORY_RERANKER_ENABLED`Environment variable	Set to true to re-rank search results with a second model for better matches.`true`
`BASIC_MEMORY_FORCE_LOCAL`Environment variable	Keep every project on local files even when cloud routing is set up.

What it can touch

It can read

Markdown notes in your Basic Memory project folders
A local search index built from them

It can change

Creates, edits, moves and deletes Markdown files in those folders
Keeps the index in sync when you edit notes by hand

Safer setup: Keep the notes folder in git or a synced drive so you can roll back any edit the AI makes.

Before you start

uv (for uvx)

If it does not work

Search misses notes you edited by hand: Run basic-memory reindex, with BASIC_MEMORY_LOG_LEVEL=DEBUG if you need to see why.
Desktop app cannot start uvx: Give the full path from which uvx in the command field, then restart the app.
Notes land in the wrong project: Ask list_memory_projects to see the default, or name the project in your request.

Peas in a pod: similar servers

How Basic Memory lines up against other knowledge and work apps servers on the shelf.

Server	Tools	Runs on	Licence	Stars
Basic Memory	27	Your computer	AGPL-3.0-or-later	4.4K
LinkedIn MCP Server	20	Your computer	Apache-2.0	4K
arXiv MCP Server	19	Your computer	Apache-2.0	3.2K
Notion	24	Your computer or hosted	MIT	4.7K
MCP Atlassian (Jira and Confluence)	98	Your computer	–	6K

Questions

Where are my notes kept?

As plain Markdown files on your disk, in ~/basic-memory by default. You can open them in Obsidian or any editor.

Is it free?

Running it locally is free and AGPL-3.0 licensed. The optional cloud version with sync and mobile access is a paid subscription.

Does it work with ChatGPT?

Yes. The search and fetch tools exist so ChatGPT's connector format works, alongside Claude, Codex, Cursor and VS Code.

What is a memory:// link?

An address for a note or a pattern of notes that build_context can follow, so the AI can load a topic and everything linked to it.

Full docs on GitHubbasicmachines-co/basic-memory

Something wrong on this page? Tell us.

More in Knowledge and work apps

LinkedIn MCP ServerRead LinkedIn profiles, companies and job posts with your own login.Started in our test★ 4K

arXiv MCP ServerSearch arXiv, download papers and read them in full.Started in our test★ 3.2K

NotionNotion's own server: search, read and update pages and databases.Started in our test★ 4.7K

MCP Atlassian (Jira and Confluence)Jira issues and Confluence pages, Cloud or self-hosted.Started in our test★ 6K