Server facts
Basic Memory MCP Server
Project
- Author
- basicmachines-co
- Repository
- github.com/basicmachines-co/basic-memory
- Website
- basicmemory.com
- License
- AGPL-3.0
- Category
- Memory & Knowledge
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 4,249
- Last commit
- Data as of
Tags
- Knowledge Graph
- Local First
- Markdown
- Semantic Search
Overview
Basic Memory turns Markdown notes into shared working knowledge for people and AI assistants. Instead of keeping useful information only inside a conversation, it lets compatible clients read, write, and search files that remain accessible in ordinary editors. Observations and wikilinks connect those notes into a graph, while semantic retrieval complements full-text search. The local setup uses files on disk with a SQLite index, and the README also describes vector search on SQLite or Postgres using FastEmbed embeddings. Obsidian can work directly with the same Markdown, frontmatter, and links.
Local operation is free under AGPL-3.0 and requires Python 3.12 or newer. The documented stdio launch uses uvx, with configuration examples for Claude Desktop, Claude Code, Codex, Cursor, and VS Code. An optional paid cloud version handles hosting, cross-device synchronization, backups, snapshots, and mobile access. Teams adds a shared workspace and collaborative note editing. Local users instead arrange their own synchronization and backups. The engine exposes behavior annotations to help agents discover tools, along with note editing and schema inspection capabilities. Separate host integrations can add session briefings or checkpoints, but the Claude Code plugin requires the MCP connection first. The distinction is straightforward: Markdown remains the knowledge format, while local or hosted operation determines how it is maintained and shared.
Install & configure
Requirements
- Python 3.12+
- uv / uvx
- An MCP-compatible client
uvx basic-memory mcpThis is the local client configuration from the README. Notes default to ~/basic-memory. Optional cloud onboarding is separate; no cloud MCP endpoint is specified in the supplied README.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"basic-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"basic-memory",
"mcp"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"basic-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"basic-memory",
"mcp"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| search | Search knowledge through the documented ChatGPT-compatible action interface. |
| fetch | Retrieve knowledge through the documented ChatGPT-compatible action interface. |
| schema_infer | Infer the structure of a knowledge base. |
| schema_validate | Check knowledge against its schema. |
| schema_diff | Compare knowledge-base structure changes. |
| edit_note | Edit notes, including append and prepend operations. |
| write_note | Write a note with protection against unintended overwrites. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Keep architecture decisions available across AI sessions.
- Search notes by meaning rather than exact wording.
- Use Obsidian and an AI assistant on the same knowledge files.
- Share team notes through the optional cloud workspace.
Strengths
- Human-readable Markdown remains editable outside the AI client.
- Local-first operation does not require cloud hosting.
- Combines graph links with full-text and vector search.
- Optional hosted backups and collaboration.
Limitations
- Local users manage their own backups and cross-device sync.
- Cloud hosting is a paid option.
- The local install requires Python.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
