🧠 myBrAIn — MCP Ecosystem

Deterministic, Idempotent, Context-Aware Second Brain for Google Antigravity.

Introduction

myBrAIn is an MCP (Model Context Protocol) server designed to provide persistent and contextual memory to language models (like Google Antigravity). It acts as a "second brain" for your development environment, allowing the AI to remember project rules, architectural decisions, and technical insights across different chat sessions.

System Architecture

The system is divided into three main components:

• Core: Manages persistence (db.py) and analytical intelligence (analyzer.py) for extracting insights from code.
• Server: The standard MCP interface (server.py) that allows Antigravity to interact with the brain.
• Admin UI: A premium dashboard (admin.py) based on Streamlit to visualize, manage, and debug stored memories with advanced features like Knowledge Graphs, Memory Export, and the Silent Observer dashboard.
• Observer: A background daemon thread (observer.py) that monitors codebase drift in real-time.

🏗 Installation

A. Docker Deployment (Recommended)

The easiest way to run myBrAIn is using Docker Compose.

# Clone & Prepare
git clone https://github.com/lilium360/myBrAIn.git
cd myBrAIn
cp .env.example .env

# Spin up
docker compose up -d

The Admin UI will be available at: [http://localhost:8501](http://localhost:8501)

B. Local Installation (Native Python)

1. Clone & Enter:

```bash

git clone https://github.com/lilium360/myBrAIn.git

cd myBrAIn

```

1. Setup Environment:

* Windows: python -m venv venv && .\venv\Scripts\activate

* Unix: python3 -m venv venv && source venv/bin/activate

1. Install: pip install -r requirements.txt

🚀 Usage Guide

1. Launching the Admin Dashboard

To graphically manage the database and visualize insights:

• Via Docker: Already running after docker compose up. Open http://localhost:8501.
• Via Python: Run streamlit run admin.py (or python -m streamlit run admin.py).

2. Integration in IDEs (Cursor, VS Code + Antigravity)

Add this to your mcpServers configuration JSON:

Option A: Via Docker

{
  "mcpServers": {
    "mybrain": {
      "command": "docker",
      "args": ["exec", "-i", "mybrain-admin", "python", "server.py"],
      "env": {
        "MYBRAIN_DATA_DIR": "/data/mybrain"
      }
    }
  }
}

Option B: Via Python (Local)

{
  "mcpServers": {
    "mybrain": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/mybrain/server.py"]
    }
  }
}

[!IMPORTANT]

Change the path in args to the ABSOLUTE path on your machine.

🧠 Project Onboarding & Context

myBrAIn is specifically designed to handle "Project Onboarding" — a process where the AI analyzes your current codebase and stores its architectural DNA.

How to Onboard a New Project

Once you have the MCP server configured, simply use the following prompt:

"I want to perform a full onboarding of this project into your long-term memory. Sequentially perform: Structural Link, Stack Analysis, Architectural Analysis, Style Analysis, and Exclusion Analysis."

📝 Integration Protocol (MANDATORY for AI Agents)

To ensure the AI uses myBrAIn correctly and consistently, copy and paste the following instructions into your project's custom instructions or .cursorrules file:

# myBrAIn Integration Protocol (MANDATORY)

You are connected to **myBrAIn**, an MCP server that acts as your Long-Term Memory and "Single Source of Truth" for this project.
You MUST NEVER rely solely on the current chat context or your general knowledge when project-specific rules are saved.

Strictly follow this operational cycle for EVERY interaction:

## 1. RECALL PHASE (Before Reasoning)
BEFORE generating any code or technical response, you MUST consult the memory:
- **Action:** Run `recall_context` using relevant keywords (e.g., "auth logic", "styling conventions", "api patterns").
- **Goal:** Retrieve the tech stack, architectural rules, and standard components already defined.
- **Constraint:** If you find an existing rule or component (e.g., "Always use `CustomButton`"), you MUST use it. Creating duplicates or unauthorized variations is FORBIDDEN.

## 2. CONSISTENCY PHASE (During Reasoning)
While generating the response:
- Strictly adhere to retrieved Constraints.
- If the user requests something that violates a saved rule (e.g., "Use jQuery" in a React project saved as "No jQuery"), warn the user of the conflict before proceeding.
- Use the code style (naming, comments, structure) retrieved from memory to maintain uniformity.

## 3. MEMORIZATION PHASE (During/After Action)
Your task is to keep the memory alive and updated. DO NOT wait for the user to ask.
Use `store_insight` proactively in the following cases:
- **New Decisions:** If a new architectural rule is established (e.g., "From now on, use only Tailwind").
- **New Patterns:** If you write a reusable generic component, save it as a "Standard Component".
- **Corrections:** If the user corrects your error, save the correction (e.g., "Do not use library X because it's buggy").
- **Onboarding:** If you detect a new empty project, propose or run `initialize_workbase`.

## 4. CONFLICT MANAGEMENT
- **myBrAIn Priority:** If your general knowledge suggests "X" but myBrAIn says "Y", the correct answer is "Y".
- **Updates:** If an old memory is obsolete, use `store_insight` to overwrite it (the system handles semantic collision automatically via `replace_id`).

---
**Correct Workflow Example:**
User: "Create a login page."
AI (Internal Thought): "Check myBrAIn for 'login', 'auth', 'ui components'."
AI Action: `recall_context("login auth ui style")`
AI (Found): "The project uses NextAuth and Shadcn components."
AI Response: Generates code using EXACTLY NextAuth and Shadcn, without inventing custom CSS unless necessary.
AI Action (Post): Since a new useful auth hook was created, run `store_insight` to save it.

Available Tools

• initialize_workbase: Link a directory to the brain.
• store_insight: Manually save a rule or context.
• recall_context: Retrieve relevant memories for the current task.
• critique_code: Validate code against stored architectural rules.
• audit_codebase: Scan the entire codebase for architectural drift and contradictions.

Advanced Configuration

You can customize the system behavior via environment variables (in Docker) or by modifying core/config.py.

🗂️ Admin Dashboard Features (v1.1)

The refactored Admin Dashboard includes:

• Card-Based Explorer: Browse memories in a modernized grid with colored tags for rules, context, and constraints.
• Knowledge Graph: Interactively visualize the semantic relationships and categorical clusters of your brain.
• Bulk Operations: Select multiple records for simultaneous deletion or quick editing.
• Silent Observer Dashboard: Real-time status monitoring of the background drift detection engine.
• Memory Management: Export full brain dumps or workbase-specific JSONs; import and reassign knowledge packets between projects.
• Workbase Management: Securely manage project data with a confirmation-protected destruction mechanism.

🔮 Roadmap

• [ ] Semantic Roadmap: Internal task planner to maintain context on long-term goals and feature progress.
• [x] Memory Import/Export: Share your "brain" with your team (Granular & Targetable).
• [x] Silent Observer: Background daemon that scans code and detects architectural drift.
• [x] Docker Support
• [x] Admin UI with Knowledge Graph