🚀 Basic Memory Cloud is Live!

• Cross-device and multi-platform support is here. Your knowledge graph now works on desktop, web, and mobile.
• Cloud is optional. The local-first open-source workflow continues as always.
• OSS discount: use code BMFOSS for 20% off for 3 months.

Sign up now →

with a 7 day free trial

Basic Memory

Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to enable any compatible LLM to read and write to your local knowledge base.

What's New in v0.19.0

• Semantic Vector Search — find notes by meaning, not just keywords. Combines full-text and vector similarity for hybrid search with FastEmbed embeddings.
• Schema System — infer, validate, and diff the structure of your knowledge base with schema_infer, schema_validate, and schema_diff tools.
• Per-Project Cloud Routing — route individual projects through the cloud while others stay local, using API key authentication (basic-memory project set-cloud).
• FastMCP 3.0 — upgraded to FastMCP 3.0 with tool annotations for better client integration.
• CLI Overhaul — JSON output mode (--json) for scripting, workspace-aware commands, and an htop-inspired project dashboard.
• Smarter Editing — edit_note append/prepend auto-creates notes if they don't exist; write_note has an overwrite guard to prevent accidental data loss.
• Richer Search Results — matched chunk text returned in search results for better context.

See the full CHANGELOG for details.

• Website: basicmemory.com
• Documentation: docs.basicmemory.com
• Community: Discord

Pick up your conversation right where you left off

• AI assistants can load context from local files in a new conversation
• Notes are saved locally as Markdown files in real time
• No project knowledge or special prompting required

https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc

Quick Start

# Install with uv (recommended)
uv tool install basic-memory

# Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
# Add this to your config:
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
# Now in Claude Desktop, you can:
# - Write notes with "Create a note about coffee brewing methods"
# - Read notes with "What do I know about pour over coffee?"
# - Search with "Find information about Ethiopian beans"

You can view shared context via files in ~/basic-memory (default directory location).

Automatic Updates

Basic Memory includes a default-on auto-update flow for CLI installs.

• Auto-install supported: uv tool and Homebrew installs
• Default check interval: every 24 hours (86400 seconds)
• MCP-safe behavior: update checks run silently in basic-memory mcp mode
• uvx behavior: skipped (runtime is ephemeral and managed by uvx)

Manual update commands:

# Check now and install if supported
bm update

# Check only, do not install
bm update --check

Config options in ~/.basic-memory/config.json:

{
  "auto_update": true,
  "update_check_interval": 86400
}

To disable automatic updates, set "auto_update": false.

Why Basic Memory?

Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation starts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:

• Chat histories capture conversations but aren't structured knowledge
• RAG systems can query documents but don't let LLMs write back
• Vector databases require complex setups and often live in the cloud
• Knowledge graphs typically need specialized tools to maintain

Basic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can read and write to. The key advantages:

• Local-first: All knowledge stays in files you control
• Bi-directional: Both you and the LLM read and write to the same files
• Structured yet simple: Uses familiar Markdown with semantic patterns
• Traversable knowledge graph: LLMs can follow links between topics
• Standard formats: Works with existing editors like Obsidian
• Lightweight infrastructure: Just local files indexed in a local SQLite database

With Basic Memory, you can:

• Have conversations that build on previous knowledge
• Create structured notes during natural conversations
• Have conversations with LLMs that remember what you've discussed before
• Navigate your knowledge graph semantically
• Keep everything local and under your control
• Use familiar tools like Obsidian to view and edit notes
• Build a personal knowledge base that grows over time
• Sync your knowledge to the cloud with bidirectional synchronization
• Authenticate and manage cloud projects with subscription validation
• Mount cloud storage for direct file access

How It Works in Practice

Let's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:

1. Start by chatting normally:

I've been experimenting with different coffee brewing methods. Key things I've learned:

- Pour over gives more clarity in flavor than French press
- Water temperature is critical - around 205°F seems best
- Freshly ground beans make a huge difference

... continue conversation.

2. Ask the LLM to help structure this knowledge:

"Let's write a note about coffee brewing methods."

LLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):

---
title: Coffee Brewing Methods
permalink: coffee-brewing-methods
tags:
- coffee
- brewing
---

# Coffee Brewing Methods

## Observations

