> ## Documentation Index
> Fetch the complete documentation index at: https://memory.basicmachines.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Information

> Technical details about Basic Memory's implementation, architecture, licensing, and Model Context Protocol integration

## Architecture

Basic Memory consists of:

> [card] Core Knowledge Engine
>
> Parses and indexes Markdown files

> [card] SQLite Database
>
> Provides fast querying and search

> [card] MCP Server
>
> Implements the Model Context Protocol

> [card] CLI Tools
>
> Command-line utilities for management

> [card] Sync Service
>
> Monitors file changes and updates the database

> [!NOTE]
>
> The system follows a **file-first architecture** where all knowledge is represented in standard Markdown files and the database serves as a secondary index.

## Model Context Protocol (MCP)

Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools:

> [card] Standardized Interface
>
> Common protocol for tool integration

> [card] Tool Registration
>
> Basic Memory registers as a tool provider

> [card] Asynchronous Communication
>
> Enables efficient interaction with AI models

> [card] Standardized Schema
>
> Structured data exchange format

Integration with Claude Desktop uses the MCP to grant Claude access to your knowledge base through a set of specialized tools that search, read, and write knowledge.

## Licensing

Basic Memory is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.en.html):

> [card] Free Software
>
> You can use, study, share, and modify the software

> [card] Copyleft
>
> Derivative works must be distributed under the same license

> [card] Network Use
>
> Network users must be able to receive the source code

> [card] Commercial Use
>
> Allowed, subject to license requirements

> [!NOTE]
>
> The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks.

## Source Code

Basic Memory is developed as an open-source project:

