Basic Memory for Claude Code: Setup & Config

What you can do with Basic Memory in Claude Code

Persistent AI knowledge in editable Markdown, with local ownership and optional cloud teamwork.

• Keep architecture decisions available across AI sessions.
• Share team notes through the optional cloud workspace.

Before you start: Basic Memory in Claude Code

• Python 3.12+
• uv / uvx
• An MCP-compatible client

This 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.

Basic Memory Claude Code configuration

1. Choose Claude Code configuration scope

   For Basic Memory, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Basic Memory to Claude Code

   Use the basic-memory entry below in mcpServers. Keep Basic Memory's documented stdio connection fields and your other Claude Code entries.

3. Check Basic Memory in Claude Code

   Basic Memory: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'basic-memory' '{"type":"stdio","command":"uvx","args":["basic-memory","mcp"],"env":{}}'

Basic Memory tools available to Claude Code

Basic Memory's stored tool list documents 7 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

search

For Basic Memory's search, review the permission request and arguments in Claude Code before approval.

fetch

For Basic Memory's fetch, review the permission request and arguments in Claude Code before approval.

schema_infer

For Basic Memory's schema_infer, review the permission request and arguments in Claude Code before approval.

Infer the structure of a knowledge base.

schema_validate

For Basic Memory's schema_validate, review the permission request and arguments in Claude Code before approval.

Check knowledge against its schema.

schema_diff

For Basic Memory's schema_diff, review the permission request and arguments in Claude Code before approval.

Compare knowledge-base structure changes.

edit_note

For Basic Memory's edit_note, review the permission request and arguments in Claude Code before approval.

write_note

For Basic Memory's write_note, review the permission request and arguments in Claude Code before approval.

Write a note with protection against unintended overwrites.

Basic Memory: full stored tool descriptions

Troubleshooting Basic Memory in Claude Code

• If Basic Memory fails to start, check uvx basic-memory (from uv, for Python tools), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Basic Memory uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Local users manage their own backups and cross-device sync.
• Known limitation: Cloud hosting is a paid option.
• Known limitation: The local install requires Python.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions