A personal knowledge system where your AI assistant can read and write your notes

How the system fits together

Obsidian folder → Basic Memory project pointing to the same folder → Claude Desktop (MCP client) → writing and searching notes → answers that cite the note by name.

• 
  Obsidian required

  Keeps and displays your notes as Markdown files

  Tool guide

• 
  Basic Memory required

  Indexes your notes and gives the assistant search, read and write tools over MCP

  About the tool

• U
  uv required

  The Python tool manager that installs Basic Memory

  Official site

• 
  Claude Desktop required

  The MCP client that uses Basic Memory's tools

  Alternative: If you use another MCP client (e.g., Claude Code, Codex); its configuration is on the vendor's integrations page

  Tool guide

• 
  Gemini Notebook optional

  Source-grounded work with selected documents (alternative path)

  Alternative: If you want to review a set of documents with citations

  Tool guide

Before you start

Step-by-step setup

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/9 steps.

1. Step 1 · In an app

   Choose an Obsidian folder (vault) for your notes

   I finished this step

   What for: Keep your notes in one folder; in a later step the assistant will connect to the same folder.

   1. Download and install Obsidian from the official site. The official site says basic use is free and needs no account.
   2. If you already have a folder of Markdown notes, choose it with the Open button to the right of 'Open folder as vault' on Obsidian's start screen. Otherwise, create a new vault with Create on the 'Create new vault' row and note where it is.
   3. Write down the full path of this folder; you'll give it to Basic Memory in step 4.

   How you know it worked

   • Obsidian opens the folder you chose as a vault and lists your notes.
   • You know the full path of the folder.
   If you get stuck: problems specific to this step

   • Obsidian shows a blank screen instead of a vault
     On the start screen, point to your existing folder with the Open button to the right of 'Open folder as vault', or create a new vault with Create on the 'Create new vault' row.
   Based on: Obsidian pricing page, Obsidian help: creating a vault, Basic Memory docs: Obsidian integration
2. Step 2 · In the terminal

   Install uv

   I finished this step

   What for: Basic Memory is installed with uv, so you need uv first.

   1. uv's installation page lists methods by operating system. The WinGet line for Windows: winget install --id=astral-sh.uv -e. The Homebrew line for macOS: brew install uv (if Homebrew isn't installed, first follow the installation on brew.sh).
   2. The uv documentation gives these two lines without a version, so they're not in the command list; check the version after installing with uv --version. The first method on the uv page is a script that downloads and runs itself; this guide doesn't recommend it, because it runs code you haven't seen (DijiKoçum's preference).
   3. After installing, close and reopen the terminal so the command can be found.
   Windows · macOSFolder: Any folder

   › uv --versionCopy

   How you know it worked

   • The terminal prints a uv version number.
   If you get stuck: problems specific to this step

   • uv command not found
     Close and reopen the terminal. If it's still missing, make sure the package manager finished the installation; go back to the method on the uv page.
   Based on: uv docs: installationGet help with this step →
3. Step 3 · In the terminal

   Install Basic Memory pinned to a version

   I finished this step

   What for: Put the program that indexes your notes and gives the assistant tools on your computer.

   1. Run the first command below. The vendor's README says the --prerelease=allow flag is required for this release series: one of Basic Memory's dependencies is a pre-release. According to the README, without the flag uv may fall back to an older version; don't skip the flag.
   2. The second command adds the folder where uv installs programs to your terminal's PATH. According to the uv documentation, this folder must be on the PATH. Then close and reopen the terminal and check the installation with the version command.
   3. By default Basic Memory sends anonymous usage telemetry. According to the vendor's page, note content, file names/paths and your search queries are not collected. If you don't want it, turn it off with the last command.
   Windows · macOSFolder: Any folder

   › uv tool install basic-memory==0.23.2 --prerelease=allowCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOSFolder: Any folder

   › uv tool update-shellCopy

   Windows · macOSFolder: Any folder

   › basic-memory --versionCopy

   Windows · macOSFolder: Any folder

   › basic-memory telemetry disableCopy

   How you know it worked

   • The version command prints 0.23.2 (the package was released on PyPI on 2026-08-25).
   If you get stuck: problems specific to this step

   • The vendor's documentation site shows `uv tool install basic-memory` without the flag, and the command installs an older version
     The README treats the flag as required; the documentation site doesn't include it. If the version command doesn't show 0.23.2, reinstall with the pinned command in this guide.
   • Incompatible Python version error
     Basic Memory requires Python 3.12 or later (PyPI listing). If uv can't find a suitable Python, see the Python installation instructions in the uv documentation.
   • The basic-memory command isn't found in the terminal
     Run uv tool update-shell and reopen the terminal. uv's tool folder is $HOME/.local/bin on macOS and %USERPROFILE%\.local\bin on Windows; check that this folder is on the PATH.
   Based on: Basic Memory GitHub README (installation, local/cloud, pricing), Basic Memory PyPI listing (version, Python requirement), Basic Memory docs: local quick start, uv docs: tools (executable folder, update-shell), Basic Memory: telemetry pageGet help with this step →