- [method] Pour over provides more clarity and highlights subtle flavors
- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
- [principle] Freshly ground beans preserve aromatics and flavor

## Relations

- relates_to [[Coffee Bean Origins]]
- requires [[Proper Grinding Technique]]
- affects [[Flavor Extraction]]

The note embeds semantic content and links to other topics via simple Markdown formatting.

3. You see this file on your computer in real time in the current project directory (default ~/$HOME/basic-memory).

• Realtime sync can be enabled via running basic-memory sync --watch

4. In a chat with the LLM, you can reference a topic:

Look at `coffee-brewing-methods` for context about pour over coffee

The LLM can now build rich context from the knowledge graph. For example:

Following relation 'relates_to [[Coffee Bean Origins]]':
- Found information about Ethiopian Yirgacheffe
- Notes on Colombian beans' nutty profile
- Altitude effects on bean characteristics

Following relation 'requires [[Proper Grinding Technique]]':
- Burr vs. blade grinder comparisons
- Grind size recommendations for different methods
- Impact of consistent particle size on extraction

Each related document can lead to more context, building a rich semantic understanding of your knowledge base.

This creates a two-way flow where:

• Humans write and edit Markdown files
• LLMs read and write through the MCP protocol
• Sync keeps everything consistent
• All knowledge stays in local files.

Technical Implementation

Under the hood, Basic Memory:

1. Stores everything in Markdown files
2. Uses a SQLite database for searching and indexing
3. Extracts semantic meaning from simple Markdown patterns
   • Files become Entity objects
   • Each Entity can have Observations, or facts associated with it
   • Relations connect entities together to form the knowledge graph
4. Maintains the local knowledge graph derived from the files
5. Provides bidirectional synchronization between files and the knowledge graph
6. Implements the Model Context Protocol (MCP) for AI integration
7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph
8. Uses memory:// URLs to reference entities across tools and conversations

The file format is just Markdown with some simple markup:

Each Markdown file has:

Frontmatter

title: <Entity title>
type: <The type of Entity> (e.g. note)
permalink: <a uri slug>

- <optional metadata> (such as tags) 

Observations

Observations are facts about a topic. They can be added by creating a Markdown list with a special format that can reference a category, tags using a "#" character, and an optional context.

Observation Markdown format:

- [category] content #tag (optional context)

Examples of observations:

- [method] Pour over extracts more floral notes than French press
- [tip] Grind size should be medium-fine for pour over #brewing
- [preference] Ethiopian beans have bright, fruity flavors (especially from Yirgacheffe)
- [fact] Lighter roasts generally contain more caffeine than dark roasts
- [experiment] Tried 1:15 coffee-to-water ratio with good results
- [resource] James Hoffman's V60 technique on YouTube is excellent
- [question] Does water temperature affect extraction of different compounds differently?
- [note] My favorite local shop uses a 30-second bloom time

Relations

Relations are links to other topics. They define how entities connect in the knowledge graph.

Markdown format:

- relation_type [[WikiLink]] (optional context)

Examples of relations:

- pairs_well_with [[Chocolate Desserts]]
- grown_in [[Ethiopia]]
- contrasts_with [[Tea Brewing Methods]]
- requires [[Burr Grinder]]
- improves_with [[Fresh Beans]]
- relates_to [[Morning Routine]]
- inspired_by [[Japanese Coffee Culture]]
- documented_in [[Coffee Journal]]

Using with VS Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

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

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

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

You can use Basic Memory with VS Code to easily retrieve and store information while coding.

Using with Claude Desktop

Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):

1. Configure Claude Desktop to use Basic Memory:

Edit your MCP configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json for OS X):

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

If you want to use a specific project (see Multiple Projects below), update your Claude Desktop config:

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

2. Sync your knowledge:

# One-time sync of local knowledge updates
basic-memory sync

# Run realtime sync process (recommended)
basic-memory sync --watch

3. Cloud features (optional, requires subscription):

# Authenticate with cloud (stores OAuth token locally)
basic-memory cloud login

# (Optional) install/configure rclone for file sync commands
basic-memory cloud setup

# Check cloud auth + health
basic-memory cloud status

Per-Project Cloud Routing (API key based):

Individual projects can be routed through the cloud while others stay local. This uses an API key for routed project calls:

