Related Pages

Related topics: Core RAG Engine and Data Pipeline, Embedding, Reranking, and Model Providers, User Interfaces, Adapters, and Operations

Introduction to Localbrain

Localbrain is a local-first knowledge and context management library written in Python. It is designed to let developers assemble, persist, and recall structured "memory" fragments on the user's own machine, without requiring an external database server or cloud service. The repository exposes a small, composable Python package under the localbrain namespace, declared as a standard src-layout project and installable through pip once the project metadata has been built.

Purpose and Scope

The high-level purpose of Localbrain is to provide a lightweight, file-backed abstraction for storing and retrieving contextual information that an application — typically an LLM-powered assistant, a note-taking tool, or an agentic workflow — needs across sessions. The project deliberately avoids heavy infrastructure: there are no daemon processes, no required network calls, and no external services to provision. Instead, the package is intended to be imported directly into a host Python application.

Key properties derived from the project layout:

• Package layout: src/localbrain/ indicates a src-layout project, which enforces that the package can only be imported when installed, reducing accidental imports from the working tree. Source: pyproject.toml
• Public surface: src/localbrain/__init__.py is the package entry point and typically re-exports the most important classes and functions (such as LocalBrain, Context, and configuration helpers) so consumers can write from localbrain import ... instead of digging into submodules. Source: src/localbrain/__init__.py
• Scope: The codebase is intentionally narrow. The two substantive modules are config.py and context.py, suggesting that configuration handling and context (memory fragment) management are the two pillars of the system. Source: src/localbrain/config.py, src/localbrain/context.py

High-Level Architecture

Localbrain separates *what is stored* from *how it is configured and located*. Configuration is handled by a dedicated module, while the core data unit — a piece of contextual memory — lives in the context module. This separation lets the same in-memory model be backed by different on-disk strategies or paths, simply by changing configuration.

flowchart LR
    A[Host Application] --> B[localbrain.__init__]
    B --> C[localbrain.config]
    B --> D[localbrain.context]
    C --> E[(Local Storage)]
    D --> E
    D --> A

In this flow:

• The host application imports the package via localbrain.__init__. Source: src/localbrain/__init__.py
• It reads or supplies configuration from localbrain.config, which defines where data lives and how it is named. Source: src/localbrain/config.py
• It creates, queries, and mutates context objects through localbrain.context, which is the data-carrying layer. Source: src/localbrain/context.py
• Persistence targets local storage on the user's filesystem rather than a remote service. Source: README.md

Core Modules

Configuration (`config.py`)

The config module centralizes all paths, names, and tunable parameters used by the rest of the package. By isolating configuration in one place, Localbrain makes it easy to embed the library into different applications without scattering path constants throughout the codebase. Source: src/localbrain/config.py

Typical responsibilities of this module include:

• Defining the default root directory under which Localbrain stores its files.
• Specifying file naming conventions for context blobs or indexes.
• Exposing a configuration object or function that downstream modules read at runtime.

Context (`context.py`)

The context module is the heart of Localbrain. It defines the data structures that represent a unit of memory — typically a timestamped, tagged, and content-bearing record — and the operations that can be performed on them: creation, lookup, update, and listing. Because the project is local-first, these operations are designed to be safe to call synchronously and to remain available even when offline. Source: src/localbrain/context.py

Package Entry (`__init__.py`)

The __init__.py file is intentionally kept thin. Its job is to make the most useful symbols importable directly from localbrain, so a developer can start using the library with minimal boilerplate. It is also the natural place to declare the package's public API contract. Source: src/localbrain/__init__.py

Installation and Distribution

Localbrain uses a standard pyproject.toml-based build configuration, which means it can be installed with modern Python packaging tools. The src-layout ensures that pip install . from the repository root produces a clean, importable package without namespace collisions with the source tree. Source: pyproject.toml

The README provides the human-oriented entry point: it explains the project's motivation, lists basic usage examples, and points to the modules described above. Anyone onboarding to Localbrain should read the README first, then follow the import paths back into config.py and context.py to understand how the pieces fit together. Source: README.md

When to Use Localbrain

Localbrain is well suited to scenarios where an application needs persistent, structured memory that:

1. Must remain available offline.
2. Should not depend on a managed database or cloud API.
3. Is small enough to live comfortably on a single machine's filesystem.
4. Needs to be embedded directly into a Python process rather than accessed over the network.

For larger, multi-user, or horizontally scaled workloads, a dedicated database system would be more appropriate. Localbrain's value lies precisely in its small surface area, predictable local behavior, and tight integration with the host Python application. Source: README.md

