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.
Basic Memory adheres to a local-first approach pyproject.toml4:
bm hook harness provides standardized entry points for agent lifecycle events like session-start and pre-compact CHANGELOG.mdNaN-NaNThe following diagram illustrates how high-level system concepts map to specific identifiers and entry points within the codebase.
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
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 |
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
To learn more about specific areas of Basic Memory, refer to the following child pages:
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
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
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
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
Refresh this wiki