Brein AI: Memory-First Offline Personal AI System
Abduljabbar Abdulghani
Tawakkul Labs · 20 July 2026
Open-source modular personal AI system with shared memory, multi-agent routing, and local inference. Runs offline using FAISS vector search, SQLite memory, and GGUF models.
Brein AI is a personal artificial intelligence system built to run entirely on the hardware you already own. It does not phone home. It does not require a subscription, a cloud account, or a reliable internet connection. Every model runs locally, every memory is stored locally, and every conversation stays on your device.
This design is not a limitation. It is the point. For builders across East Africa, where connectivity is expensive, intermittent, and increasingly a question of digital sovereignty, an AI that works fully offline is not a compromise. It is the difference between a tool that works when you need it and a tool that works only when the network allows it.
Why Memory First
Most AI assistants treat every conversation as a fresh start. You tell them something once, and the next day you tell them again. Brein AI inverts that assumption with a simple thesis: the value of a personal AI is not the model inside it, it is the memory of what you have told it.
Memory in Brein AI works on three layers. The first is a vector database powered by FAISS, which stores the meaning of every piece of content you ingest and retrieves it by similarity, not by exact keyword. The second is a persistent SQLite store that keeps the metadata of everything the system knows, so memories survive restarts, crashes, and model swaps. The third is a neural mesh, a lightweight associative layer that connects related memories to each other, the way a working memory connects to long term storage in a human brain.
Around these layers sits an LRU cache. When the system needs to answer a question, it first checks what it has recently used, then searches its permanent memory, and only then turns to the model. The result is an assistant that remembers your context for follow up questions, learns quietly in the background, and answers faster over time instead of slower.
Core Features
Memory First Architecture
- FAISS powered similarity search with SSD offload, so memory can scale to millions of vectors without loading everything into RAM.
- A neural mesh that builds basic associative connections between related memories.
- Hierarchical memory combining fast working memory with durable SQLite persistence.
- LRU caching that keeps frequently used knowledge hot and prunes what is no longer relevant.
The Agent Team
Brein AI does not use a single monolithic model. It routes work through a small team of specialized agents, each named for the brain region that inspires its job:
- The Hippocampus Agent handles memory encoding and ingestion. It decides what is worth remembering and writes it into the system.
- The Prefrontal Cortex Agent handles complex reasoning, but only when the query actually demands it, so simple questions stay fast and cheap.
- The Amygdala Agent drives personality and tone, generating responses through local GGUF models.
- The Thalamus Router sits in front of all of them, classifying every query by complexity and sending it to the right specialist.
This routing matters for one practical reason: running a large model for a trivial question wastes battery, time, and memory. By sending easy queries to light paths and hard ones to the full model, Brein AI stays responsive on hardware that would struggle with a single frontier model that is permanently active.
What We Removed and Why
Engineering honesty matters in a systems paper, so this section says plainly what was cut and why:
- The System Awareness Layer was disabled because it caused freezes during active sessions.
- Reinforcement learning was removed because memory consolidation through it proved unstable in daily use.
- Complex prompt management was replaced with simple hardcoded prompts, which are predictable and debuggable.
- The web content pipeline is defined but not yet implemented, and is gated behind a quarantine and review flow when it ships.
These are deliberate trades. The project prioritizes a system that stays up for weeks over one that theoretically does more but crashes in the middle of a workday.
Production Readiness
The current build is stable and useful today. It exposes a FastAPI REST API with conversational memory, supports GGUF models including Llama 3.2, Phi 3.1, and Hermes, maintains context across follow up messages, runs efficient similarity search over stored memory, and performs simple background learning from conversations.
System Architecture
The system is a layered architecture with three entry points and one brain. The entry points are a web interface built in HTML and JavaScript, the FastAPI REST API, and mobile applications built with React Native. All three feed into a single multi agent orchestrator, so every conversation, no matter the device, passes through the same routing and memory logic.
Below the orchestrator sit the four agents described earlier. Each agent reports into a central Memory Manager, which coordinates the three memory layers: FAISS for vectors, SQLite for metadata, and the neural mesh for associative links. Because the Memory Manager is the single point of truth, agents can be added, removed, or swapped without rewriting the memory system.
The architecture is intentionally shallow. There is no distributed queue, no message broker, no service mesh. There is one process, one brain, and one storage layer. That is what keeps it reliable on a laptop, a mini PC, or a refurbished desktop.
Frontend Interfaces
The web interface is the primary control surface. Four views cover the full workflow: the main interaction dashboard for conversations, the knowledge base view for managing ingested content, the neural mesh visualizer for inspecting how memories connect, and the system analytics dashboard for monitoring health and performance in real time. Because everything renders locally, the interface stays responsive even on weak connections, and the analytics view gives operators a live picture of what the system is doing.
Core System Architecture
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Web Interface │ │ REST API │ │ Mobile Apps │
│ (HTML/JS) │ │ (FastAPI) │ │ (React Native) │
│ │ │ │ │ │
└──────────────────────┘ └──────────────────────┘ └──────────────────────┘
│ │ │
└────────────────────────────────┴────────────────────────────────┘
┌──────────────────────┐
│ Orchestrator │
│ (Multi-Agent) │
│ │
└──────────────────────┘
│
│
────────────┬──────────────────────────┬────────────┼─────────────┬──────────────────────────┬───────────
│ │ │ │
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Hippocampus │ │ Prefrontal Cortex │ │ Amygdala │ │ Thalamus │
│ Memory │ │ Reason │ │ GGUF AI │ │ Routing │
│ │ │ │ │ │ │ │
└──────────────────────┘ └──────────────────────┘ └──────────────────────┘ └──────────────────────┘
│ │ │ │
────────────└──────────────────────────┴──────────────────────────┴──────────────────────────┘───────────
│
┌────────────────────────────────────────────────────────┐
│ FAISS │ SQLite │
│ (Vectors) │ (Metadata) │
├────────────────────────────────────────────────────────┤
│ Neural Mesh │ (Associative Learning) │
└────────────────────────────────────────────────────────┘
Simplified Agent Architecture
The production build runs a leaner team than the full design: the Hippocampus for core memory, the Amygdala driving GGUF generation, and the Thalamus for routing, all coordinated by the orchestrator and backed by the FAISS plus SQLite Memory Manager.
┌──────────────────────┐
│ Orchestrator │
│ (Query Router) │
│ │
└──────────────────────┘
│
────────────┬──────────────────────────┬──────────────────────────┬───────────
│ │ │
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ Hippocampus │ │ Amygdala │ │ Thalamus │
│ (Core Memory) │ │ (GGUF AI) │ │ (Routing) │
│ │ │ │ │ │
└──────────────────────┘ └──────────────────────┘ └──────────────────────┘
│ │ │
────────────└──────────────────────────┴──────────────────────────┘───────────
│
┌──────────────────────┐
│ Memory Manager │
│ (FAISS + SQLite) │
│ │
└──────────────────────┘
Quick Start
Prerequisites
- Python 3.8 or newer
- Git
Installation
The fastest path is the automated installer, which clones the repository and configures the environment for you:
# Clone the repository
git clone https://github.com/AbduljabbarBXR/Brein-Ai.git
cd Brein-Ai
# Run the installer
python setup.py
Prefer explicit control? Use the manual path: create a virtual environment, install the dependency manifest, and launch the backend directly.
# Clone the repository and navigate into it
git clone https://github.com/AbduljabbarBXR/Brein-Ai.git
cd Brein-Ai
# Create and activate a virtual environment
python -m venv brein_env
source brein_env/bin/activate # On Windows use: brein_env\Scripts\activate
# Install the required dependencies
pip install -r requirements.txt
# Start the system
python backend/main.py
Usage
Starting the Server
Launch the backend from the project root:
python backend/main.py
The API listens on http://localhost:8000 by default, configurable through the server settings in config.json.
Accessing the Web Interface
With the server running, open frontend/index.html in any modern browser. No build step, no bundler, no server side rendering: the interface talks directly to the local API.
Making API Calls
Every capability of the system is reachable over HTTP. A minimal interaction, asking a question and receiving an answer with memory attached, looks like this:
import requests
# Define the API endpoint
url = "http://localhost:8000/api/query"
# Define the payload
payload = {
"query": "Explain machine learning in simple terms.",
"session_id": "user123"
}
# Send the POST request
response = requests.post(url, json=payload)
# Print the response
print(response.json())
The session_id field is the key to memory. Pass the same identifier across requests and the system carries conversation context between them. Omit it and each call is treated as a fresh session.
API Documentation
The API is organized into five groups: query processing, memory management, web content integration, device synchronization, and testing plus monitoring. The full reference lives in the project wiki; the core surface is documented below.
Core Endpoints
Query Processing
POST /api/query
Content-Type: application/json
{
"query": "Your question here",
"session_id": "optional_session_id",
"enable_web_access": false
}
Memory Management
GET /api/memory/stats # Get memory statistics
GET /api/memory/search?q=term # Search memory
POST /api/ingest # Ingest new content
Web Content Integration
POST /api/web/fetch # Fetch web content (with safety pipeline)
GET /api/web/quarantine/list # List quarantined content
POST /api/web/review # Approve/reject quarantined content
Device Synchronization
POST /api/sync/register-device # Register mobile device
POST /api/sync/delta # Get sync delta
POST /api/sync/apply-delta # Apply sync changes
Testing and Monitoring
POST /api/test/run-comprehensive # Run full test suite
POST /api/profiler/start # Start performance monitoring
GET /api/profiler/health # Get system health status
The quarantine flow on the web endpoints deserves emphasis. Content fetched from the web never enters memory directly: it lands in quarantine, is scored against a configurable trust list, and must be explicitly approved. This is the safety pipeline the roadmapped web feature will rely on, and it is already built into the API contract.
Configuration
System behavior is controlled by a single config.json at the installation root. The defaults are sensible for a private personal deployment, and every value can be changed without touching code.
{
"database": {
"path": "memory/brein_memory.db"
},
"models": {
"embedding_model": "all-MiniLM-L6-v2"
},
"server": {
"host": "127.0.0.1",
"port": 8000
},
"security": {
"web_access_default": false,
"audit_enabled": true
}
}
Two defaults are worth highlighting. The server binds to 127.0.0.1, so the system does not expose itself to the network unless you deliberately change the host. And web access defaults to disabled, which means the model answers from memory, not from whatever is currently trending online. Both decisions reflect the same principle: the system is private by default and open only by explicit choice.
Testing and Quality
The project ships a testing pipeline as part of the runtime itself. A single endpoint runs the comprehensive suite, which exercises the system against over a thousand documents to validate memory ingestion, retrieval, and conversational flow under realistic load.
curl -X POST http://localhost:8000/api/test/run-comprehensive
Performance is not an afterthought. The benchmark endpoint runs repeated iterations and reports the numbers you need to compare configurations:
curl -X POST http://localhost:8000/api/test/benchmark -d '{"iterations": 100}'
And when a deployment is live, the profiler turns the system inside out for inspection: start real time monitoring, then read current metrics whenever you need them.
# Start real-time monitoring
curl -X POST http://localhost:8000/api/profiler/start
# Get current metrics
curl http://localhost:8000/api/profiler/current
Performance Profile
Measured on a mid range consumer machine, the numbers are strong enough for daily use and honest about their limits:
- Memory ingestion runs at roughly 50 to 200 documents per second, depending on content length.
- Query processing averages 100 to 500 milliseconds end to end.
- The system comfortably supports 10 or more simultaneous queries.
- Memory scales to millions of vectors using SSD offload, so the working set is bounded by disk, not RAM.
- Storage cost is about one kilobyte per memory node, including vector and metadata.
Security and Privacy
Because Brein AI is local first, the security model starts from a strong position: the data never has to travel to be used. On top of that baseline, the system adds five explicit layers:
- Content sanitization strips malicious scripts and suspicious patterns from ingested material.
- Domain trust scoring maintains a configurable list of trusted sources.
- Audit trails record every operation and every routing decision, so behavior can be reviewed after the fact.
- Access controls provide granular permissions over web access and data operations.
- Data provenance tracks where each piece of content came from and how it was transformed.
For users managing sensitive or professionally confidential information, the combination of local inference and full provenance is the difference between a personal assistant and a data leak waiting to happen.
Mobile Deployment
The same server that runs on a laptop can extend to mobile devices. Two mechanisms make this work. First, models can be exported to TFLite bundles sized for phone hardware:
curl -X POST http://localhost:8000/api/models/export-mobile-bundle \
-d '{"bundle_name": "brein_mobile_v1"}'
Second, devices register with the server and synchronize memory deltas, so a phone and a laptop can share a single memory without either storing the whole database:
curl -X POST http://localhost:8000/api/sync/register-device \
-d '{
"device_id": "mobile_001",
"device_name": "iPhone 14",
"device_type": "mobile",
"capabilities": ["offline_mode", "sync"]
}'
The sync design is delta based by intention: the phone declares offline capability, receives only what changed, and keeps working when the network drops. This makes a phone a true extension of the assistant rather than a thin client for it.
Roadmap
Brein AI is a working system today and a foundation for more. The directions that matter most, in the order they matter:
- Restore a hardened web content pipeline using the quarantine and review flow already present in the API, so the assistant can responsibly incorporate fresh information.
- Bring back reinforcement learning for memory consolidation, but behind the stability work that made the first attempt unreliable, and off by default.
- Expand GGUF model support and automatic hardware detection, so the system selects the right model for the machine it runs on.
- Improve regional language coverage, with a focus on Swahili and other languages spoken across East Africa, since local models are one of the strongest arguments for local AI.
- Ship mobile applications to the app stores with full offline mode and background sync, completing the device story.
- Build community tooling around the memory format, so users can share curated memory packs the way they share plugins today.
The project treats reliability as a feature and memory as a moat. Every addition above is judged against one question: does it still run for a month without a freeze?
Contributing
Contributions are welcome. The workflow is a standard fork and pull request loop:
- Fork the repository
- Create a new feature branch
- Commit your changes with a descriptive message
- Push the branch to your fork
- Open a Pull Request
Acknowledgments
- FAISS, for efficient similarity search.
- Sentence Transformers, for text embedding models.
- FastAPI, for the REST API framework.
- SQLite, for metadata storage.
- BeautifulSoup, for web content parsing.
License
This project is licensed under the MIT License. See the LICENSE file for more details.