Od klonu repo do pierwszej pamięci w pięć minut.

Wymagania

• Docker Engine + Docker Compose v2.
• Ollama na hoście (http://127.0.0.1:11434) z pobranym modelem nomic-embed-text. Zarówno semantic-search, jak i consciousness-server dochodzą do Ollamy poprzez hosta. Jeśli Ollama nie działa, /api/search zwraca precyzyjny 503 ollama_unreachable, zamiast udawać, że wszystko gra.

Ubuntu / Debian: curl -fsSL https://ollama.com/install.sh | sh, a potem ollama pull nomic-embed-text. macOS: zainstaluj aplikację Ollama, później pobierz ten sam model.

1. Sklonuj ekosystem

Cały stack mieści się w jednym repozytorium. Plik compose w deploy/docker-compose.yml spina sześć usług plus Redisa z tego jednego drzewa.

git clone https://github.com/build-on-ai/consciousness-server.git
cd consciousness-server

2. Zweryfikuj hosta

Krótki skrypt sprawdza Dockera, Compose, Ollamę i model do embeddingów. Jest opcjonalny, ale pokazuje dokładnie, czego brakuje, zamiast pozwolić Dockerowi paść w połowie pulla.

bin/preflight
# Kończy z kodem 0, gdy host jest gotowy.
# Jeśli czegoś brakuje — wypisuje co zainstalować i przerywa.
# Najczęstszy przypadek: "ollama pull nomic-embed-text".

3. Uruchom stack

Domyślny profil podnosi sześć bloków z AUTH_MODE=off, więc pojedynczy użytkownik dostaje działający ekosystem bez generowania kluczy. Key-server jest opcjonalny — przez --profile full; do tego przewodnika nie jest potrzebny.

cd deploy
docker compose up -d

Co właśnie uruchomiłeś — porty są od razu dostępne z LAN-u:

Ekosystem rezerwuje zakres 3030–3049 dla obecnych i przyszłych klocków BuildOnAI. Aktywny podzbiór żyje w ports.yaml w katalogu repo — każda warstwa (natywne serwery, compose, preflight, narzędzia) czyta ten sam plik.

3.5 Porty zajęte na Twoim hoście?

Jeśli któryś domyślny port jest zajęty na Twojej maszynie — inny serwis nasłuchuje na 3032, masz już uruchomione Redis na 6379 — naprawa to edycja jednego pliku. Nie zmieniaj docker-compose.yml; ports.yaml jest jednym źródłem prawdy, każda warstwa z niego czyta.

# Podnieś każdy port w ports.yaml o 10000 (lub dowolny wolny offset):
sed -i -E 's/^(  [a-z-]+: )3([0-9]{3})$/\113\2/' ports.yaml
sed -i -E 's/^(  redis: )6379$/\116379/' ports.yaml

# Wygeneruj deploy/.env, ponów preflight, podnieś stack:
bin/sync-ports
bin/preflight
cd deploy && docker compose up -d

Co się stało: ports.yaml przesunął całą paletę o 10000 (więc CS żyje na 13032, semantic search na 13037, redis na 16379 itd.). bin/sync-ports wygenerował na nowo deploy/.env; compose podstawił nowe wartości; bin/preflight przeszedł bez ostrzeżeń.

Porty wewnętrzne kontenerów (zmienne PORT wewnątrz serwisów, REDIS_PORT do kontenera redis, URL'e między serwisami przez DNS dockera) zostają zahardkodowane — żyją w sieci dockera i nigdy nie zderzą się z hostem. Tylko porty po stronie hosta się zmieniają.

Można też nadpisać jeden port bez edycji ports.yaml: PORT_KEY_SERVER=13040 docker compose up -d. Przydatne do jednorazowych testów.

4. Sprawdź, że wszystko żyje

Każda usługa wystawia /health. Jedna pętla potwierdza, że stack wstał czysto:

for p in 3032 3037 3038 3041 3042; do
  curl -sf "http://127.0.0.1:$p/health" >/dev/null && echo "port $p OK"
done

# Oczekiwany wynik:
# port 3032 OK
# port 3037 OK
# port 3038 OK
# port 3041 OK
# port 3042 OK

Jeśli któregoś portu brak, docker compose logs <usługa> z katalogu deploy/ pokazuje, co padło. Najczęstszy przypadek to nieuruchomiona Ollama — popraw to, zrestartuj przez docker compose restart semantic-search i sprawdź ponownie.

5. Zapisz pierwszą pamięć

Warstwa pamięci jest gotowa od razu po bootcie. Bez dodatkowej konfiguracji. Trzy wywołania — zapisz rozmowę, zapisz rekord treningowy, wyszukaj po wszystkim:

# 1. Zapisz rekord konwersacji
curl -X POST http://127.0.0.1:3032/api/memory/conversations \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": "first-agent",
    "session_id": "s1",
    "messages": [{"role": "user", "content": "hello world"}]
  }'

# 2. Zapisz rekord treningowy (pole "type" jest WYMAGANE —
#    jedna z wartości: troubleshooting | exploration | implementation |
#    explanation | architecture | ui_mapping)
curl -X POST http://127.0.0.1:3032/api/memory/training \
  -H 'Content-Type: application/json' \
  -d '{
    "agent": "first-agent",
    "type": "exploration",
    "goal": "first run",
    "instruction": "verify that storage works",
    "input": "quickstart guide",
    "output": "ecosystem boots"
  }'

# 3. Wyszukaj semantycznie po wszystkim, co zostało zaembedowane
curl -X POST http://127.0.0.1:3037/api/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "first run quickstart"}'

Trzecie wywołanie idzie wprost do portu 3037, bo semantic-search działa jako osobna usługa z network_mode: host. Embeddingi pochodzą z Ollamy; indeks żyje w ChromaDB; zapytanie to pojedynczy POST.

Dalsze kroki

• Cortex → — lokalny agent AI napędzany Ollamą. Spina się z tą samą warstwą pamięci.
• Document Processor → — aplikacja desktop do PDF / DOCX / TXT, która wrzuca zparsowane treści do wspólnej pamięci.
• Key Server → — włączasz uwierzytelnianie ed25519, gdy chcesz wyjść z AUTH_MODE=off.
• Maszyny → — zarejestruj kolejne maszyny, żeby agenci mogli routować po GPU, VRAM, dostępnych modelach.

Sprzątanie

Drzewo deploy/volumes/* (store ChromaDB, dump Redisa, logi per usługa) jest zapisywane przez kontenery działające jako root, więc usunięcie z hosta wymaga sudo. Trzy poziomy:

cd deploy
docker compose down              # zatrzymuje kontenery, wolumeny zostają
docker compose down -v           # zatrzymuje + usuwa nazwane wolumeny
sudo rm -rf volumes              # pełny reset do stanu wyjściowego