Reference

Technical Information

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

This page describes the architecture of the open-source Basic Memory project. Basic Memory Cloud builds on this foundation with hosted infrastructure and additional features.

Architecture

Basic Memory consists of:

Core Knowledge Engine — Parses and indexes Markdown files
Database — Provides fast querying and search
MCP Server — Implements the Model Context Protocol
CLI Tools — Command-line utilities for management
File Watcher — Monitors file changes and indexes 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 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:

Entities

Distinct concepts represented by Markdown documents

Observations

Categorized facts and information about entities

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

Resulting JSON Entity 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.

mermaid

Rendering diagram...

Database

The database maintains the knowledge graph topology for fast queries and semantic traversal. It contains:

Knowledge Graph Schema — Database tables for the knowledge graph structure
Search Index — Full text search index across the knowledge base

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 — The foundation of your knowledge base

Human-Readable — Edit with any text editor
Version Control Friendly — Works seamlessly with Git
Standard Format — Plain Markdown with YAML frontmatter
Complete Ownership — Your files, your control

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

Edit this pageorReport an issue

AI Assistant Guide

Guide for AI assistants using Basic Memory through the Model Context Protocol (MCP).

Troubleshooting

Common issues and solutions for Basic Memory.