fk/kpt-labs-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kpt-labs-vault/README.md
Floki 709a54ac91 auto-backup 2026-06-21T01-11-54
2026-06-21 03:11:54 +02:00

14 KiB
Raw Blame History

🚀 KPT-LABS Agent OS — System Recovery & Onboarding Guide

Letzte Aktualisierung: 21.6.2026, 00:10:05 | Version: 1.0.0 Vault Hash: v1.0-20260619-1400

📋 Inhaltsverzeichnis

  1. System-Übersicht
  2. Schnellstart (5 Minuten)
  3. Wichtige Pfade
  4. Datenbank-Schema
  5. API-Keys & Credentials
  6. Services & Ports
  7. Disaster Recovery
  8. Umzug auf Neuen PC
  9. Automatische Prozesse
  10. Cron-Jobs
  11. Troubleshooting
  12. Kontakt & Support

🔍 System-Übersicht

Das KPT-LABS Agent OS ist ein Multi-Agent Dashboard mit folgenden Kernkomponenten:

Komponente Beschreibung Port/Ort
Dashboard Next.js Web-UI http://localhost:5555
Datenbank SQLite (better-sqlite3) dashboard/data/kptlabs.db
Obsidian Vault Wissensdatenbank E:\OpenCode_Projekte\obsidianVault
Hermes Gateway Telegram/Discord Bot localhost:8642
LiteLLM Proxy LLM API Proxy localhost:4000
Redis Cache/Session Store localhost:6379
Memory Service Agent Memory localhost:5002

Architektur-Diagramm

┌─────────────────────────────────────────────────────────────┐
│                    KPT-LABS Agent OS                         │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Dashboard   │  │   Hermes    │  │  Telegram/Discord   │  │
│  │  (Next.js)   │  │   Gateway   │  │       Bots          │  │
│  │  Port 5555   │  │  Port 8642  │  │                     │  │
│  └──────┬───────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                 │                     │             │
│         └─────────────────┼─────────────────────┘             │
│                           │                                   │
│                    ┌──────┴──────┐                            │
│                    │  LLM APIs   │                            │
│                    │ (OpenRouter │                            │
│                    │  Anthropic  │                            │
│                    │  OpenAI...) │                            │
│                    └─────────────┘                            │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  SQLite DB  │  │  Obsidian   │  │      Docker         │  │
│  │  (kptlabs)  │  │   Vault     │  │   (LiteLLM,Redis)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

🚀 Schnellstart (5 Minuten)

Voraussetzungen

  • Node.js 18+ & npm
  • Git
  • Docker & Docker Compose
  • Obsidian (optional, für Vault)

Git Setup (bereits konfiguriert)

# Git ist bereits initialisiert im Vault
cd obsidianVault
git status

# Erste Commits sind bereits vorhanden
git log --oneline

# Auto-Commit bei jedem System Snapshot (stündlich)
# Manuell committen:
git add -A
git commit -m "📝 update: Beschreibung"

Git als Backup nutzen

# Remote Repository setzen (GitHub/GitLab)
git remote add origin <REPO_URL>
git push -u origin main

# Auf neuem PC klonen
git clone <REPO_URL> obsidianVault

Installation

# 1. Repository klonen
git clone <REPO_URL> KPT-LABS
cd KPT-LABS

# 2. Dashboard
cd dashboard
npm install
npm run build
npm start

# 3. Docker Services (LiteLLM, Redis)
docker-compose up -d

# 4. Hermes Gateway (optional)
hermes setup
hermes gateway start

# 5. Öffne Dashboard
open http://localhost:5555

Erste Schritte

  1. Login: FK@KPT-LABS / admin
  2. System → Obsidian Tab → Sync prüfen
  3. Chat senden → Token-Tracking testen

📁 Wichtige Pfade

Windows (aktuell)

E:\OpenCode_Projekte\KPT-LABS\
├── dashboard/                    → Next.js Dashboard
│   ├── src/
│   │   ├── app/api/              → API-Routen
│   │   ├── components/           → React-Komponenten
│   │   └── lib/                  → Bibliotheken
│   ├── data/kptlabs.db           → SQLite Datenbank
│   └── package.json
├── hermes-workspace/              → Hermes Frontend
├── obsidianVault/                → Wissensdatenbank
│   ├── Home.md
│   ├── 00-Meta/
│   ├── 01-Wissensdatenbank/
│   ├── 02-Projekte/
│   ├── 03-Ideenpool/
│   ├── 04-Sessions/
│   ├── 05-Dashboard/
│   └── 06-Notizen/
└── docker-compose.yml

Linux/Mac (Zielpfade)

~/KPT-LABS/
├── dashboard/
├── hermes-workspace/
└── obsidianVault/