Related Pages

Related topics: Introduction to Localbrain, Embedding, Reranking, and Model Providers, User Interfaces, Adapters, and Operations

Core RAG Engine and Data Pipeline

1. Purpose and Scope

The Core RAG Engine and Data Pipeline is the ingestion backbone of Localbrain. It is responsible for turning raw, on-disk user files into normalized, chunked units that downstream retrieval and generation components can consume. The pipeline runs locally, never streaming source documents off-device, which matches the project's privacy-first positioning.

The pipeline is composed of three cooperating modules located under src/localbrain/core/:

• A scanner that walks the file system and discovers candidate files.
• A set of loaders, registered through a central registry, that convert raw bytes into typed Document objects.
• A chunker that splits documents into retrieval-sized segments.

file_index.py sits between the scanner and the loaders, giving the pipeline a persistent view of what has already been seen and processed. Source: src/localbrain/core/scanner.py:1-1, src/localbrain/core/file_index.py:1-1, src/localbrain/core/chunking.py:1-1.

2. File Discovery and Indexing

2.1 Scanner

scanner.py exposes the entry point for discovering content. It traverses a configurable root path, applies include/exclude filters, and yields file metadata (path, size, mtime, extension) that downstream stages need to decide whether a file is indexable.

Source: src/localbrain/core/scanner.py:1-1.

2.2 File Index

file_index.py persists the result of scanning so that re-runs are incremental rather than full rebuilds. It stores stable identifiers for each file along with a content fingerprint, allowing the loader stage to skip unchanged files and reprocess only modified or newly added ones.

flowchart LR
    A[Root Path] --> B[scanner.py<br/>walk + filter]
    B --> C[file_index.py<br/>fingerprint + dedupe]
    C --> D{Loader<br/>registry}
    D --> E[base.py<br/>Document schema]
    D --> F[text_loader.py<br/>plain text I/O]
    E --> G[chunking.py<br/>segment into chunks]
    F --> G
    G --> H[(Downstream<br/>retrieval store)]

Source: src/localbrain/core/file_index.py:1-1, src/localbrain/core/loaders/registry.py:1-1.

3. Loader Layer

3.1 Base Loader Contract

loaders/base.py defines the abstract Loader interface. Every concrete loader must implement a method that takes a file path and returns a Document object carrying both the raw text and the provenance metadata required for citation downstream (source path, loader name, etc.). Centralizing this contract makes the pipeline pluggable: new formats only require a new subclass.

Source: src/localbrain/core/loaders/base.py:1-1.

3.2 Text Loader

loaders/text_loader.py is the concrete implementation for plain-text and similar readable formats. It handles encoding detection and basic normalization (stripping null bytes, normalizing line endings) before handing the result back as a Document produced by base.py.

Source: src/localbrain/core/loaders/text_loader.py:1-1, src/localbrain/core/loaders/base.py:1-1.

3.3 Loader Registry

loaders/registry.py is the dispatch table. Given a file path or MIME type, it selects the correct Loader implementation. This indirection means chunking.py and the rest of the pipeline never need to know which loader handled a file — they only consume uniform Document objects.

Source: src/localbrain/core/loaders/registry.py:1-1.

4. Chunking

Once a document is loaded, chunking.py splits it into smaller pieces suitable for embedding and retrieval. The chunker is configured by size and overlap parameters and emits chunks that preserve the parent document's metadata so that answers can later be traced back to the originating file and span.

Key responsibilities:

• Window-based splitting with configurable overlap to preserve context across chunk boundaries.
• Propagation of source metadata from the Document returned by the loaders onto each chunk.
• Stable ordering so embeddings and vectors stay consistent across re-index runs.

Source: src/localbrain/core/chunking.py:1-1, src/localbrain/core/loaders/base.py:1-1.

5. End-to-End Data Flow

The contract between stages is deliberately narrow: each stage hands the next a single, well-typed value (FileRecord, Document, Chunk). This makes the pipeline easy to test in isolation and easy to extend — adding a new file format means adding one loader class and registering it, with no changes to scanning, indexing, or chunking. Source: src/localbrain/core/scanner.py:1-1, src/localbrain/core/file_index.py:1-1, src/localbrain/core/loaders/base.py:1-1, src/localbrain/core/loaders/text_loader.py:1-1, src/localbrain/core/loaders/registry.py:1-1, src/localbrain/core/chunking.py:1-1.

6. Design Notes

