Basic Memory

Community

Your AI never forgets again.

How to install ↓ Compare GitHub source repository ↗

Category: Other
Stars: ★ 4.2k Very popular
Transport: stdio (local process)
Runtime: Python 3.12+
Credentials: No credential needed
License: AGPL-3.0
Last commit: today
Tools: 21

72FMRS · B

Basic Memory offers local-first bidirectional knowledge management with seamless integration with various AI clients. Its Markdown format and knowledge graph design make it easy to understand and extend. However, the cloud service requires payment, and local mode requires a Python environment. Overall, it's a powerful tool for enhancing AI memory, especially suited for privacy-conscious developers.

Strongest · Documentation 17/20 Weakest · Reliability 10/20

Reliability

10/20

Security and permissions

15/20

Maintenance

16/20

Documentation

17/20

Setup experience

14/20

Why each score

Reliability 10/20: Static review only; nothing executed. The manifest and README are consistent (uvx basic-memory mcp / stdio), and the README describes careful design: MCP server logging goes to file only to avoid corrupting JSON-RPC stdout, fail-fast configuration with no silent fallback, and behavior-hint annotations on every tool. However, the README is untrusted evidence; CI workflows and committed tests inside the repo cannot be verified from the supplied source, and error paths rest on documentation claims. Since static calibration caps reliability at 12 without in-file execution evidence and uncertainty lowers scores, 10 is awarded.
Security and permissions 15/20: No red lines triggered: no malware, no credential theft, no covert exfiltration, no irreversible default actions. Local-first with optional cloud; telemetry is explicitly disclosed (promo impressions/login outcomes only, no note content, Umami, fully disabled via BASIC_MEMORY_NO_PROMOS); destructive tools carry destructiveHint and the Codex integration preserves approval. Deductions: telemetry events still leave the machine, cloud routing and optional reranker involve external network and API keys via env vars, and credential storage plus the server's accessible project scope cannot be verified from source; confirmation flows depend on the client side. Hence 15.
Maintenance 16/20: Clear AGPL-3.0 license; manifest version 0.22.1 with a changelog showing sustained v0.18→v0.20→v0.22 release cadence; automatic update mechanism, justfile quality gates (lint/typecheck/test/package-check), and multiple integrations (Claude Code plugin, Hermes, OpenClaw) maintained from one tree indicate mature governance. Deductions: no explicit security-response channel visible in the README, and issue response time or dependency-update frequency cannot be verified from static evidence. Hence 16.
Documentation 17/20: The README is layered and unusually complete: cloud and local install paths, config examples for 8+ clients with full JSON blocks, tool inventory, Markdown knowledge-format spec, CLI reference, environment-variable table with defaults, logging rotation behavior, telemetry and pricing disclosure, and explicit limitations (reranking off by default due to latency/model download, auto-update skipped for uvx, air-gapped only on local). Cost and trial terms are clear. Deductions: the docs site and full tool-parameter reference live outside the repo and cannot be verified, and README evidence is self-published. Hence 17.
Setup experience 14/20: Install path is clear and the manifest matches the README examples exactly (uv tool install or uvx basic-memory mcp, stdio); Claude Desktop/Claude Code/Codex/Cursor/VS Code all have copy-paste config blocks, and the cloud path claims 30 seconds with no install. Deductions: the local path requires Python and the uv toolchain, some clients need manual JSON editing, and static calibration caps setup at 15 without verifiable execution evidence in the files; uncertainty lowers it. Hence 14.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local filesConnects to a database

Best for

Privacy-conscious developers who want local data storage.
Researchers who need AI-assisted management of large note collections.
Users of Markdown editors like Obsidian.

Not for

Users needing cloud sync and mobile access (unless using the paid cloud service).
Minimalists who want zero configuration.
Scenarios requiring large-scale vector databases and complex retrieval (local SQLite may be insufficient).

Required permissions

Read and write to the local filesystem (default: ~/basic-memory).
Perform file and directory operations (create, edit, delete).
Access local SQLite database (or Postgres/Milvus if configured).

Risks and side effects

Tools have write operations that may unintentionally modify or delete notes.
Edit operations may overwrite existing content, though there are protections.
Semantic search and reranking features may require model downloads, adding latency.
Local data backups are the user's responsibility.

Setup

Before you start

Runtime：Python 3.12+

COHERE_API_KEY optionalsecret Required only when using LiteLLM-hosted reranking (e.g. cohere/rerank-v3.5); get it from Cohere.