Wichtige Dateien

Datei Zweck Backup?
dashboard/data/kptlabs.db Hauptdatenbank ✅ Täglich
obsidianVault/ Wissensdatenbank ✅ Git
dashboard/.env API-Keys ✅ Verschlüsselt
~/.hermes/config.yaml Hermes Config ✅
~/.hermes/auth.json Credentials ✅

🗄️ Datenbank-Schema

Kern-Tabellen

-- Benutzer & Sessions
users (id, username, password_hash, role)
sessions (id, session_key, user_id, agent_id, title)
messages (id, session_id, role, content, agent_id, metadata)

-- API-Keys & Provider
api_keys (id, name, key, provider, is_active, preferred_models, priority)
provider_health (provider, model, status, avg_latency_ms, success_count, fail_count)

-- Token-Tracking
token_usage (id, session_id, agent_id, provider, model, input_tokens, output_tokens, cost_usd, latency_ms)
token_budgets (agent_id, period, token_limit, cost_limit_usd)
model_latency (provider, model, latency_ms, status)

-- Features
scheduled_tasks (id, name, agent_id, prompt, cron_expression, is_active)
agent_teams (id, name, leader_agent_id, status)
team_members (team_id, agent_id, model, role)
session_exports (id, session_id, format, file_path)
obsidian_sync_log (id, session_id, success, file_path, tokens_saved)
agent_state (id, uptime_seconds, total_sessions, total_messages, health_status)

Wichtige Queries

-- Aktive Sessions heute
SELECT COUNT(*) FROM sessions WHERE date(created_at) = date('now');

-- Token-Verbrauch letzte 24h
SELECT SUM(total_tokens) FROM token_usage WHERE created_at >= datetime('now', '-1 days');

-- Provider Status
SELECT provider, status, avg_latency_ms FROM provider_health;

-- Offene Tasks
SELECT * FROM tasks WHERE status != 'done';

🔑 API-Keys & Credentials

Provider-Konfiguration

Provider API-Key env var Status
OpenRouter OPENROUTER_API_KEY ✅ Aktiv
Anthropic ANTHROPIC_API_KEY ⬜ Optional
OpenAI OPENAI_API_KEY ⬜ Optional
DeepSeek DEEPSEEK_API_KEY ⬜ Optional

Hermes Auth

# Credentials anzeigen
hermes auth list

# Neuen Key hinzufügen
hermes auth add openrouter
hermes auth add anthropic

# Token-Status prüfen
hermes status

Sicherheitshinweise

  • 🔒 Nie API-Keys in Git committen
  • 🔒 .env Dateien sind in .gitignore
  • 🔒 hermes auth.json ist verschlüsselt
  • 🔄 Keys regelmäßig rotieren (monatlich)

🌐 Services & Ports

Service Port Starten Status
Dashboard 5555 npm start (in dashboard/) 🟢
Hermes Gateway 8642 hermes gateway start 🟢
LiteLLM Proxy 4000 docker-compose up -d 🟢
Redis 6379 docker-compose up -d 🟢
Memory Service 5002 docker-compose up -d 🟢

Docker Services

# Starten
cd KPT-LABS
docker-compose up -d

# Stoppen
docker-compose down

# Logs
docker-compose logs -f

# Status
docker-compose ps

🚨 Disaster Recovery

Szenario 1: Datenbank-Crash

# 1. Letztes Backup finden
ls -la dashboard/data/backups/

# 2. Backup wiederherstellen
cp dashboard/data/backups/kptlabs_<TIMESTAMP>.db dashboard/data/kptlabs.db

# 3. Dashboard neu starten
cd dashboard
npm start

Szenario 2: Obsidian Vault beschädigt

# Git Repository wiederherstellen
cd obsidianVault
git checkout .
git pull

