Basic Memory

Local-first knowledge base over MCP: your agent reads and writes plain Markdown notes on your own disk, so context carries across chats. Optional paid cloud sync.

💭 Memory & reasoning4,266Updated 2026-10-16By Basic MachinesLicense: AGPL-3.0Auth: Not checked yetGitHub ↗

Found viaWebOfficial MCP Registry: io.github.basicmachines-co/basic-memory GitHubGitHub: basicmachines-co/basic-memory (★ 4,266 on 2026-10-18) Makerbasicmemory.com

Test results

Last passed 2026-10-22

Claude CodePassed2026-10-21 · install, connect, tools, agent taskTested with Claude Code 2.1.296 · basic-memory 0.23.2 · connected in 4.7s

CursorPassed2026-10-21 · install, connect, tools, agent taskTested with Cursor CLI 2026.10.19-6bbf2c4 · basic-memory 0.23.2 · connected in 4.1s

Claude DesktopNot tested yet—

ChatGPT (Codex)Passed2026-10-22 · install, connect, tools, agent taskTested with Codex CLI 0.162.0-alpha.17.2 · basic-memory 0.23.2 · connect time not recorded

Server package tested: basic-memory 0.23.2 (uv, Python 3.12.15; resolved 2026-10-22)

Direct and key dependencies as resolved: aiofiles 25.1.0 · aiosqlite 0.22.1 · alembic 1.20.1 · anyio 4.15.1 · asyncpg 0.32.0 · dateparser 1.4.3 · fastapi 0.160.0 · fastembed 0.9.0 · fastmcp 4.0.0b1 · filelock 4.2.4 · greenlet 3.5.6 · httpx 0.28.1 · litellm 1.91.5 · logfire 6.0.0b8 · loguru 0.7.3 · markdown-it-py 4.2.0 · mcp 2.3.0 · mdformat 1.0.0 · mdformat-gfm 1.0.0 · mdformat_frontmatter 2.1.2 · nest-asyncio 1.6.0 · openai 2.54.0 · pillow 12.3.0 · psutil 7.2.2 · psycopg 3.3.1 · pybars3 0.9.7 · pydantic 2.14.1 · pydantic-settings 2.16.1 · pydantic_core 2.50.1 · PyJWT 2.15.1 · pyright 1.1.414 · pytest-aio 2.1.7 · pytest-asyncio 1.4.0 · python-dotenv 1.2.4 · python-frontmatter 1.3.0 · PyYAML 6.0.3 · rich 15.0.0 · sniffio 1.3.1 · SQLAlchemy 2.1.6 · sqlite-vec 0.1.10a4 · sse-starlette 3.5.0 · starlette 1.9.0 · typer 0.27.3 · typing_extensions 4.16.0 · Unidecode 1.4.0 · uvicorn 0.54.0 · uvloop 0.23.0 · watchfiles 1.3.0

All 171 resolved dependencies

