Overview

Relevant source files

• .claude-plugin/marketplace.json
• .github/workflows/release.yml
• .gitignore
• CHANGELOG.md
• CLA.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md
• integrations/openclaw/package.json
• plugins/claude-code/.claude-plugin/marketplace.json
• plugins/claude-code/.claude-plugin/plugin.json
• plugins/codex/.codex-plugin/plugin.json
• pyproject.toml
• server.json
• src/basic_memory/__init__.py
• src/basic_memory/cli/app.py
• src/basic_memory/cli/commands/__init__.py
• src/basic_memory/cli/main.py

Basic Memory is a local-first knowledge management system that combines the structural benefits of a Knowledge Graph with the human-readability of Markdown files. It is designed to provide AI agents (via the Model Context Protocol) and humans with a shared, durable memory that persists across sessions and projects.

The system treats Markdown files as the source of truth, indexing them into a relational database to enable complex graph traversals, full-text search, and semantic (vector) retrieval.

Local-First Philosophy

Basic Memory adheres to a local-first approach pyproject.toml4:

• Plain Text: Knowledge is stored as standard Markdown files on your local disk README.md37-39
• Privacy & Control: Data remains under your control, air-gap friendly, and accessible without an internet connection README.md78-80
• Cloud Optional: While a hosted cloud version exists for cross-device sync, the core engine is open-source (AGPL-3.0) and runs entirely locally README.md75-168

Key Capabilities

• Bidirectional Sync: Both humans and AI agents can read and write to the same files; the system reconciles changes automatically README.md40
• Knowledge Graph: Uses WikiLinks and structured "Observations" to build a traversable graph of related concepts README.md41
• Hybrid Search: Combines Full-Text Search (FTS) with semantic vector embeddings to find notes by meaning README.md42-43
• Concurrent Safety: Persistence is built around generation-versioned, compare-and-swap writes to prevent deadlocks in multi-agent workloads CHANGELOG.md7-99
• MCP-Native: Built from the ground up to support the Model Context Protocol, working out-of-the-box with Claude Desktop, Cursor, and other agents README.md44-133
• Lifecycle Hooks: A bm hook harness provides standardized entry points for agent lifecycle events like session-start and pre-compact CHANGELOG.mdNaN-NaN

---

System Context: Natural Language to Code Entities

The following diagram illustrates how high-level system concepts map to specific identifiers and entry points within the codebase.

Entry Points and Runtime Modes

Basic Memory can run in different "modes" (Local, Cloud, or API) depending on the entry point used.

Sources: pyproject.toml81-82 src/basic_memory/cli/main.py18-38 src/basic_memory/cli/app.py71-151 CHANGELOG.md15-117

---

Subsystem Relationships

Basic Memory is structured into several layers that coordinate to keep the filesystem and the database in sync while serving AI requests.

Subsystem	Primary Role	Key Code Entities
Storage	Persists notes and metadata	Entity, Observation, Relation (Models)
Services	Business logic and file I/O	EntityService, FileService, SyncService
Search	Indexing and retrieval	SearchService, SQLiteSearchRepository, MilvusVectorIndex
Interface	Exposing tools to agents	FastMCP, basic_memory_diagnostics
Caching	High-performance reads	ReadCache, Redis

Knowledge Flow Diagram

This diagram shows how a note travels from a file on disk to a searchable entity in an LLM's context, specifically mapping code-level actors to the process.

Sources: README.md130-135 CHANGELOG.md59-102 pyproject.toml27-73 src/basic_memory/cli/app.py149-151

---

Navigating the Documentation

To learn more about specific areas of Basic Memory, refer to the following child pages:

Getting Started

Covers installation via uv tool install basic-memory README.md84 initial configuration of the config.json project registry, and setting up the MCP server for use in Claude Desktop or Cursor server.json1-31 It also details the bm CLI entrypoint pyproject.toml82 and the bm config command group for managing settings CHANGELOG.mdNaN-NaN

• See: Getting Started

Note Format and Knowledge Representation

Detailed reference for the Markdown-based note format. Explains how to use YAML frontmatter (including created/modified timestamps CHANGELOG.md90-92), the syntax for "Observations" (e.g., [category] content #tags), and how to define relationships between notes using WikiLinks or explicit relation syntax README.md37-41 CHANGELOG.md97-99

• See: Note Format and Knowledge Representation

Core Architecture

A deep dive into the internal structure of the codebase, including the service-repository pattern, the dual-backend strategy (SQLite/Postgres), pluggable vector indexes like Milvus CHANGELOG.md63-71 and the use of uvloop to resolve asyncpg engine-dispose races on Postgres src/basic_memory/cli/app.py73-105

• See: Core Architecture

---

Sources: CHANGELOG.md1-128 README.md1-172 src/basic_memory/__init__.py1-7 pyproject.toml1-82 src/basic_memory/cli/main.py1-44 src/basic_memory/cli/app.py1-166 src/basic_memory/cli/commands/__init__.py1-38