4. Step 4 · In the terminal

   Point the Basic Memory project to your Obsidian folder

   I finished this step

   What for: Notes the assistant writes should land in the folder Obsidian sees.

   1. Replace the path in the first command below with your vault path from step 1. 'mynotes' is the project name; you can use any name you like.
   2. The second command makes this project the default. The vendor says that when you change the default from the command line, new notes are written to the chosen folder after Claude Desktop is restarted.
   WindowsFolder: Any folder

   › basic-memory project add mynotes "C:\Users\YOURNAME\Documents\MyNotes"Copy

   macOSFolder: Any folder

   › basic-memory project add mynotes ~/Documents/MyNotesCopy

   Windows · macOSFolder: Any folder

   › basic-memory project default mynotesCopy

   Windows · macOSFolder: Any folder

   › bm project listCopy

   How you know it worked

   • The project commands finish without errors.
   • The project list command shows the mynotes project and its folder path.
   If you get stuck: problems specific to this step

   • Notes are written to the ~/basic-memory folder instead of the Obsidian folder
     The default project is still 'main'. Run the default command, then fully quit and reopen Claude Desktop. The vendor says default notes are kept in the main project under ~/basic-memory.
   Based on: Basic Memory docs: projects and where notes are stored, Basic Memory docs: Obsidian integration, Basic Memory docs: CLI basicsGet help with this step →