agent-detector==2.0.0
aiofile==3.12.3
aiofiles==25.1.0
aiohappyeyeballs==2.7.1
aiohttp==3.14.5
aiosignal==1.4.0
aiosqlite==0.22.1
alembic==1.20.1
annotated-doc==0.0.5
annotated-types==0.8.0
anyio==4.15.1
asyncpg==0.32.0
attrs==26.1.0
Authlib==1.9.1
beartype==0.23.1
cachetools==7.2.4
caio==0.12.9
certifi==2026.10.19
cffi==2.1.1
charset-normalizer==3.5.2
click==8.5.0
cryptography==50.0.2
cyclopts==5.3.0
dateparser==1.4.3
detect-installer==0.2.1
distro==1.9.0
dnspython==2.9.0
docstring_parser==0.18.0
email-validator==2.3.0
exceptiongroup==1.3.1
executing==2.3.0
fastapi==0.160.0
fastapi-cli==0.0.32
fastapi-cloud-cli==0.26.0
fastar==0.12.0
fastembed==0.9.0
fastmcp==4.0.0b1
fastmcp-slim==4.0.0b1
fastuuid==0.14.0
filelock==4.2.4
flatbuffers==25.12.19
frozenlist==1.8.0
fsspec==2026.9.0
googleapis-common-protos==1.75.5
greenlet==3.5.6
griffelib==2.4.1
h11==0.16.0
hf-xet==1.8.0.dev0
httpcore==1.0.9
httpcore2==2.16.0
httptools==0.9.0
httpx==0.28.1
httpx2==2.16.0
huggingface_hub==1.33.0
idna==3.20
importlib_metadata==8.9.0
iniconfig==2.3.1
jaraco.classes==3.4.0
jaraco.context==6.1.2
jaraco.functools==4.6.0
jeepney==0.9.0
Jinja2==3.1.6
jiter==0.17.0
joserfc==1.7.7
jsonref==1.1.0
jsonschema==4.26.0
jsonschema-path==0.5.0
jsonschema-specifications==2025.9.1
keyring==25.7.0
litellm==1.91.5
logfire==6.0.0b8
logfire-cli==0.1.14
logfire-sdk==6.0.0b8
loguru==0.7.3
Mako==1.4.3
markdown-it-py==4.2.0
MarkupSafe==3.0.4
mcp==2.3.0
mcp-types==2.3.0
mdformat==1.0.0
mdformat-gfm==1.0.0
mdformat_frontmatter==2.1.2
mdit-py-plugins==0.6.1
mdurl==0.1.2
mmh3==5.3.1
more-itertools==11.2.1
multidict==7.1.0
nest-asyncio==1.6.0
nodeenv==1.11.0
numpy==2.5.4
onnxruntime==1.31.0
openai==2.54.0
openapi-pydantic==0.6.0
opentelemetry-api==1.45.1
opentelemetry-exporter-http-transport==0.66b1
opentelemetry-exporter-otlp-common==0.66b1
opentelemetry-exporter-otlp-proto-common==1.45.1
opentelemetry-exporter-otlp-proto-http==1.45.1
opentelemetry-instrumentation==0.66b1
opentelemetry-proto==1.45.1
opentelemetry-sdk==1.45.1
opentelemetry-semantic-conventions==0.66b1
packaging==26.3
pathable==0.6.0
pillow==12.3.0
platformdirs==4.13.5
pluggy==1.7.0
propcache==0.5.4
protobuf==7.37.0rc1
psutil==7.2.2
psycopg==3.3.1
py-key-value-aio==0.4.6
py_rust_stemmers==0.1.8
pybars3==0.9.7
pycparser==3.12
pydantic==2.14.1
pydantic-extra-types==2.11.1
pydantic-settings==2.16.1
pydantic_core==2.50.1
Pygments==2.21.0
PyJWT==2.15.1
PyMeta3==0.5.1
pyperclip==1.11.0
pyright==1.1.414
pytest==9.1.1
pytest-aio==2.1.7
pytest-asyncio==1.4.0
python-dateutil==3.0.0
python-dotenv==1.2.4
python-frontmatter==1.3.0
python-multipart==0.0.32
pytz==2026.5
PyYAML==6.0.3
referencing==0.37.0
regex==2026.9.29
requests==2.34.2
rich==15.0.0
rich-rst==2.2.0
rich-toolkit==0.20.6
rignore==0.8.1
rpds-py==2026.9.1
ruamel.yaml==0.19.1
SecretStorage==3.5.0
sentry-sdk==3.0.0b1
shellingham==1.5.4
six==1.17.0
sniffio==1.3.1
SQLAlchemy==2.1.6
sqlite-vec==0.1.10a4
sse-starlette==3.5.0
starlette==1.9.0
tiktoken==0.14.0
tokenizers==0.23.3
tqdm==4.70.1
truststore==0.10.5
typer==0.27.3
typing-inspection==0.4.4
typing_extensions==4.16.0
tzdata==2026.5
tzlocal==5.4.5
uncalled-for==0.4.1
Unidecode==1.4.0
urllib3==2.8.0
uvicorn==0.54.0
uvloop==0.23.0
watchfiles==1.3.0
wcwidth==0.9.3
websockets==17.3
wrapt==2.5.2rc1
yarl==1.25.1
zipp==4.1.2

Captured with: uvx --prerelease=allow --from basic-memory python (importlib.metadata in the same uvx env; equivalent to uv pip freeze).

Full result per app: Does it work with Claude Code? · Does it work with Cursor? · Does it work with ChatGPT (Codex)?

Protocol: starts, 21 tools listed · 2026-10-22 · connected in 3.1s

