brain-template/docs/brain-engine-guide.md

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

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

# 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 :

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

Dernier recours

pkill -f 'python3.*server.py'

---

Lancer en arriere-plan

Si tu ne veux pas bloquer un terminal :

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

Verifier les logs :

tail -f /tmp/brain-engine.log

---

Recherche semantique

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

Installer Ollama

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

Indexer le corpus

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

Apres l'indexation, la recherche fonctionne :

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

Re-indexer apres des modifications

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 :

# 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

# 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

# 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