• Locality. No network calls exist in this layer; scanning, loading, and chunking all operate on local files and in-process data structures.
• Incrementality. file_index.py fingerprints files so unchanged content is skipped on re-ingest.
• Extensibility. New formats are added by subclassing the base Loader and registering the implementation in registry.py.
• Provenance. Both the loader layer and the chunker preserve source metadata, which is what allows later answers to be cited back to the original file and span.

Related Pages

Related topics: Introduction to Localbrain, Core RAG Engine and Data Pipeline, User Interfaces, Adapters, and Operations

Embedding, Reranking, and Model Providers

The Localbrain project ships a pluggable model-provider layer under src/localbrain/core/embed/ (for embedding models) and src/localbrain/core/rerank/ (for reranking models). Its purpose is to isolate the rest of the application — retrieval pipelines, indexing jobs, and the CLI/RPC surfaces — from the specific inference backend in use. A consumer asks for vectors or rerank scores through abstract base classes, and the registry resolves the request to a concrete provider such as FastEmbed, Ollama, or SentenceTransformers.

1. Embedding Provider Architecture

1.1 Abstract Base Contract

src/localbrain/core/embed/base.py defines the abstract embedding interface that every concrete provider must satisfy. The base class establishes the expected method shape (typically embed_documents for batched indexing input and embed_query for retrieval-time vectors) and any shared configuration objects or return types consumed downstream by the vector store and retriever layers.

Source: src/localbrain/core/embed/base.py:1-120

1.2 Provider Registry

src/localbrain/core/embed/registry.py centralizes provider discovery and instantiation. Rather than hard-coding FastEmbedProvider() or OllamaProvider() at call sites, application code consults the registry by name and receives a configured instance. This is what allows Localbrain's configuration files (or environment-driven selection) to swap backends without code changes and keeps provider construction side-effect free for tests.

Source: src/localbrain/core/embed/registry.py:1-80

2. Concrete Embedding Providers

Localbrain currently exposes three backends, each implemented as a thin adapter over its underlying library. All three implement the same base contract from §1.1, so they are interchangeable from the perspective of the indexing and retrieval code paths.

2.1 FastEmbed Provider

fastembed_provider.py wraps the FastEmbed library, which performs CPU-friendly ONNX inference. This provider is the default for local/offline operation because it requires no external services and bundles model weights from disk on first use.

Source: src/localbrain/core/embed/fastembed_provider.py:1-150

2.2 Ollama Provider

ollama_provider.py talks to a local or remote Ollama server over HTTP, requesting embeddings via the model's /v1/embeddings (or native Ollama) endpoint. It is used when the operator wants to leverage a GPU-hosted model that is already managed by Ollama, instead of loading weights in-process.

Source: src/localbrain/core/embed/ollama_provider.py:1-150

2.3 SentenceTransformers Provider

st_provider.py integrates the SentenceTransformers library, which is the canonical reference implementation for transformer-based sentence embeddings in the Python ecosystem. It supports the broadest range of models and is typically chosen when the user specifies a HuggingFace model identifier not packaged by FastEmbed.

Source: src/localbrain/core/embed/st_provider.py:1-150

Provider Comparison

3. Reranking Abstraction

src/localbrain/core/rerank/base.py defines a parallel abstract interface for cross-encoder rerankers. Where embedding providers compress queries and documents into a shared vector space for fast retrieval, rerankers receive (query, candidate) pairs and return a calibrated relevance score that is used to reorder the top-K results returned by the vector store.

The base module in this directory establishes the contract (input shape, return type, scoring semantics) so that future reranker implementations — local cross-encoders, Ollama-routed rerank models, cloud APIs — can be added without modifying retrieval code. Concrete reranker adapters are expected to live alongside this base file under src/localbrain/core/rerank/ (e.g. fastembed_rerank.py, ollama_rerank.py) following the same pattern used by the embedding providers in §2.

Source: src/localbrain/core/rerank/base.py:1-120

4. Component Interaction Flow

flowchart LR
    A[Application / Retriever] --> B[embed.registry]
    B --> C[FastEmbedProvider]
    B --> D[OllamaProvider]
    B --> E[SentenceTransformersProvider]
    A --> F[rerank.base]
    F --> G[Reranker implementations]
    C --> H[(Vector Store)]
    D --> H
    E --> H
    H --> F
    F --> A

A typical two-stage retrieval flow is:

1. The retriever calls embed_registry.get(...) to obtain a configured provider and encodes the query.
2. The vector store returns candidate documents using ANN search.
3. The candidates are passed to a reranker implementing rerank.base, which rescores them.
4. Final ordered results are returned to the caller.

Summary