5. Step 5 · In an app

   Add Basic Memory to Claude Desktop as an MCP server

   I finished this step

   What for: So Claude can use the tools for searching and writing your notes.

   1. First, know the limit: this connection works only in the Claude Desktop app; it can't be used on claude.ai in the browser or in Cowork. On a Team/Enterprise account, the administrator may have turned off adding local servers; if Settings > Developer is missing or adding doesn't work, ask your administrator.
   2. In Claude Desktop, open the claude_desktop_config.json file with Settings > Developer > Edit Config. According to the MCP documentation, it is under %APPDATA%\Claude\ on Windows and under ~/Library/Application Support/Claude/ on macOS.
   3. On Windows, the packaged (MSIX) version installed from claude.ai/download may read the file from %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\; this isn't in the official documentation, it comes from an open GitHub issue (non-official source).
   4. First find the full path: in the terminal, uv tool dir --bin shows uv's tool folder regardless of PATH; on macOS you can also use which basic-memory, and in Windows PowerShell Get-Command basic-memory. Edit the example below accordingly (replace YOURNAME with your own user name; on Windows, backslashes are doubled inside JSON).
   5. Add the example to the file (if you have other servers, put it inside the existing mcpServers). The vendor's documentation site shows the uvx format for Claude Desktop; because uvx doesn't pin the version and the README treats the pre-release flag as required, this guide uses the full path of the installed command.
   6. Fully quit and reopen Claude Desktop. This connection gives Claude read and write access to the notes in the folder you chose; the MCP documentation says to grant access only to folders you're comfortable with Claude reading and modifying.
   Windows · macOSFolder: Any folder

   › uv tool dir --binCopy

   claude_desktop_config.json (Windows) · jsonCopy

   {
     "mcpServers": {
       "basic-memory": {
         "command": "C:\\Users\\YOURNAME\\.local\\bin\\basic-memory.exe",
         "args": [
           "mcp"
         ]
       }
     }
   }

   Based on the configuration on the vendor's local installation page: the vendor shows this format for Homebrew, and the uvx format for Claude Desktop; why the full path is used here is explained in the step above. The name basic-memory.exe isn't written in any documentation; it is the usual form on Windows because uv copies tool executables; check the file name with the command below. The folder is the Windows executable folder from the uv documentation (it may differ if XDG_BIN_HOME is set; uv tool dir --bin gives the correct one).

   claude_desktop_config.json (macOS) · jsonCopy

   {
     "mcpServers": {
       "basic-memory": {
         "command": "/Users/YOURNAME/.local/bin/basic-memory",
         "args": [
           "mcp"
         ]
       }
     }
   }

   The macOS version of the same example; the folder is the Unix executable folder from the uv documentation ($HOME/.local/bin, different if XDG_BIN_HOME is set). If the file already has other servers, don't overwrite it; add this inside mcpServers.

   How you know it worked

   • After Claude Desktop restarts, basic-memory shows as running on the Settings > Developer page; Basic Memory's tools are listed in the + / tools menu in the chat box (the menu name may vary by version: the MCP documentation says 'Add files, connectors, and more', the Basic Memory documentation says 'search and tools menu').
   If you get stuck: problems specific to this step

   • Basic Memory isn't in the tools menu, doesn't appear on the Developer page, or there's an ENOENT error
     There are two possible causes. (1) Claude Desktop can't find the command: for ENOENT the vendor says to give the full path; check the path, that YOURNAME is replaced with your own user name, and the JSON syntax. (2) Only in the Windows packaged (MSIX) version: the app may read %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json while Edit Config opens a different file; the two files don't sync. Add the same JSON to this file too (non-official source: open GitHub issue).
   • Settings > Developer is missing or the local server can't be added
     On a work or school (Team, Enterprise) computer, the administrator may have turned off local MCP servers through device policy (GPO/MDM; isLocalDevMcpEnabled); the setting is on by default. Ask your administrator. Which plans include it is not stated in Anthropic's documentation.
   • Where is the config file on Linux
     This guide doesn't cover Linux: the MCP documentation gives only the macOS and Windows paths. The Basic Memory documentation lists the Linux path separately; check there.
   Based on: Basic Memory docs: local installation and connecting an MCP client, Basic Memory docs: Claude Desktop integration, MCP docs: connecting a local MCP server to Claude Desktop, Anthropic support: custom connectors; local servers with a config file are a separate mechanism, Anthropic support: Claude Desktop enterprise configuration (device policy: MDM/GPO), uv docs: storage directories (executable folder path), uv docs: command-line reference (uv tool dir --bin), NON-OFFICIAL SOURCE: anthropics/claude-code issue #26073 (Windows MSIX config path bug, open)Get help with this step →
6. Step 6 · In a coding agent

   Have the assistant write a note, then search for it

   I finished this step

   What for: See that the note the assistant creates really appears in your folder.

   !You check this step yourself; the system should not move past it without your approval.

   1. In Claude Desktop, type: 'List my Basic Memory projects.' Wait for the assistant to show the mynotes project; the path may not appear. The bm project list command from the previous step gives the definitive check.
   2. Then: 'Create a note called My First Note; explain in two sentences what Basic Memory is for.' Read Claude's tool call approval and approve it.
   3. Open the vault in Obsidian and check that the file My First Note.md is there. Read what the assistant wrote; if it's wrong, fix it in Obsidian.

   How you know it worked

   • The assistant mentions mynotes in the project list (the folder path may not appear).
   • The file My First Note.md appears in your Obsidian vault.
   If you get stuck: problems specific to this step

   • The note was created somewhere other than the Obsidian folder
     The assistant may have chosen a different project. Say 'write to the mynotes project' in your request, and set the default project as in step 4.
   • The new note doesn't appear in Obsidian
     Check the status with basic-memory status; if the index is stale, run the bm reindex command the vendor documents. Reopen Obsidian with the vault refreshed.
   Based on: Basic Memory docs: Claude Desktop integration, Basic Memory docs: Obsidian integration, Basic Memory docs: local quick startGet help with this step →
