---
title: "Technical Information"
description: "Technical details about Basic Memory implementation, architecture, licensing, and Model Context Protocol integration"
canonical_url: "https://docs.basicmemory.com/reference/technical-information"
---
# Technical Information

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

<note>

This page describes the architecture of the open-source [Basic Memory](https://github.com/basicmachines-co/basic-memory) project. [Basic Memory Cloud](https://docs.basicmemory.com/cloud/cloud-guide) builds on this foundation with hosted infrastructure and additional features.

</note>

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

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

</note>

## Model Context Protocol (MCP)

Basic Memory implements the [Model Context Protocol](https://modelcontextprotocol.io), 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)](https://www.gnu.org/licenses/agpl-3.0.en.html):

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

<note>

The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks.

</note>

## Source Code

Basic Memory is developed as an open-source project:

- **GitHub Repository** — [https://github.com/basicmachines-co/basic-memory](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:

<note>

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

</note>

## Implementation Details

Knowledge in Basic Memory is organized as a semantic graph:

<steps>

### Entities

Distinct concepts represented by Markdown documents

### Observations

Categorized facts and information about entities

### Relations

Connections between entities that form the knowledge graph

### Tags

Additional categorization for entities and observations

</steps>

This structure emerges from simple text patterns in standard Markdown. The example below is saved as `Coffee Notes/Coffee Brewing Methods.md` — its frontmatter sets an explicit `permalink`, which overrides the path-derived one:

### Example Markdown Input

```markdown
---
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]]
```

### Resulting JSON Entity Structure

```json
{
  "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-brewing-methods",
          "to_id": "coffee/proper-grinding-technique",
          "relation_type": "requires",
          "permalink": "coffee/coffee-brewing-methods/requires/coffee/proper-grinding-technique",
          "to_name": "Proper Grinding Technique"
        },
        {
          "from_id": "coffee/coffee-brewing-methods",
          "to_id": "coffee/flavor-extraction",
          "relation_type": "affects",
          "permalink": "coffee/coffee-brewing-methods/affects/coffee/flavor-extraction",
          "to_name": "Flavor Extraction"
        }
      ],
      "created_at": "2025-03-06T13:34:48.563606",
      "updated_at": "2025-03-06T14:01:23.445071"
    }
  ]
}
```

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

### 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 code="flowchart TD
User((User)) <--> |Conversation| Claude["Claude or other LLM"]
Claude <-->|API Calls| BMCP["Basic Memory MCP Server"]

KnowledgeFiles["Markdown Files - Source of Truth"]
KnowledgeIndex[(Knowledge Graph Index)]

BMCP <-->|"bm_write() bm_read()"| KnowledgeFiles
BMCP <-->|"bm_search() bm_context()"| KnowledgeIndex
KnowledgeFiles <-.->|Sync Process| KnowledgeIndex
KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git))

User -.->|"Complete control, Privacy preserved"| KnowledgeFiles
">



</mermaid>

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

### Sync Process

The sync process:

<steps>

### Detect Changes

Detects changes to files in the knowledge directory

### Parse Files

Parses modified files to extract structured data

### Update Database

Updates the database with changes

### Resolve References

Resolves forward references when new entities are created

### Update Search Index

Updates the search index for fast querying

</steps>

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

<note>

Results are ranked by relevance to the query using advanced scoring algorithms.

</note>

## System Architecture

### Component Interaction

The Basic Memory system is built with a modular architecture:

<tabs>
<div label="File Layer">

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

</div>

<div label="Processing Layer">

**Sync Service** — Keeps everything in sync

- **File Monitoring** — Watches for changes in real-time
- **Markdown Parsing** — Extracts structure from content
- **Entity Extraction** — Identifies entities, observations, relations
- **Database Updates** — Maintains the knowledge graph index

</div>

<div label="Storage Layer">

**Database** — Fast indexing

- **Fast Querying** — Optimized for knowledge graph queries
- **Full-Text Search** — Search across all content
- **Relationship Mapping** — Tracks entity connections
- **Metadata Storage** — Stores parsed entity information

</div>

<div label="Interface Layer">

**MCP Server** — AI integration layer

- **Standardized Tools** — a comprehensive set of MCP tools for AI access
- **Real-Time Access** — Live knowledge base queries
- **Secure Auth** — JWT-based authentication for cloud
- **Cross-Platform** — Works with Claude, VS Code, Cursor

</div>
</tabs>

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

<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

</note>

---

## Next Steps

<card-group>
<card icon="i-lucide-file-text" title="Knowledge Format" to="https://docs.basicmemory.com/concepts/knowledge-format">

The markdown patterns behind the entity model.

</card>

<card icon="i-lucide-settings" title="Configuration" to="https://docs.basicmemory.com/reference/configuration">

Every config field and environment variable.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.