# basicmachines-co/basic-memory architecture

> Architecture diagram of the GitHub repository basicmachines-co/basic-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/basicmachines-co/basic-memory
- Repository: https://github.com/basicmachines-co/basic-memory

## Overview

##### Project Type and Purpose
- Basic Memory is a local knowledge base system that lets users and LLMs (such as Claude) interact by reading and writing structured Markdown files. It includes both an API layer (to support MCP integration for LLMs) and a CLI for command-based interactions. It manages a knowledge graph extracted from Markdown files and uses a SQLite database for indexing and searching.
- Its goal is to provide “persistent memory” for conversations, allowing for bi-directional updates between human-provided notes and AI assistants. It is a full-stack project built around local file storage, API/CLI communication, and integration with external AI services.

##### File Structure
– api: Implements HTTP endpoints (routers for knowledge, memory, search, and project info) to support the MCP protocol.
– cli: Contains command implementations allowing command-line interactions (e.g., sync, import, status, and project commands).
– mcp: Implements the Model Context Protocol (both client and server components) to integrate with LLMs like Claude.
– models, repository, schemas: The layered abstraction for data – defining entities, database repositories, and data transport formats.
– markdown: Logic to process Markdown files and extract structured data such as Observations and Relations.
– services: Business logic components including context service, entity service, file service, and search service.
- Other supporting files include configuration (pyproject.toml, Dockerfile, Makefile) and tests across multiple domains (API, CLI, markdown, repository, etc.).

a. Main Components:
- Input Layer:
– CLI Interface: Allows users to run commands like sync, import, and note manipulation.
– API Server: Exposes HTTP endpoints (via routers) for MCP-based communication (used by LLMs and integration with Claude Desktop).
- Business Logic Layer:
– MCP Component: Implements the Model Context Protocol to interact with external LLMs (bidirectional read/write for notes).
– Services: Contains logic for entity management, context building, and search operations.
- Data Layer:
– Repository & Database: Uses a SQLite database to index and search Markdown files and store metadata.
– File System Storage: Houses all the Markdown files that represent the persistent knowledge base.
- Supporting Components:
– Markdown Parser/Processor: Converts Markdown files into structured entities (knowledge, observations, relations).
– Data Sync Module: Manages watch processes and real-time synchronization between file changes and the database.
– Configuration/Environment: Build scripts (Makefile, Dockerfile) and configuration files (pyproject.toml, installer scripts) that help deploy and run the system.

b. Relationships and Interactions:
- The CLI and API Server both interact with the core “services” module.
- The MCP component (invoked via both API endpoints and CLI) communicates with external LLMs by adhering to the MCP protocol.
- Services access the repository layer, which in turn reads/writes to both the SQLite database and the local Markdown file system.
- The Markdown parser/processor extracts semantic entities from the files, enabling the repository to maintain and update the knowledge graph.
- Data flows should show:
– User commands (via CLI/API) trigger service calls.
– Services interact with the repository to update/read persistent storage.
– Data synchronization between file changes (Markdown) and SQLite occurs in near-real time.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Different layers (interface, business logic, data persistence) are clearly demarcated.
- Modular Design: Components are organized in distinct modules (api, cli, mcp, services, repository, markdown) with clear responsibilities.
- Local-First & Lightweight: Uses local files (Markdown) and a SQLite database, avoiding heavy cloud infrastructure.
- Extensibility: The use of routers and commands makes it adaptable to both CLI and HTTP/MCP driven interactions.

d. Relevant Technologies, Frameworks, and Tools:
- Python (with support for Python 3.12+)
- SQLite for persistent storage
- Docker (via Dockerfile) and Makefile for deployment and automation
- CI/CD and testing via GitHub workflows (in .github/workflows)
- External integrations with Claude Desktop and Smithery for MCP configuration
- Markdown processing libraries (implied in src/basic_memory/markdown)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Interfaces
    subgraph "Input Interfaces"
        CLI["CLI Interface"]:::input
        API["API Server"]:::input
    end

    %% Core Services Layer
    subgraph "Core Services"
        BS["Business Services"]:::services
        MCP["MCP Module"]:::services
        MP["Markdown Parser/Processor"]:::services
        DS["Data Sync Module"]:::services
    end

    %% Data Layer
    subgraph "Data Layer"
        Repo["Repository & Database Interface"]:::data
        DB["SQLite Database"]:::database
        FS["File System Storage (Markdown)"]:::data
    end

    %% External Communication
    subgraph "External Communication"
        LLM["External LLM (Claude Desktop)"]:::external
    end

    %% Infrastructure & Support
    subgraph "Infrastructure & Support"
        conf["Configuration & Deployment Scripts"]:::infra
    end

    %% Relationships
    CLI -->|"triggers"| BS
    API -->|"triggers"| BS
    BS <-->|"accesses"| Repo
    BS -->|"invokes"| MCP
    MP -->|"parses_into"| Repo
    DS -->|"syncs_with"| Repo
    Repo -->|"stores_in"| DB
    Repo -->|"reads_from"| FS
    MCP -->|"communicates_with"| LLM

    %% Click Events
    click CLI "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/cli"
    click API "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/api"
    click MCP "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/mcp"
    click BS "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/services"
    click Repo "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/repository"
    click MP "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/markdown"
    click DS "https://github.com/basicmachines-co/basic-memory/tree/main/src/basic_memory/sync"
    click conf "https://github.com/basicmachines-co/basic-memory/tree/main/Dockerfile"
    click conf "https://github.com/basicmachines-co/basic-memory/tree/main/Makefile"
    click conf "https://github.com/basicmachines-co/basic-memory/blob/main/pyproject.toml"

    %% Styles
    classDef input fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef services fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef data fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef database fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