7. Step 7 · In a coding agent

   Ask for an answer that cites your notes, edit the note and ask again

   I finished this step

   What for: See that search finds the edited note, and see the source of the answer.

   !You check this step yourself; the system should not move past it without your approval.

   1. Ask: 'What do my notes say about Basic Memory? Name the note your answer came from.' Compare the note name in the answer with the file in your own folder.
   2. In Obsidian, add a sentence to My First Note.md (e.g., ‘I edited this note by hand.’) and save.
   3. Ask the same question again. If the answer doesn't include the new sentence, check the status with basic-memory status and, if needed, refresh the index with bm reindex.

   How you know it worked

   • The answer names a note or a memory:// address, and that note exists in your folder.
   • The sentence you added by hand appears in the second answer.
   If you get stuck: problems specific to this step

   • The assistant doesn't name the source note in its answer
     Add 'name the notes your answer is based on' to your request. Basic Memory gives every note a memory:// address; ask the assistant for that address too.
   Based on: Basic Memory docs: memory:// addresses, Basic Memory docs: local MCP tools, Basic Memory docs: Claude Desktop integrationGet help with this step →
8. Step 8 · In the browser

   Alternative path: choose which files to use as sources in Notebook

   I finished this step

   What for: Add the documents you want to work with in Notebook as the right type.

   1. Create a new notebook in Gemini Notebook and sign in with your Google account. Before access, Google requires your age to be verified on the account and your country to be supported; Google's help page doesn't give the country list there, so check on Google's own page whether it opens for your account. On the Standard plan you can add up to 50 sources per notebook; higher plans have higher limits.
   2. Because Obsidian notes are Markdown files, Notebook can upload Markdown (md) files directly. The file you upload becomes a copy inside the notebook.
   3. Google's announcement mentions automatic Drive sync for Google Docs, Sheets and Slides. Automatic sync for a .md or .pdf file you put in Drive is not documented, so keep any document you want synced as a Google Doc. There's also no method that automatically connects your Obsidian folder to Notebook.

   How you know it worked

   • The files you chose appear in the notebook's source list.
   If you get stuck: problems specific to this step

   • You hit the source limit
     The Standard plan has a limit of 50 sources. Work with fewer but larger documents, or check the higher plans' limits on Google's plans page.
   Based on: Gemini Notebook help: adding and updating sources, Gemini Notebook help: plans and source limits, Google Workspace Updates: automatic Drive sync (May 26, 2026), Gemini Notebook help: access issues (age, country/region)