# Save an API key (create one in the web app or via CLI)
basic-memory cloud set-key bmc_abc123...
# Or create one via CLI (requires OAuth login first)
basic-memory cloud create-key "my-laptop"

# Set a project to route through cloud
basic-memory project set-cloud research

# Revert a project to local mode
basic-memory project set-local research

# List projects and route metadata
basic-memory project list

basic-memory cloud login / basic-memory cloud logout are authentication commands. They do not change default CLI routing behavior.

Routing Flags:

Use routing flags to disambiguate command targets:

# Force local routing for this command
basic-memory status --local
basic-memory project list --local
basic-memory project ls --name main --local

# Force cloud routing for this command
basic-memory status --cloud
basic-memory project info my-project --cloud
basic-memory project ls --name main --cloud

No-flag behavior defaults to local when no project context is present.

The local MCP server routes per transport: --transport stdio honors per-project routing (local or cloud), while --transport streamable-http and --transport sse always route locally.

CLI Note Editing (tool edit-note):

# Append content
basic-memory tool edit-note project-plan --operation append --content $'\n## Next Steps\n- Finalize rollout'

# Find/replace with replacement count validation
basic-memory tool edit-note docs/api --operation find_replace --find-text "v0.14.0" --content "v0.15.0" --expected-replacements 2

# Replace a section body
basic-memory tool edit-note docs/setup --operation replace_section --section "## Installation" --content $'Updated install steps\n- Run just install'

# JSON metadata output for integrations
basic-memory tool edit-note docs/setup --operation append --content $'\n- Added note' --format json

4. In Claude Desktop, the LLM can now use these tools:

Content Management:

write_note(title, content, folder, tags, output_format="text"|"json") - Create or update notes
read_note(identifier, page, page_size, output_format="text"|"json") - Read notes by title or permalink
read_content(path) - Read raw file content (text, images, binaries)
view_note(identifier) - View notes as formatted artifacts
edit_note(identifier, operation, content, output_format="text"|"json") - Edit notes incrementally
move_note(identifier, destination_path, output_format="text"|"json") - Move notes with database consistency
delete_note(identifier, output_format="text"|"json") - Delete notes from knowledge base

Knowledge Graph Navigation:

build_context(url, depth, timeframe, output_format="json"|"text") - Navigate knowledge graph via memory:// URLs
recent_activity(type, depth, timeframe, output_format="text"|"json") - Find recently updated information
list_directory(dir_name, depth) - Browse directory contents with filtering

Search & Discovery:

search(query, page, page_size) - Search across your knowledge base
search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project) - Search with filters (query is optional for filter-only searches)

Project Management:

list_memory_projects(output_format="text"|"json") - List all available projects
create_memory_project(project_name, project_path, output_format="text"|"json") - Create new projects
get_current_project() - Show current project stats
sync_status() - Check synchronization status

output_format defaults to "text" for these tools, preserving current human-readable responses. build_context defaults to "json" and can be switched to "text" when compact markdown output is preferred.

Cloud Discovery (opt-in):

cloud_info() - Show optional Cloud overview and setup guidance
release_notes() - Show latest release notes

Visualization:

canvas(nodes, edges, title, folder) - Generate knowledge visualizations

5. Example prompts to try:

"Create a note about our project architecture decisions"
"Find information about JWT authentication in my notes"
"Create a canvas visualization of my project components"
"Read my notes on the authentication system"
"What have I been working on in the past week?"

Futher info

See the Documentation for more info, including:

• Complete User Guide
• CLI tools
• Cloud CLI and Sync
• Managing multiple Projects
• Importing data from OpenAI/Claude Projects

Telemetry

Basic Memory collects anonymous, minimal usage events to understand how the CLI-to-cloud conversion funnel performs. This helps us prioritize features and improve the product.

What we collect:

• Cloud promo impressions (when the promo banner is shown)
• Cloud login attempts and outcomes
• Promo opt-out events

What we do NOT collect:

• No file contents, note titles, or knowledge base data
• No personally identifiable information (PII)
• No IP address tracking or fingerprinting
• No per-command or per-tool-call tracking

Events are sent to our Umami Cloud instance, an open-source, privacy-focused analytics platform. Events are fire-and-forget on a background thread — analytics never blocks or slows the CLI.

