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.

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:

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:

Examples of observations:

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

Markdown format:

Examples of relations:

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

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.

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

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):

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

2. Sync your knowledge:

3. Cloud features (optional, requires subscription):

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:

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:

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):

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

Content Management:

Knowledge Graph Navigation:

Search & Discovery:

Project Management:

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):

Visualization:

5. Example prompts to try:

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

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:

This disables both promo messages and all telemetry events.

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)

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

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:

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:

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:

See the justfile for the complete list of development commands.

AGPL-3.0

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

Built with hearts by Basic Machines