Skip to main content

​
Architecture

Basic Memory consists of:

Core Knowledge Engine

Parses and indexes Markdown files

SQLite Database

Provides fast querying and search

MCP Server

Implements the Model Context Protocol

CLI Tools

Command-line utilities for management

Sync Service

Monitors file changes and updates the database
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, an open standard for enabling AI models to access external tools:

Standardized Interface

Common protocol for tool integration

Tool Registration

Basic Memory registers as a tool provider

Asynchronous Communication

Enables efficient interaction with AI models

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

Free Software

You can use, study, share, and modify the software

Copyleft

Derivative works must be distributed under the same license

Network Use

Network users must be able to receive the source code

Commercial Use

Allowed, subject to license requirements
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:

GitHub Repository

https://github.com/basicmachines-co/basic-memory

Issue Tracker

Report bugs and request features on GitHub

Contributions

Pull requests are welcome following the contributing guidelines

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

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

{
  "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:

Entities

Documents in your knowledge base

Observations

Facts or statements about entities

Relations

Connections between entities

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.

​
SQLite Database

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

Knowledge Graph Schema

Database tables for the knowledge graph structure

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:

Hybrid Search

Uses a combination of full-text search and semantic matching

Comprehensive Indexing

Indexes observations, relations, and content

Pattern Matching

Supports wildcards and pattern matching in memory:// URLs

Graph Traversal

Traverses the knowledge graph to follow relationships
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:
Markdown Files serve as the source of truth:
  • Human-readable and editable
  • Version control friendly
  • Standard format compatibility
  • Complete data ownership

​
Performance Characteristics

Local Performance

All operations are local with no network latency

Scalability

Handles knowledge bases with thousands of documents

Resource Efficiency

Minimal CPU and memory footprint

​
Development Philosophy

Basic Memory embodies several key principles:
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