Opt out by setting the environment variable:

export BASIC_MEMORY_NO_PROMOS=1

This disables both promo messages and all telemetry events.

Logging

Basic Memory uses Loguru for logging. The logging behavior varies by entry point:

Entry Point	Default Behavior	Use Case
CLI commands	File only	Prevents log output from interfering with command output
MCP server	File only	Stdout would corrupt the JSON-RPC protocol
API server	File (local) or stdout (cloud)	Docker/cloud deployments use stdout

Log file location: ~/.basic-memory/basic-memory.log (10MB rotation, 10 days retention)

Environment Variables

Variable	Default	Description
BASIC_MEMORY_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR
BASIC_MEMORY_CLOUD_MODE	false	When true, API logs to stdout with structured context
BASIC_MEMORY_FORCE_LOCAL	false	When true, forces local API routing
BASIC_MEMORY_FORCE_CLOUD	false	When true, forces cloud API routing
BASIC_MEMORY_EXPLICIT_ROUTING	false	When true, marks route selection as explicit (--local/--cloud)
BASIC_MEMORY_ENV	dev	Set to test for test mode (stderr only)
BASIC_MEMORY_NO_PROMOS	false	When true, disables cloud promo messages and telemetry

Examples

# Enable debug logging
BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync

# View logs
tail -f ~/.basic-memory/basic-memory.log

# Cloud/Docker mode (stdout logging with structured context)
BASIC_MEMORY_CLOUD_MODE=true uvicorn basic_memory.api.app:app

Development

Running Tests

Basic Memory supports dual database backends (SQLite and Postgres). By default, tests run against SQLite. Set BASIC_MEMORY_TEST_POSTGRES=1 to run against Postgres (uses testcontainers - Docker required).

Quick Start:

# Run all tests against SQLite (default, fast)
just test-sqlite

# Run all tests against Postgres (uses testcontainers)
just test-postgres

# Run both SQLite and Postgres tests
just test

Available Test Commands:

• just test - Run all tests against both SQLite and Postgres
• just test-sqlite - Run all tests against SQLite (fast, no Docker needed)
• just test-postgres - Run all tests against Postgres (uses testcontainers)
• just test-unit-sqlite - Run unit tests against SQLite
• just test-unit-postgres - Run unit tests against Postgres
• just test-int-sqlite - Run integration tests against SQLite
• just test-int-postgres - Run integration tests against Postgres
• just test-windows - Run Windows-specific tests (auto-skips on other platforms)
• just test-benchmark - Run performance benchmark tests
• just testmon - Run tests impacted by recent changes (pytest-testmon)
• just test-smoke - Run fast MCP end-to-end smoke test
• just fast-check - Run fix/format/typecheck + impacted tests + smoke test
• just doctor - Run local file <-> DB consistency checks with temp config

Postgres Testing:

Postgres tests use testcontainers which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.

Testmon Note: When no files have changed, just testmon may collect 0 tests. That's expected and means no impacted tests were detected.

Test Markers:

Tests use pytest markers for selective execution:

• windows - Windows-specific database optimizations
• benchmark - Performance tests (excluded from default runs)
• smoke - Fast MCP end-to-end smoke tests

Other Development Commands:

just install          # Install with dev dependencies
just lint             # Run linting checks
just typecheck        # Run type checking
just typecheck-ty     # Run ty type checking (incremental supplement to pyright)
just format           # Format code with ruff
just fast-check       # Fast local loop (fix/format/typecheck + testmon + smoke)
just doctor           # Local consistency check (temp config)
just check            # Run all quality checks
just migration "msg"  # Create database migration

Type Checking Strategy:

• just typecheck (Pyright) remains the primary, blocking type checker.
• just typecheck-ty (Astral ty) is available as a supplemental checker while rules are adopted incrementally.
• We recommend running both locally while reducing ty diagnostics over time.

Local Consistency Check:

basic-memory doctor   # Verifies file <-> database sync in a temp project

See the justfile for the complete list of development commands.

License

AGPL-3.0

Contributions are welcome. See the Contributing guide for info about setting up the project locally and submitting PRs.

Star History

Built with ♥️ by Basic Machines