## Asset Header

- **Asset ID:** SOP-EL-R100X-Guia-Setup-BrainOS-v01
- **Version:** v01
- **Status:** Draft
- **Owner:** Victor Heredia
- **IntellBank:** IB-EL-EmpowerLabs
- **Tipo:** SOP — Standard Operating Procedure
- **Propósito:** Guía de Instalación — Tu BrainOS (Memoria Persistente para Tu Sherpa IA)
- **Última actualización:** 2026-04-11

---

# Guía de Instalación — Tu BrainOS (Memoria Persistente para Tu Sherpa IA)
## Re100X-Guia-Setup-BrainOS-v01

---


---

## ¿Qué vas a construir y por qué importa?

Imagina que cada vez que hablas con una IA (Claude, ChatGPT, Gemini), esa IA recuerda todo lo que le has dicho antes — tus decisiones, tus proyectos, tu forma de pensar, tus compromisos. No porque la plataforma lo guarde (eso depende de ellos y pueden borrarlo cuando quieran), sino porque **tú tienes tu propia base de datos personal** donde se almacena todo.

Eso es un BrainOS: **tu memoria digital soberana.** Es tuya, vive en tu cuenta, y cualquier IA puede leer de ella y escribir en ella.

**En términos simples:** vas a crear una "bodega de pensamientos" en la nube, y vas a darle a tus IAs la llave para que puedan guardar cosas ahí y buscarlas cuando las necesites.

### Lo que vas a necesitar

| Servicio | Qué es en lenguaje simple | Costo |
|----------|--------------------------|-------|
| **Supabase** | Una base de datos en la nube. Piensa en ella como un Excel muy poderoso que vive en internet y que las IAs pueden consultar. | Gratis (el tier gratuito es más que suficiente) |
| **OpenRouter** | Un "traductor universal" que permite que tu base de datos entienda el significado de lo que guardas, no solo las palabras exactas. | ~$5 USD (duran meses de uso normal) |

### Los 8 pasos del proceso

| Paso | Qué haces | Dónde | Tiempo |
|------|-----------|-------|--------|
| 1 | Crear tu proyecto Supabase | supabase.com (navegador) | 3 min |
| 2 | Configurar la base de datos | Supabase dashboard (navegador) | 5 min |
| 3 | Guardar tus credenciales de conexión | Supabase dashboard (navegador) | 2 min |
| 4 | Crear cuenta OpenRouter + API key | openrouter.ai (navegador) | 3 min |
| 5 | Generar tu clave de acceso | Terminal (Mac) o PowerShell (Windows) | 2 min |
| 6 | Desplegar el servidor MCP | Terminal / PowerShell | 15 min |
| 7 | Conectar a Claude Desktop y/o ChatGPT | Cada app respectiva | 5 min |
| 8 | Probar que funciona | Claude Desktop o ChatGPT | 5 min |

---

## ANTES DE EMPEZAR — Descarga el Credential Tracker

> **¿Qué es esto?** Es una hoja de Excel donde vas a ir anotando todas las contraseñas, claves y URLs que generes durante el proceso. Algunas de estas claves **solo se muestran una vez** — si no las guardas inmediatamente, tendrás que empezar de nuevo.

📥 **[Descargar Credential Tracker (.xlsx)](https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/docs/BrainOS-credential-tracker.xlsx)**

Ábrelo ahora. Déjalo abierto. Llénalo conforme avanzas.

---

## PASO 1 — Crear tu proyecto Supabase

### ¿Qué es Supabase? (Para no-técnicos)

Supabase es como rentar un pequeño almacén digital en la nube. Ahí vas a guardar tus pensamientos, decisiones, ideas y contexto. Lo especial de este almacén es que tiene "búsqueda inteligente" — puede encontrar cosas por su significado, no solo por las palabras exactas que usaste.

### Acciones

