# Brain-engine — guide pratique

> Demarrer, arreter, diagnostiquer. Les commandes du quotidien.

---

## C'est quoi brain-engine ?

Brain-engine c'est le serveur local de ton brain. Il fait 3 choses :

1. **Dashboard web** — tes docs, tes workflows, la visualisation 3D de ton corpus
2. **API locale** — les agents et scripts du brain l'utilisent pour chercher du contexte
3. **Recherche semantique** — tu poses une question, il trouve les fichiers pertinents

> Brain-engine n'est **pas obligatoire** pour utiliser le brain avec Claude Code.
> C'est un bonus. `brain boot` fonctionne sans.

---

## Demarrer

```bash
cd ~/Dev/Brain
bash brain-engine/start.sh
```

Le script :
1. Cree l'environnement Python (une seule fois)
2. Installe les dependances (une seule fois)
3. Init brain.db si absent
4. Indexe le corpus si Ollama est disponible
5. Lance le serveur sur le port 7700

**Le terminal reste occupe.** Ouvre un autre terminal pour Claude Code.

---

## Verifier que ca tourne

```bash
# Health check
curl http://localhost:7700/health

# Dashboard
# Ouvre dans ton navigateur :
http://localhost:7700/ui/
```

---

## Arreter

### Premier plan (cas normal)

Tu as lance `bash brain-engine/start.sh` dans un terminal → **Ctrl+C** dans ce terminal.

### Arriere-plan

Si tu l'as lance avec `nohup` :

```bash
kill $(cat /tmp/brain-engine.pid)
```

### Dernier recours

```bash
pkill -f 'python3.*server.py'
```

---

## Lancer en arriere-plan

Si tu ne veux pas bloquer un terminal :

```bash
cd ~/Dev/Brain
nohup bash brain-engine/start.sh > /tmp/brain-engine.log 2>&1 &
echo $! > /tmp/brain-engine.pid
```

Verifier les logs :

```bash
tail -f /tmp/brain-engine.log
```

---

## Recherche semantique

La recherche necessite **Ollama** + le modele `nomic-embed-text`.

### Installer Ollama

```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text
```

### Indexer le corpus

```bash
cd ~/Dev/Brain
brain-engine/.venv/bin/python3 brain-engine/embed.py
```

Apres l'indexation, la recherche fonctionne :

```bash
curl "http://localhost:7700/search?q=comment+fonctionnent+les+sessions"
```

### Re-indexer apres des modifications

```bash
brain-engine/.venv/bin/python3 brain-engine/embed.py
```

> L'indexation est incrementale — seuls les fichiers modifies sont re-indexes.

---

## Connexion MCP (Claude Code)

Brain-engine expose un serveur MCP pour que Claude Code puisse chercher dans ton brain :

```bash
# Lancer le MCP server (port 7701)
brain-engine/.venv/bin/python3 brain-engine/mcp_server.py

# Ajouter dans Claude Code
claude mcp add brain --transport http http://localhost:7701/mcp/
```

Puis en session Claude Code :

```
use brain_search to find context about <sujet>
```

---

## Diagnostiquer

### Le serveur ne demarre pas

```bash
# Verifier que le port n'est pas deja utilise
lsof -i :7700

# Verifier les logs
cat /tmp/brain-engine.log
```

### "no such table: embeddings"

Normal si Ollama n'est pas installe. La recherche ne fonctionne pas mais le dashboard et l'API oui.

### Le dashboard affiche une page blanche

```bash
# Verifier que brain-ui est build
ls ~/Dev/Brain/brain-ui/dist/index.html

# Si absent, rebuild :
bash brain-ui/build.sh
# Puis relancer brain-engine
```

---

## Ports

| Service | Port | Usage |
|---------|------|-------|
| brain-engine | 7700 | API + dashboard |
| MCP server | 7701 | Connexion Claude Code |