9. Step 9 · In the browser

   Alternative path: know how updates work for each source type

   I finished this step

   What for: Tell apart which sources update on their own and which ones you need to refresh.

   !You check this step yourself; the system should not move past it without your approval.

   1. Sources imported from Drive: Google's help page says they update automatically and sync every few minutes; Google's announcement mentions this for Google Docs, Sheets and Slides (it isn't documented for .md/.pdf in Drive). If needed, open the source and sync it manually with 'Click to sync with Google Drive'.
   2. If the file is deleted in Drive or you lose access to it, the source becomes inaccessible. Notebook can't delete or edit the original file in Drive.
   3. Markdown, text or PDF uploaded as a local file: Google's help page describes a source as 'a copy or an auto-synced version' and describes automatic sync only for Drive. Updates for local files aren't described; when the file changes, upload the new version again.
   4. Web link: Google says only the page's text is taken as the source, and doesn't say whether it is refreshed later. If the page has changed, add the link again.

   How you know it worked

   • You can tell each source's type and who needs to do what to keep it up to date.
   If you get stuck: problems specific to this step

   • Information you corrected in Drive still looks old in the notebook
     Google says the source syncs every few minutes. Open the notebook and wait, or use the manual sync button on the source.
   • You updated the Markdown file you uploaded, but the notebook is out of date
     Automatic updates for local file sources aren't documented. Remove the old source and upload the new version.
   Based on: Gemini Notebook help: adding and updating sources, Google Workspace Updates: automatic Drive sync (May 26, 2026)

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

• No costObsidian

  The official site says basic use is free and needs no account. The commercial license recommended for organizations using it for work is optional (USD 50 per user per year on the official site); Sync and Publish are separate paid add-ons. (October 17, 2026) source

• No costBasic Memory local installation

  The README shows the local installation as free and licensed under AGPL-3.0. It doesn't require a cloud account. source

• No costPrivacy: Basic Memory telemetry

  Not a fee but a data item: by default the local installation sends anonymous usage telemetry; the command to turn it off is basic-memory telemetry disable. Note content isn't collected, but the notes the assistant reads go to the model. source

• SubscriptionBasic Memory Cloud (optional)

  The README mentions a price of USD 15 per month and a 7-day trial; prices and terms may change on the vendor's page. It isn't needed for the local steps in this guide. (October 17, 2026) source

• SubscriptionClaude Desktop / model usage

  Your use of the assistant depends on your Claude account's plan; plans and prices are on Anthropic's plans page. Notes kept in local files are a separate matter from the content sent to the model. source

• SubscriptionGemini Notebook (alternative path)

  The Standard plan lists free sign-up with a Gmail account; source limits and quotas vary by plan. For country/region and age requirements, see Google's access page. source

• Setup serviceSetup service

  If you like, we can handle the setup and your note structure for you; scope is agreed on a call. source

Sources

• Basic Memory GitHub README (installation, local/cloud, pricing) · Source code · read October 17, 2026
• Basic Memory PyPI listing (version, Python requirement) · Vendor page · read October 17, 2026
• Basic Memory docs: local quick start · Official documentation · read October 17, 2026
• Basic Memory docs: local installation and connecting an MCP client · Official documentation · read October 17, 2026
• Basic Memory docs: projects and where notes are stored · Official documentation · read October 17, 2026
• Basic Memory docs: Obsidian integration · Official documentation · read October 17, 2026
• Basic Memory docs: Claude Desktop integration · Official documentation · read October 17, 2026
• Basic Memory docs: memory:// addresses · Official documentation · read October 17, 2026
• Basic Memory docs: local MCP tools · Official documentation · read October 17, 2026
• MCP docs: connecting a local MCP server to Claude Desktop · Official documentation · read October 17, 2026
• uv docs: installation · Official documentation · read October 17, 2026
• Obsidian pricing page · Vendor page · read October 17, 2026
• Gemini Notebook help: adding and updating sources · Help center · read October 17, 2026
• Gemini Notebook help: plans and source limits · Help center · read October 17, 2026
• Google Workspace Updates: automatic Drive sync (May 26, 2026) · Vendor page · read October 17, 2026
• Anthropic support: custom connectors; local servers with a config file are a separate mechanism · Help center · read October 17, 2026
• Anthropic support: Claude Desktop enterprise configuration (device policy: MDM/GPO) · Help center · read October 17, 2026
• Anthropic plans and pricing page · Vendor page · read October 17, 2026
• uv docs: tools (executable folder, update-shell) · Official documentation · read October 17, 2026
• uv docs: storage directories (executable folder path) · Official documentation · read October 17, 2026
• Obsidian help: creating a vault · Official documentation · read October 17, 2026
• Google blog: NotebookLM is now Gemini Notebook (July 16, 2026) · Vendor page · read October 17, 2026
• Basic Memory docs: CLI basics · Official documentation · read October 17, 2026
• Basic Memory: telemetry page · Vendor page · read October 17, 2026
• NON-OFFICIAL SOURCE: anthropics/claude-code issue #26073 (Windows MSIX config path bug, open) · Source code · read October 17, 2026
• uv docs: command-line reference (uv tool dir --bin) · Official documentation · read October 17, 2026
• Gemini Notebook help: access issues (age, country/region) · Help center · read October 17, 2026