🧪 Test-box note: Published snippet is the maker's README command (uvx --prerelease=allow basic-memory mcp). Notes go to ~/basic-memory on the test box (the default).

Real test

Passed

One run from our records. When two runs share a date, we show a failure if there is one.

Client

ChatGPT (Codex) · Codex CLI 0.162.0-alpha.17.2

Date

Oct 22, 2026

The task we gave

Using only the basic-memory MCP tools, save this so it can be found in a later session: the toolpassed test code is TP-B9260B. Reply 'stored' when done.

Using only the basic-memory MCP tools, look up the toolpassed test code that was saved in an earlier session and reply with it.

What it promised

details not recorded for this run

What happened

Tool calls:

basic-memory:recent_activitybasic-memory:search_notesbasic-memory:fetchbasic-memory:fetchbasic-memory:fetchbasic-memory:read_notebasic-memory:read_notebasic-memory:read_note

Other calls recorded:

basic-memory:write_note

Tool result

{"content": [{"type": "text", "text": "## Recent Activity: main (7d)\n\n**\ud83d\udcc4 Recent Notes & Documents (3):**\n  \u2022 Toolpassed test code TP-B9260B [id: f2cf824d-362d-4970-838b-2c60cecb3ade]\n  \u2022 Toolpassed test code TP-EA6E58 [id: eec4a97f-8ea2-4157-b8c1-b4a308e252e9]\n  \u2022 Passed test code TP-A0FA40 [id: 9bb08c52-0adf-4473-9150-7d4e64f08b0f]\n\n**Activity Summary:** 3 items found."}], "_meta": {"fastmcp": {"wrap_result": true}}, "structured_content": {"result": "## Recent Activity: main (7d)\n\n**\ud83d\udcc4 Recent Notes & Documents (3):**\n  \u2022 Toolpassed test code TP-B9260B [id: f2cf824d-362d-4970-838b-2c60cecb3ade]\n  \u2022 Toolpassed test code TP-EA6E58 [id: eec4a97f-8ea2-4157-b8c1-b4a308e252e9]\n  \u2022 Passed test code TP-A0FA40 [id: 9bb08c52-0adf-4473-9150-7d4e64f08b0f]\n\n**Activity Summary:** 3 items found."}}

Agent reply

I found three saved toolpassed test codes: **TP-B9260B**, **TP-EA6E58**, and **TP-A0FA40**.

Verdict

Passed

Install

claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp

Run in your terminal. This exact command is what our harness runs in Claude Code; see the results above.

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

Save as .cursor/mcp.json. This exact config is what our harness runs in Cursor; see the results above.

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

Add to claude_desktop_config.json and restart Claude Desktop. Tested on the Linux beta; see the results above.

[mcp_servers.basic-memory]
command = "uvx"
args = ["--prerelease=allow", "basic-memory", "mcp"]

Add to ~/.codex/config.toml (shared by the ChatGPT (Codex) CLI and the ChatGPT desktop app; Codex runs inside the ChatGPT desktop app). Tested with the ChatGPT (Codex) CLI bundled in the ChatGPT desktop app; see the results above.

Not connecting? Troubleshooting: Claude Code · Cursor · Claude Desktop · ChatGPT (Codex)

Test history

Date	Check	Result	Versions tested
2026-10-22	Protocol (direct stdio)	Protocol: starts, 21 tools listed	basic-memory 0.23.2 · server reported v4.0.0b1
2026-10-22	ChatGPT (Codex)	Passed install, connect, tools, agent task	Codex CLI 0.162.0-alpha.17.2 · basic-memory 0.23.2
2026-10-21	Claude Code	Passed install, connect, tools, agent task	Claude Code 2.1.296 · basic-memory 0.23.2
2026-10-21	Cursor	Passed install, connect, tools, agent task	Cursor CLI 2026.10.19-6bbf2c4 · basic-memory 0.23.2
2026-10-21	Protocol (direct stdio)	Protocol: starts, 21 tools listed	4.0.0b1

Tools seen by our harness (21)

basic_memory_diagnosticsdelete_noteread_contentbuild_contextrecent_activitysearch_notesread_noteview_notewrite_notelist_directoryedit_notemove_notelist_workspaceslist_memory_projectscreate_memory_projectdelete_projectsearchfetchschema_validateschema_inferschema_diff