The Embedding, Reranking, and Model Providers layer in Localbrain is a thin, well-factored abstraction over heterogeneous inference backends. The embed/base.py interface and embed/registry.py resolver together make embedding backends plug-and-play, while three concrete adapters — FastEmbed, Ollama, and SentenceTransformers — cover the most common local-and-remote deployment scenarios. The parallel rerank/base.py module extends the same pattern to second-stage scoring, ensuring the retrieval pipeline can remain backend-agnostic as new models are added.

Related Pages

Related topics: Introduction to Localbrain, Core RAG Engine and Data Pipeline, Embedding, Reranking, and Model Providers

User Interfaces, Adapters, and Operations

Localbrain exposes its core functionality through a thin, pluggable adapter layer. Three front-ends — a Command-Line Interface, a Model Context Protocol (MCP) server, and a Web server — share the same underlying configuration object so behavior stays consistent regardless of how a user reaches the system. This page documents the adapter architecture, each surface's scope, and the operations they expose.

Adapter Architecture Overview

The localbrain.adapters package is structured as a uniform namespace that re-exports each entry point. The package-level __init__.py aggregates the three front-ends so consumers can import them together, while the web sub-package keeps its server module isolated under localbrain/adapters/web/ for clearer separation of transport concerns.

localbrain/
└── adapters/
    ├── __init__.py        # Public re-exports for CLI, MCP, Web
    ├── cli.py             # CLI entry point
    ├── mcp_server.py      # MCP server entry point
    └── web/
        ├── __init__.py    # Web adapter facade
        └── server.py      # HTTP server implementation

All three adapters read from src/localbrain/config.py, which is the single source of truth for connection settings, paths, and feature toggles. This keeps each surface a thin translation layer rather than an independent configuration silo.

Source: src/localbrain/adapters/__init__.py:1-40 Source: src/localbrain/config.py:1-80

The Three User Surfaces

Command-Line Interface

cli.py provides an interactive terminal front-end. It parses arguments and sub-commands, then routes them to the same operation handlers used by the other adapters. The CLI is intended for local development, scripting, and CI automation where shell-native invocation is preferred.

Source: src/localbrain/adapters/cli.py:1-120

Model Context Protocol Server

mcp_server.py implements an MCP server, enabling external MCP-compatible clients (such as AI assistants and IDE plugins) to discover and invoke Localbrain operations as structured tools. It bridges remote tool-calling semantics to the local engine by exposing operation schemas and routing requests through the same core handlers used elsewhere.

Source: src/localbrain/adapters/mcp_server.py:1-150

Web Server

The web surface is split across two files: web/server.py contains the HTTP request handling and routing logic, while web/__init__.py acts as the adapter facade that re-exports the server object for top-level import parity with cli and mcp_server. This dual structure lets the HTTP layer evolve without changing the public adapter namespace.

Source: src/localbrain/adapters/web/server.py:1-200 Source: src/localbrain/adapters/web/__init__.py:1-30

Operation Flow and Configuration

Operations flow through the adapters in a consistent pattern:

1. The adapter parses the incoming request (CLI flags, MCP tool call, or HTTP payload).
2. It reads the relevant settings from localbrain.config.
3. It dispatches the operation to the underlying handler.
4. Results are serialized back into the adapter's native response format.

Because config.py is shared, toggling a feature (for example, switching model provider, changing a server host, or pointing to a different data directory) takes effect uniformly across all three surfaces without code changes inside the adapters themselves.

Source: src/localbrain/config.py:1-120 Source: src/localbrain/adapters/cli.py:120-200

The table below summarizes adapter responsibilities:

Scope and Boundaries

The adapter layer is intentionally narrow. It does not implement business logic; it only translates inbound messages into handler calls and shapes outbound responses. Persistent state, indexing, and inference orchestration live outside this layer. When extending Localbrain with a new transport (for example, a gRPC or Slack adapter), the convention is to add a sibling module under localbrain/adapters/, re-export it from __init__.py, and reuse config.py so the new surface inherits the existing operational settings.

Source: src/localbrain/adapters/__init__.py:1-60 Source: src/localbrain/adapters/web/__init__.py:1-30

This minimal coupling keeps each front-end small, testable in isolation, and replaceable without rewriting the core engine.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Tamariskwhisper962/Localbrain

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Tamariskwhisper962/Localbrain

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Tamariskwhisper962/Localbrain

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Tamariskwhisper962/Localbrain

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Tamariskwhisper962/Localbrain

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Tamariskwhisper962/Localbrain

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Tamariskwhisper962/Localbrain

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Localbrain with real data or production workflows.

• Configuration risk requires verification - GitHub / issue