1. Ve a [supabase.com](https://supabase.com) y crea una cuenta (el login con GitHub es el más rápido, pero puedes usar email)
2. Una vez dentro del dashboard, haz clic en **New Project**
3. Elige tu organización (la que viene por default está bien)
4. Ponle nombre al proyecto: `BrainOS`
5. **IMPORTANTE:** Genera una contraseña de base de datos → **cópiala inmediatamente al Credential Tracker**
6. Elige la región más cercana a ti (ej: East US si estás en CDMX)
7. Haz clic en **Create new project** — espera 1-2 minutos

### ¿Qué buscar para confirmar que funcionó?

Cuando el proyecto esté listo, verás un dashboard con menú a la izquierda. En la URL de tu navegador verás algo como:

```
supabase.com/dashboard/project/abcxyz123
```

Esa parte random (`abcxyz123`) es tu **Project ref**. Cópiala al Credential Tracker.

### Status de Victor

> *(Se irá llenando conforme avancemos)*
> - [ ] Cuenta Supabase creada
> - [ ] Proyecto "BrainOS" creado
> - [ ] Database password guardado en tracker
> - [ ] Project ref guardado en tracker

---

## PASO 2 — Configurar la base de datos

### ¿Qué estamos haciendo? (Para no-técnicos)

Acabas de crear el "almacén". Ahora necesitas instalar los "estantes" — definir cómo se va a organizar la información adentro. Son 4 comandos SQL que se copian y pegan uno por uno. No necesitas entender el código — solo copiarlo y hacer clic en "Run".

**Analogía:** Es como cuando compras un archivero nuevo y le pones las divisiones y las etiquetas antes de empezar a guardar carpetas.

### 2.1 — Activar la extensión de vectores

En el menú izquierdo del dashboard de Supabase: **Database → Extensions** → busca "vector" → activa **pgvector** (flip el switch ON).

> **¿Para qué sirve?** Esto permite que tu base de datos entienda "significados", no solo texto. Es lo que hace posible que busques "criterios para rechazar proyectos" y encuentre un pensamiento que dice "No acepté el trabajo de María porque requería viajar demasiado."

### 2.2 — Crear la tabla de pensamientos

En el menú izquierdo: **SQL Editor → New query** → pega el siguiente código y haz clic en **Run**:

```sql
-- Crear la tabla de pensamientos
create table thoughts (
  id uuid default gen_random_uuid() primary key,
  content text not null,
  embedding vector(1536),
  metadata jsonb default '{}'::jsonb,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Índice para búsqueda semántica rápida
create index on thoughts
  using hnsw (embedding vector_cosine_ops);

-- Índice para filtrar por metadata
create index on thoughts using gin (metadata);

-- Índice para consultas por fecha
create index on thoughts (created_at desc);

-- Auto-actualizar la fecha de modificación
create or replace function update_updated_at()
returns trigger as $$
begin
  new.updated_at = now();
  return new;
end;
$$ language plpgsql;

create trigger thoughts_updated_at
  before update on thoughts
  for each row
  execute function update_updated_at();
```

> **¿Qué acaba de pasar?** Creaste una "tabla" llamada `thoughts` con 6 columnas: un ID único, el texto del pensamiento, su representación semántica (el "significado" en números), metadata (etiquetas automáticas), y dos fechas. También creaste 3 índices que hacen las búsquedas rápidas, y un mecanismo que actualiza automáticamente la fecha cuando modificas algo.

### 2.3 — Crear la función de búsqueda

Nueva query → pega y Run:

```sql
create or replace function match_thoughts(
  query_embedding vector(1536),
  match_threshold float default 0.7,
  match_count int default 10,
  filter jsonb default '{}'::jsonb
)
returns table (
  id uuid,
  content text,
  metadata jsonb,
  similarity float,
  created_at timestamptz
)
language plpgsql
as $$
begin
  return query
  select
    t.id,
    t.content,
    t.metadata,
    1 - (t.embedding <=> query_embedding) as similarity,
    t.created_at
  from thoughts t
  where 1 - (t.embedding <=> query_embedding) > match_threshold
    and (filter = '{}'::jsonb or t.metadata @> filter)
  order by t.embedding <=> query_embedding
  limit match_count;
end;
$$;
```

> **¿Qué acaba de pasar?** Creaste la función de "búsqueda inteligente". Cuando le preguntes a tu IA "¿qué decidí sobre X?", esta función compara el significado de tu pregunta con el significado de todos tus pensamientos guardados, y devuelve los más parecidos — ordenados por relevancia.

### 2.4 — Configurar seguridad

Nueva query → pega y Run:

```sql
alter table thoughts enable row level security;

create policy "Service role full access"
  on thoughts
  for all
  using (auth.role() = 'service_role');
```

> **¿Qué acaba de pasar?** Activaste la seguridad. Solo tu servidor (con tu clave secreta) puede leer y escribir en la tabla. Nadie más puede acceder a tus pensamientos.

### 2.5 — Otorgar permisos

Nueva query → pega y Run:

```sql
grant select, insert, update, delete on table public.thoughts to service_role;
```

> **¿Qué acaba de pasar?** Le diste permiso explícito a tu servidor para leer, escribir, actualizar y borrar pensamientos. Sin esto, el servidor recibiría un error de "permiso denegado".

### ¿Cómo verificar que todo funcionó?

Ve a **Table Editor** en el menú izquierdo. Deberías ver la tabla `thoughts` con las columnas: id, content, embedding, metadata, created_at, updated_at. Si la ves, todo está bien.

### Status de Victor

> - [ ] pgvector activado
> - [ ] Tabla `thoughts` creada (visible en Table Editor)
> - [ ] Función `match_thoughts` creada (visible en Database → Functions)
> - [ ] Row Level Security activada
> - [ ] Permisos otorgados

---

## PASO 3 — Guardar tus credenciales de conexión

### ¿Qué estamos haciendo? (Para no-técnicos)

Necesitas dos "llaves" para que tu servidor pueda hablar con tu base de datos: la dirección (URL) y la clave secreta. Es como anotar la dirección de tu almacén y hacer una copia de la llave.

### Acciones

En el menú izquierdo: **Settings** (ícono de engrane) → **API Keys**

Copia al Credential Tracker:

1. **Project URL** — Aparece arriba de la página bajo "Project URL"
2. **Secret key** — Baja hasta la sección **"Secret keys"** → copia la key `default`

> ⚠️ **Trata la Secret key como una contraseña.** Quien la tenga puede leer y escribir en tu base de datos. No la compartas ni la publiques.

### Status de Victor

> - [ ] Project URL guardada en tracker
> - [ ] Secret key guardada en tracker

---

## PASO 4 — Crear cuenta OpenRouter + API key

### ¿Qué es OpenRouter? (Para no-técnicos)

OpenRouter es un servicio que traduce texto a "vectores de significado" (embeddings). Cuando guardas un pensamiento, OpenRouter lo convierte en una representación matemática de su significado. Cuando buscas algo, hace lo mismo con tu pregunta y compara ambas representaciones. Así es como encuentra cosas por significado y no solo por palabras exactas.

**Analogía:** Si tu base de datos es la bodega, OpenRouter es el bibliotecario que sabe clasificar cada libro por su tema profundo, no solo por el título.

### Acciones

1. Ve a [openrouter.ai](https://openrouter.ai) y crea una cuenta
2. Ve a [openrouter.ai/keys](https://openrouter.ai/keys)
3. Haz clic en **Create Key**, nómbrala `BrainOS`
4. **Copia la key inmediatamente al Credential Tracker**
5. Ve a Credits y agrega $5 USD

### Status de Victor

> - [ ] Cuenta OpenRouter creada
> - [ ] API key generada y guardada en tracker
> - [ ] $5 USD en créditos agregados

---

## PASO 5 — Generar tu clave de acceso (MCP Access Key)

### ¿Qué estamos haciendo? (Para no-técnicos)

Tu servidor va a estar accesible por internet (así es como Claude y ChatGPT pueden hablarle). Necesitas una clave de acceso para que solo TÚ puedas usarlo. Es como ponerle contraseña a tu WiFi.

### Acciones

Abre la **Terminal** (Mac) o **PowerShell** (Windows) y ejecuta:

**Mac/Linux:**
```bash
openssl rand -hex 32
```

**Windows (PowerShell):**
```powershell
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
```

Te dará algo como: `a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1`

**Cópialo al Credential Tracker** bajo "MCP Access Key".

> **¿Cómo abrir la Terminal?**
> - **Mac:** Busca "Terminal" en Spotlight (Cmd + Espacio → escribe "Terminal")
> - **Windows:** Busca "PowerShell" en el menú de inicio

### Status de Victor

> - [ ] Terminal abierta
> - [ ] MCP Access Key generada y guardada en tracker

---

## PASO 6 — Desplegar el servidor MCP

### ¿Qué estamos haciendo? (Para no-técnicos)

Hasta ahora creaste la bodega (Supabase) y contrataste al bibliotecario (OpenRouter). Ahora vas a instalar la "puerta de entrada" — un pequeño servidor que recibe peticiones de tus IAs y las traduce en operaciones sobre tu base de datos. Se llama "servidor MCP" (Model Context Protocol).

**Analogía:** Es como instalar un recepcionista en la entrada de tu bodega que sabe atender a cualquier persona (Claude, ChatGPT, etc.) y sabe exactamente dónde guardar y dónde buscar las cosas.

### 6.1 — Crear carpeta del proyecto

Crea una carpeta nueva donde guardes tus proyectos (ej: Documentos/BrainOS).

En la Terminal, navega a esa carpeta:

```bash
cd /ruta/a/tu/carpeta/BrainOS
```

> **Tip:** En Mac, puedes arrastrar la carpeta desde Finder a la Terminal después de escribir `cd ` (con espacio).

### 6.2 — Instalar Supabase CLI

**Mac (con Homebrew):**
```bash
brew install supabase/tap/supabase
```

**Mac (sin Homebrew — instala Homebrew primero):**
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Luego cierra y reabre Terminal, y ejecuta el comando de arriba.

**Windows:**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```

Verifica que funcionó:
```bash
supabase --version
```

> **¿Qué es un CLI?** Es un programa que se usa desde la Terminal escribiendo comandos, en lugar de hacer clic en botones. No te preocupes — solo vas a copiar y pegar los comandos que te doy aquí.

### 6.3 — Conectar tu Terminal a Supabase

```bash
supabase login
```

Se abrirá tu navegador para autenticar. Sigue las instrucciones y regresa a la Terminal cuando diga "You are now logged in."

### 6.4 — Inicializar y vincular el proyecto

```bash
supabase init
```

Verifica que se creó la carpeta:
```bash
ls supabase/
```

Vincula con tu proyecto (reemplaza `YOUR_PROJECT_REF` con el valor de tu Credential Tracker):
```bash
supabase link --project-ref YOUR_PROJECT_REF
```

### 6.5 — Configurar las claves secretas

```bash
supabase secrets set MCP_ACCESS_KEY=tu-access-key-del-paso-5
```

```bash
supabase secrets set OPENROUTER_API_KEY=tu-openrouter-key-del-paso-4
```

> ⚠️ Asegúrate de que las claves coincidan EXACTAMENTE con lo que guardaste en el Credential Tracker.

### 6.6 — Descargar los archivos del servidor

Tres comandos, uno por uno:

```bash
supabase functions new BrainOS-mcp
```

```bash
curl -o supabase/functions/BrainOS-mcp/index.ts https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/server/index.ts
```

```bash
curl -o supabase/functions/BrainOS-mcp/deno.json https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/server/deno.json
```

Verifica que descargó correctamente:
```bash
head -1 supabase/functions/BrainOS-mcp/index.ts
```

✅ Debe mostrar: `import "jsr:@supabase/functions-js/edge-runtime.d.ts";`
❌ Si muestra: `console.log("Hello from Functions!")` — la descarga falló. Borra la carpeta y repite los 3 comandos.

### 6.7 — Desplegar

```bash
supabase functions deploy BrainOS-mcp --no-verify-jwt
```

Tu servidor ahora está vivo en:
```
https://YOUR_PROJECT_REF.supabase.co/functions/v1/BrainOS-mcp
```

Tu **MCP Connection URL** (la que usarás para conectar las IAs) es:
```
https://YOUR_PROJECT_REF.supabase.co/functions/v1/BrainOS-mcp?key=tu-access-key
```

Guarda ambas en el Credential Tracker.

### Status de Victor

> - [ ] Carpeta del proyecto creada
> - [ ] Supabase CLI instalado
> - [ ] Login exitoso
> - [ ] Proyecto inicializado y vinculado
> - [ ] Secrets configurados (MCP_ACCESS_KEY + OPENROUTER_API_KEY)
> - [ ] Archivos del servidor descargados (verificado con head -1)
> - [ ] Servidor desplegado (deploy exitoso)
> - [ ] MCP Server URL guardada en tracker
> - [ ] MCP Connection URL guardada en tracker

---

## PASO 7 — Conectar a Claude Desktop y/o ChatGPT

### Conectar a Claude Desktop

1. Abre Claude Desktop → **Settings** → **Connectors**
2. Haz clic en **Add custom connector**
3. Nombre: `BrainOS`
4. Remote MCP server URL: pega tu **MCP Connection URL** (la que termina en `?key=tu-clave`)
5. Haz clic en **Add**

Eso es todo. En tu próxima conversación, Claude tendrá acceso a tu BrainOS.

> **Para activar/desactivar por conversación:** En cualquier chat, haz clic en el botón "+" → Connectors → activa o desactiva BrainOS.

### Conectar a ChatGPT (requiere plan de pago)

1. Ve a [chatgpt.com](https://chatgpt.com) → perfil → **Settings**
2. **Apps & Connectors** → **Advanced settings** → activa **Developer mode**
3. En **Apps & Connectors**, haz clic en **Create**
4. Nombre: `BrainOS`
5. Descripción: `Base de conocimiento personal con búsqueda semántica`
6. MCP endpoint URL: pega tu **MCP Connection URL**
7. Authentication: selecciona **No Authentication** (tu clave va en la URL)
8. Haz clic en **Create**

> ⚠️ Activar Developer Mode desactiva la función Memory de ChatGPT. Tu BrainOS la reemplaza — y funciona en todas las IAs, no solo en ChatGPT.

### Status de Victor

> - [ ] Claude Desktop conectado (connector agregado)
> - [ ] ChatGPT conectado (connector creado)
> - [ ] Herramientas visibles en nueva conversación

---

## PASO 8 — Probar que funciona

### Test 1: Capturar un pensamiento

En Claude Desktop (o ChatGPT), escribe:

```
Recuerda esto: Decidí que el proyecto Tu Sherpa IA va a ser el primer producto que pase por la Factory formal del Big MetaFactory. Victor es el primer cliente.
```

La IA debería confirmar la captura y mostrar metadata extraída (tipo, temas, personas, action items).

### Test 2: Buscar un pensamiento

En la misma conversación o una nueva:

```
¿Qué he decidido sobre Tu Sherpa IA?
```

Debería encontrar el pensamiento que acabas de guardar.

### Test 3: Verificar en Supabase

Ve al dashboard de Supabase → **Table Editor** → tabla `thoughts`. Deberías ver una fila con tu mensaje, un embedding (array de números), y metadata.

### Status de Victor

> - [ ] Thought capturado exitosamente
> - [ ] Búsqueda semántica funcionando
> - [ ] Fila visible en Supabase Table Editor

---

## ¡LISTO! Tu BrainOS está operativo.

### Lo que acabas de construir

En ~45 minutos, sin escribir una línea de código, construiste:

1. **Una base de datos personal soberana** — tus datos son tuyos, no de OpenAI ni de Anthropic
2. **Búsqueda semántica** — encuentra cosas por significado, no por palabras exactas
3. **Portable entre IAs** — Claude, ChatGPT, y cualquier otro que soporte MCP usan la misma memoria
4. **Captura automática** — cada thought se etiqueta automáticamente con metadata
5. **Costo ~$0/mes** — tier gratuito de Supabase + centavos de OpenRouter

### Próximo paso

Ejecutar la **Memory Migration**: traer a tu BrainOS todo lo que tus IAs ya saben de ti. Esto se hace con un Companion Prompt específico que le pide a la IA que exporte su conocimiento sobre ti en forma de thoughts capturables.

---

## Troubleshooting (Resolución de problemas)

| Problema | Causa probable | Solución |
|----------|---------------|----------|
| Las herramientas no aparecen en Claude Desktop | Connector no activado para la conversación | "+" → Connectors → verificar que BrainOS está ON |
| Error 401 | La clave de acceso no coincide | Verificar que `?key=` en la URL coincide exactamente con MCP_ACCESS_KEY en secrets |
| "Permission denied for table thoughts" | Falta el GRANT del paso 2.5 | Ejecutar el SQL del paso 2.5 en Supabase SQL Editor |
| La búsqueda no devuelve nada | No hay thoughts capturados aún | Capturar al menos un thought primero (paso 8 test 1) |
| ChatGPT no usa las herramientas | Developer Mode no está activo, o ChatGPT necesita instrucción explícita | Activar Developer Mode. Pedir: "Usa la herramienta search_thoughts de BrainOS para buscar X" |

---

## Historial de versiones

| Versión | Fecha | Cambio |
|---------|-------|--------|
| v1.0 | 2026-03-20 | Creación inicial. 8 pasos documentados con explicaciones para audiencia no-técnica. Basado en Build Your BrainOS (OB1) + experiencia de instalación de Victor Heredia como caso piloto. |

---

*[[Re100X-Guia-Setup-BrainOS-v01]] v1.0 — EmpowerLabs — 2026-03-20*
*Guía de instalación BrainOS para Tu Sherpa IA — Audiencia: profesionales no-técnicos*