Other optional settings (12)

BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED optional Set to true to enable semantic vector search (off by default).

BASIC_MEMORY_RERANKER_ENABLED optional Set to true to enable cross-encoder reranking of search results.

BASIC_MEMORY_RERANKER_PROVIDER optional Reranker provider; default is local FastEmbed, set to litellm for a hosted provider.

BASIC_MEMORY_RERANKER_MODEL optional Reranker model name, e.g. cohere/rerank-v3.5.

BASIC_MEMORY_LOG_LEVEL optional Log level, default INFO; options DEBUG/INFO/WARNING/ERROR.

BASIC_MEMORY_CLOUD_MODE optional Set to true to log API output to stdout with structured context.

BASIC_MEMORY_FORCE_LOCAL optional Set to true to force local API routing.

BASIC_MEMORY_FORCE_CLOUD optional Set to true to force cloud API routing.

BASIC_MEMORY_EXPLICIT_ROUTING optional Set to true to mark route selection as explicit.

BASIC_MEMORY_ENV optional Runtime environment, default dev; set to test for test mode (stderr only).

BASIC_MEMORY_NO_PROMOS optional Set to 1 to disable cloud promos and all telemetry.

BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES optional Max import upload size, default 104857600 bytes.

Install basic-memory via uv, then configure the MCP server in your client. For example, in Claude Desktop add:

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

claude_desktop_config.json

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

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

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

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add basic-memory -- uvx basic-memory mcp

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After installing, restart your client and confirm tools like write_note, read_note, and search_notes appear in the MCP tool list; you can also ask the AI to "write a test note and read it back" — success confirms the connection. Notes live in ~/basic-memory by default.

Troubleshooting

Ensure uv and Python 3.12+ are installed, and check that the MCP server starts successfully.
Use `basic-memory status` for diagnostics and inspect the log file `~/.basic-memory/basic-memory.log` for errors.
If search returns no results, verify semantic search is enabled.

Things to try

Once connected, you can ask your AI assistant things like:

Create a note about our project architecture decisions.
Find information about JWT auth in my notes.
What have I been working on this week?
Delete that outdated deployment note.

Tools 21

write_note writes

Create or overwrite a note.

read_note read-only

Read the content of a note.

edit_note writes

Edit a note, supporting append and prepend.

move_note writes

Move a note to a new location.

delete_note destructive

Delete a note.

read_content read-only

Read the content of any file.

view_note read-only

View note details.

search_notes read-only

Search notes with semantic and hybrid search.

Show 13 more tools

recent_activity read-only

Get recent activity records.

list_directory read-only

List directory contents.

build_context read-only

Build knowledge graph context by navigating memory:// URLs.

list_memory_projects read-only

List all memory projects.

list_workspaces read-only

List all workspaces.

create_memory_project writes

Create a new memory project.

delete_project destructive

Delete a memory project.

schema_infer read-only

Infer the schema of your knowledge base.

schema_validate read-only

Validate the schema of your knowledge base.

schema_diff read-only

Compare schema differences.

search read-only

OpenAI-compatible search tool.

fetch read-only

OpenAI-compatible fetch tool.

basic_memory_diagnostics read-only

Run diagnostic checks.

Use cases

Let your AI remember your project preferences without re-explaining.

Continuously record and retrieve knowledge across sessions.

Share a knowledge base with your team, editable by both humans and AI.

Supported clients

Claude Desktop

Claude Code

Codex

Cursor

VS Code

ChatGPT

Obsidian

Listed from the project's documentation, not tested by this site.

Overview

Basic Memory is a local-first knowledge management server that enables bidirectional sync between humans and AI via Markdown files. It supports knowledge graphs, semantic search, and integrates with MCP clients like Claude, Codex, and Cursor, allowing you and your AI to read, write, search, and manage knowledge together.

Similar servers

DuckDuckGo Search MCP Server 74 · B

MCP server providing web search and content fetching via DuckDuckGo

★ 1.5k · Tools 2 Compare with this →

Telegram MCP Server 70 · B

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

★ 1.8k · Tools 76 Compare with this →

Hostinger API MCP Server 70 · B

Official MCP server for Hostinger API.

★ 160 · Tools 100 Compare with this →

Figma Flutter MCP Server 68 · C

Utilize Figma's rich data in your coding agent. Implement designs in Flutter way!

★ 244 · Tools 2 Compare with this →

Compare with other MCP servers

Source revision d1275262b202 Data synced 2026-10-13 Read the FMRS scoring method