> [card] GitHub Repository
>
> [https://github.com/basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory)

> [card] Issue Tracker
>
> Report bugs and request features on GitHub

> [card] Contributions
>
> Pull requests are welcome following the contributing guidelines

> [card] Documentation
>
> Source for this documentation is also available in the repository

## Data Storage and Privacy

Basic Memory is designed with privacy as a core principle:

> [!NOTE]
>
> **Privacy-First Design:**
>
> * **Local-First**: All data remains on your local machine
> * **No Cloud Dependency**: No remote servers or accounts required
> * **Telemetry**: Optional and disabled by default
> * **Standard Formats**: All data is stored in standard file formats you control

## Implementation Details

Knowledge in Basic Memory is organized as a semantic graph:

**1. Entities**

Distinct concepts represented by Markdown documents

**2. Observations**

Categorized facts and information about entities

**3. Relations**

Connections between entities that form the knowledge graph

This structure emerges from simple text patterns in standard Markdown:

### Example Markdown Input

```markdown theme={null}
---
title: Coffee Brewing Methods
type: note
permalink: coffee/coffee-brewing-methods
tags:
- '#coffee'
- '#brewing'
- '#methods'
- '#demo'
---

# Coffee Brewing Methods

An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction.

## Overview

Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans,
resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are:

- Grind size
- Water temperature
- Brew time
- Coffee-to-water ratio
- Agitation/turbulence

## Observations

- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds
  #extraction
- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity

## Relations

- requires [[Proper Grinding Technique]]
- affects [[Flavor Extraction]]
```

### Parsed JSON Structure

> [accordion] Resulting JSON Entity Structure
>
> ```json theme={null}
> {
>   "entities": [
>     {
>       "permalink": "coffee/coffee-brewing-methods",
>       "title": "Coffee Brewing Methods",
>       "file_path": "Coffee Notes/Coffee Brewing Methods.md",
>       "entity_type": "note",
>       "entity_metadata": {
>         "title": "Coffee Brewing Methods",
>         "type": "note",
>         "permalink": "coffee/coffee-brewing-methods",
>         "tags": "['#coffee', '#brewing', '#methods', '#demo']"
>       },
>       "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c",
>       "content_type": "text/markdown",
>       "observations": [
>         {
>           "category": "principle",
>           "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction",
>           "tags": [
>             "extraction"
>           ],
>           "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction"
>         },
>         {
>           "category": "method",
>           "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity",
>           "tags": [
>             "clarity"
>           ],
>           "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity"
>         }
>       ],
>       "relations": [
>         {
>           "from_id": "coffee/coffee-bean-origins",
>           "to_id": "coffee/coffee-brewing-methods",
>           "relation_type": "pairs_with",
>           "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods",
>           "to_name": "Coffee Brewing Methods"
>         },
>         {
>           "from_id": "coffee/flavor-extraction",
>           "to_id": "coffee/coffee-brewing-methods",
>           "relation_type": "affected_by",
>           "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods",
>           "to_name": "Coffee Brewing Methods"
>         }
>       ],
>       "created_at": "2025-03-06T14:01:23.445071",
>       "updated_at": "2025-03-06T13:34:48.563606"
>     }
>   ]
> }
> ```

Basic Memory understands how to build context via its semantic graph.

### Entity Model

Basic Memory's core data model consists of:

> [card] Entities
>
> Documents in your knowledge base

> [card] Observations
>
> Facts or statements about entities

> [card] Relations
>
> Connections between entities

> [card] Tags
>
> Additional categorization for entities and observations

The system parses Markdown files to extract this structured information while preserving the human-readable format.

### Files as Source of Truth

Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git.

```mermaid theme={null}
flowchart TD
    User((User)) <--> |Conversation| Claude["Claude or other LLM"]
    Claude <-->|API Calls| BMCP["Basic Memory MCP Server"]
    
    subgraph "Local Storage"
        KnowledgeFiles["Markdown Files - Source of Truth"]
        KnowledgeIndex[(Knowledge Graph SQLite Index)]
    end
    
    BMCP <-->|"write_note() read_note()"| KnowledgeFiles
    BMCP <-->|"search_notes() build_context()"| KnowledgeIndex
    KnowledgeFiles <-.->|Sync Process| KnowledgeIndex
    KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git))
    
    User -.->|"Complete control, Privacy preserved"| KnowledgeFiles
    
    
    class Claude primary
    class BMCP secondary
    class KnowledgeFiles tertiary
    class KnowledgeIndex quaternary
    class User,Editors user
```

### SQLite Database

A local SQLite database maintains the knowledge graph topology for fast queries and semantic traversal without cloud dependencies. It contains:

> [card] Knowledge Graph Schema
>
> Database tables for the knowledge graph structure

> [card] Search Index
>
> Full text search index across the knowledge base

### Sync Process

The sync process:

**1. Detect Changes**

Detects changes to files in the knowledge directory

**2. Parse Files**

Parses modified files to extract structured data

**3. Update Database**

Updates the SQLite database with changes

**4. Resolve References**

Resolves forward references when new entities are created

**5. Update Search Index**

Updates the search index for fast querying

### Search Engine

The search functionality:

> [card] Hybrid Search
>
> Uses a combination of full-text search and semantic matching

> [card] Comprehensive Indexing
>
> Indexes observations, relations, and content

> [card] Pattern Matching
>
> Supports wildcards and pattern matching in memory:// URLs

> [card] Graph Traversal
>
> Traverses the knowledge graph to follow relationships

> [!NOTE]
>
> Results are ranked by relevance to the query using advanced scoring algorithms.

## System Architecture

### Component Interaction

The Basic Memory system is built with a modular architecture:

> [tab] File Layer
>
> **Markdown Files** serve as the source of truth:
>
> * Human-readable and editable
> * Version control friendly
> * Standard format compatibility
> * Complete data ownership

> [tab] Processing Layer
>
> **Sync Service** processes changes:
>
> * File system monitoring
> * Markdown parsing
> * Entity extraction
> * Database updates

> [tab] Storage Layer
>
> **SQLite Database** provides:
>
> * Fast querying capabilities
> * Full-text search indexing
> * Relationship mapping
> * Metadata storage

> [tab] Interface Layer
>
> **MCP Server** exposes:
>
> * Standardized tool interface
> * Real-time data access
> * Secure authentication
> * Cross-platform compatibility

### Performance Characteristics

> [card] Local Performance
>
> All operations are local with no network latency

> [card] Scalability
>
> Handles knowledge bases with thousands of documents

> [card] Resource Efficiency
>
> Minimal CPU and memory footprint

## Development Philosophy

Basic Memory embodies several key principles:

> [!NOTE]
>
> **Core Principles:**
>
> * **Local-First**: Your data stays on your machine
> * **Open Standards**: Uses standard formats and protocols
> * **Human-Readable**: Everything is accessible without special tools
> * **AI-Native**: Designed specifically for AI collaboration
> * **Privacy-Preserving**: No data collection or tracking


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.