# Falls kein Git: Backup-Ordner nutzen
cp -r /path/to/backup/obsidianVault/* obsidianVault/

Szenario 3: Kompletter System-Verlust

Siehe Umzug auf Neuen PC — das ist die komplette Wiederherstellung.

Szenario 4: API-Key abgelaufen

# 1. Neuen Key in .env eintragen
echo "OPENROUTER_API_KEY=neuer_key" >> dashboard/.env

# 2. Dashboard neu starten
cd dashboard
npm run build
npm start

# 3. Testen
curl http://localhost:5555/api/system

💻 Umzug auf Neuen PC

Schritt 1: Auf altem PC exportieren

# Obsidian Vault klonen
cd obsidianVault
git add -A
git commit -m "pre-migration backup"
git push

# Datenbank sichern
cp dashboard/data/kptlabs.db kptlabs_backup.db

# Hermes Config sichern
cp ~/.hermes/config.yaml hermes_config_backup.yaml
cp ~/.hermes/auth.json hermes_auth_backup.json

Schritt 2: Auf neuem PC importieren

# 1. Repository klonen
git clone <REPO_URL> KPT-LABS
cd KPT-LABS

# 2. Dashboard installieren
cd dashboard
npm install
cp ../kptlabs_backup.db data/kptlabs.db
npm run build
npm start

# 3. Obsidian Vault klonen
cd ..
git clone <OBSIDIAN_GIT_URL> obsidianVault

# 4. Hermes wiederherstellen
mkdir -p ~/.hermes
cp hermes_config_backup.yaml ~/.hermes/config.yaml
cp hermes_auth_backup.json ~/.hermes/auth.json

# 5. Docker starten
docker-compose up -d

Schritt 3: Verifizieren

# Dashboard öffnen
open http://localhost:5555

# System Status prüfen
curl http://localhost:5555/api/system | jq '.status'

# Obsidian Sync prüfen
curl http://localhost:5555/api/obsidian/sync | jq '.vaultStats'

⏰ Automatische Prozesse

Context Compression

  • Wann: Bei 70% Token-Limit
  • Was: Alte Nachrichten werden zusammengefasst
  • Config: app_settings.context_compression

Auto-Session-Save

  • Wann: Alle 5 Nachrichten
  • Was: Markdown-Datei in Obsidian Vault
  • Ort: 04-Sessions/Daily/YYYY-MM-DD_agent.md

Token-Tracking

  • Wann: Jeder API-Request
  • Was: Input/Output Tokens, Kosten, Latenz
  • Wo: token_usage Tabelle

Provider Health Check

  • Wann: Jeder API-Request
  • Was: Erfolgsrate, Latenz, Cooldown
  • Wo: provider_health Tabelle

📅 Cron-Jobs

Job Zeit API-Call
Daily Backup 03:00 POST /api/cron/backup
Weekly Report Montag 09:00 POST /api/cron/weekly-report
Obsidian Sync Check Alle 6h GET /api/obsidian/sync

Cron-Jobs verwalten

# Liste
hermes cron list

# Erstellen
hermes cron create "Name" "Prompt" "Schedule"

# Manuell ausführen
hermes cron run <ID>

🔧 Troubleshooting

Dashboard startet nicht

# Logs prüfen
cd dashboard
npm run build 2>&1 | tail -20

# Port prüfen
netstat -ano | findstr :5555

# Neu starten
pkill -f next
npm start

Datenbank-Fehler

# Prüfen
sqlite3 dashboard/data/kptlabs.db "SELECT count(*) FROM sessions;"

# Reparieren
sqlite3 dashboard/data/kptlabs.db ".dump" > backup.sql
rm dashboard/data/kptlabs.db
sqlite3 dashboard/data/kptlabs.db < backup.sql

Obsidian Sync Fehler

# Manuell synchronisieren
curl -X POST http://localhost:5555/api/obsidian/sync \
  -H "Content-Type: application/json" \
  -d '{"action":"list-sessions"}'

API-Key Probleme

# Testen
curl http://localhost:5555/api/system

# Neustart mit frischem Port
pkill -f next && sleep 2 && npm start

📊 System-Metriken (Live)

Metrik Aktualisierung API
Sessions Echtzeit /api/chat/sessions
Token Usage 10s /api/system
Provider Health 10s /api/system
Obsidian Sync 10s /api/obsidian/sync
Agent State 10s /api/agent-state
Feedback Echtzeit /api/feedback

📝 Changelog

v1.0.0 (2026-06-19)

  • ✅ Initiale Version
  • ✅ Dashboard mit KPI Widget
  • ✅ Context Compression
  • ✅ Auto-Session-Save zu Obsidian
  • ✅ Feedback-Loop System
  • ✅ Agent State Tracking
  • ✅ Cron-Jobs (Backup, Report, Sync)
  • ✅ Disaster Recovery Guide

👥 Rollen

Rolle Zugriff Beschreibung
Admin Voll Alles
Agent Eingeschränkt Chat, Tools
Viewer Read-Only Dashboard ansehen

🔗 Nützliche Links

⚠️ Checkliste für neuen Agenten

  • Diese Datei gelesen
  • Dashboard geöffnet und Login getestet
  • Obsidian Vault Pfad geprüft
  • API-Keys vorhanden (.env)
  • Docker Services laufend
  • Erste Chat-Nachricht gesendet
  • Token-Tracking geprüft
  • Backup getestet

Diese Datei wird automatisch aktualisiert. Nicht manuell bearbeiten. Generiert von: KPT-LABS Agent OS v1.0.0 Bei Fragen: Erstelle ein Issue im Repository oder kontaktiere den Admin.