Quickstart — Soul 4.0.2
4.0.2 ist auf npm veröffentlicht und läuft vollständig lokal. Kein Konto, kein API-Key, kein ausgehender Netzwerkverkehr. Voraussetzung ist Node.js ab Version 18.
1 — Installation
Ein Aufruf legt das Datenverzeichnis ~/.soul
an. Bestehende Stände aus früheren Versionen werden dabei migriert; vor
der Migration wird eine Sicherung geschrieben.
2 — Im MCP-Client einhängen
Soul spricht das Model Context Protocol über stdio. In Claude Code genügt ein Befehl:
Andere MCP-Clients (Cursor, Windsurf, Zed) tragen den Server in ihrer Konfigurationsdatei ein:
Nach dem Neustart des Clients meldet der Handshake
[email protected] mit 23 Werkzeugen.
3 — Die Fünf-Minuten-Demo
Der Punkt von Soul lässt sich in vier Schritten zeigen. Entscheidend ist Schritt 2: die Session wird wirklich beendet, damit klar ist, dass die Erinnerung nicht aus dem Kontextfenster kommt.
Schritt 1 — etwas merken. In einer laufenden Session:
user_statement wird nur vergeben, wenn es eine
tatsächliche Nutzeraussage gibt — mit Zitat. Eigene
Schlussfolgerungen des Modells landen als
agent_inference. Das ist der Unterschied, um den es
geht.
Schritt 2 — Session schliessen. Fenster zu, Client beenden, neu starten. Kein geteilter Kontext.
Schritt 3 — in der neuen Session abrufen.
Schritt 4 — den Verlauf ansehen. soul_timeline zeigt, wann welches Wissen dazukam und was es korrigiert hat.
Was die Demo zeigt und was nicht. Sie belegt, dass Wissen eine Session überlebt und seine Herkunft behält. Sie ist kein Nachweis, dass ein Modell dadurch bessere Antworten gibt — dafür braucht es einen kontrollierten Vergleich, und der ist für den Proxy noch nicht gefahren. Der Stand der Messungen steht auf der Nachweise-Seite.
Werkzeugreferenz
23 Werkzeuge, gruppiert nach Aufgabe.
| Werkzeug | Gruppe | Zweck |
|---|---|---|
| soul_remember | Gedächtnis | Fakt speichern, mit Herkunftsangabe |
| soul_recall | Gedächtnis | Nach gespeichertem Wissen suchen |
| soul_correct | Gedächtnis | Bestehenden Eintrag berichtigen |
| soul_confirm | Gedächtnis | Eintrag bestätigen, Konfidenz anheben |
| soul_resolve | Gedächtnis | Widerspruch zwischen Einträgen entscheiden |
| soul_forget | Gedächtnis | Eintrag zurückziehen (Ledger bleibt) |
| soul_context | Kontext | Kapsel für die aktuelle Aufgabe abrufen |
| soul_about_me | Kontext | Was das System über den Nutzer weiss |
| soul_identity | Kontext | Identitätsprofil lesen und pflegen |
| soul_timeline | Verlauf | Chronologie der Wissensänderungen |
| soul_status | Verlauf | Zustand von Datenbank und Ledger |
| soul_export | Verlauf | Vollständigen Bestand exportieren |
| soul_import | Verlauf | Bestand einspielen |
| soul_reflect | Verlauf | Sitzung abschliessen, Erkenntnisse festhalten |
| soul_run | Laufzeit | Aufgabe als nachvollziehbaren Run starten |
| soul_feedback | Laufzeit | Ergebnis eines Runs zurückmelden |
| soul_goal | Laufzeit | Ziele setzen und verfolgen |
| soul_deliberate | Urteil | Strukturierte Abwägung einer Entscheidung |
| soul_commit_deliberation | Urteil | Abwägung als Entscheidung festschreiben |
| soul_predict | Urteil | Vorhersage mit Konfidenz ablegen (Kalibrierung) |
| soul_mark_useful | Urteil | Eintrag als nützlich markieren |
| soul_workbench | Werkbank | Offene Aufgaben an Modelle zuweisen |
| soul_review_queue | Werkbank | Was auf menschliche Prüfung wartet |
CLI
semantic on ist bewusst nicht
voreingestellt: es lädt ein lokales Modell nach. Auch danach verlässt
kein Datum den Rechner.
Wo die Daten liegen
| Pfad | Art | Inhalt |
|---|---|---|
| ~/.soul/memories.db | SQLite (WAL) | Alle Einträge, Ledger, Runs, Episoden |
| ~/.soul/constitution.json | JSON | Richtlinie — im Code durchgesetzt, nicht nur im Prompt |
Die Richtlinie regelt, was gar nicht erst gespeichert wird: erkannte Secrets werden verworfen, es bleibt nur ein bereinigtes Ablehnungsereignis. Inhalte, die nach Prompt-Injection aussehen, werden isoliert und nie wieder ausgeliefert. Sensible Kategorien warten auf eine ausdrückliche Bestätigung.
Grenze, offen gesagt: Eine Kontext-Firewall kann prinzipiell nicht lückenlos sein. Die Regeln senken das Risiko, sie beseitigen es nicht. Wer damit hochsensible Daten verarbeitet, sollte das wissen.
API-Referenz — Soul 4.1.0 Proxy
Dieser Dienst ist noch nicht erreichbar. Was hier steht, beschreibt die geplante Schnittstelle, damit eine Integration vorbereitet werden kann — es ist keine Beschreibung eines laufenden Systems. Details können sich bis zum Start noch ändern.
Es liegt für 4.1.0 auch keine Wirksamkeitsmessung vor. Der Vergleich gegen die Baseline ist präregistriert, aber nicht gefahren. Bis dahin steht hier keine Leistungszahl.
Was gemessen ist und was nicht, samt der bekannten Schwächen von 4.0.2, steht gesammelt auf der Startseite unter Nachweise.
Der Proxy ist OpenAI-kompatibel. Für bestehende Integrationen ändert sich nur der Base-URL — Anfrage- und Antwortformat bleiben, wie die SDKs sie erwarten. Dazwischen laufen Intent Analysis und Task Restructuring.
Was dazwischen passiert
Der Proxy legt vor deine Anfrage eine Vorbereitungs-Runde. Im voreingestellten Modus setzt er dafür eine deterministisch zusammengebaute System-Nachricht an den Anfang der Nachrichtenliste — deine letzte Nutzer-Nachricht bleibt dabei Byte für Byte unverändert. Es wird also nichts umgeschrieben, was du geschrieben hast; das Modell bekommt zusätzlich eine Anleitung, wie es an die Aufgabe herangehen soll.
AMPLIFY_MODE | Modellaufruf | Verhalten |
|---|---|---|
| implant | nein | Voreinstellung. System-Nachricht davor, Nutzer-Nachricht unverändert |
| implant-v10 | nein | Vergleichsarm für die Messung, gleiches Prinzip, anderer Rahmen |
| analyzer | ja | Älterer Pfad: ersetzt die letzte Nutzer-Nachricht durch eine Vorlage |
| off | nein | Reines Durchreichen, keine Vorbereitung |
Fail-open. Geht beim Zusammenbauen irgendetwas schief, wird die Anfrage im Original weitergereicht statt abgebrochen. Ein Fehler im Amplifier soll dich nie einen Aufruf kosten.
Triviales bleibt unangetastet. Kurze, offensichtliche Anfragen erkennt der Proxy und lässt sie durch — eine Vorbereitungs-Runde für „wie spät ist es" wäre nur Ballast.
Ungemessen. Ob diese Vorbereitung die Ergebnisse messbar verbessert, ist offen. Der Vergleich gegen die Baseline (Benchmark B2) ist präregistriert und noch nicht gefahren. Bis das Ergebnis vorliegt, ist der Mechanismus eine begründete Annahme — kein belegter Vorteil, und hier steht keine Zahl dazu.
Authentifizierung
Über einen API-Key aus dem Dashboard, als Bearer-Token im Header:
Der Schlüssel wird bei der Erstellung genau einmal im Klartext angezeigt; gespeichert wird nur ein Hash. Geht er verloren, wird ein neuer erzeugt — der alte lässt sich im Dashboard widerrufen und ist danach sofort ungültig.
Der Schlüssel gehört in eine Umgebungsvariable, nicht in Frontend-Code und nicht ins Repository. Wer ihn hat, kann Aufrufe auf dein Kontingent absetzen.
Eigener Upstream-Key (BYOK)
Es sind zwei getrennte Schlüssel im Spiel. Der Soul-Key im
Authorization-Header weist dich gegenüber
Soul aus. Zusätzlich kannst du optional deinen eigenen Modell-Key
mitschicken — dann läuft der Aufruf über dein Konto beim Anbieter statt
über den hinterlegten Standard-Key.
Der Wert aus X-Soul-Upstream-Key ersetzt den
hinterlegten Standard-Key für genau diesen einen Aufruf.
Er wird nicht gespeichert und nicht protokolliert. Antwortet der Anbieter
mit einem Fehler, wird der verwendete Schlüssel aus dem Antworttext
entfernt, bevor er dich erreicht — manche Anbieter spiegeln Schlüssel in
Fehlermeldungen zurück.
Anbieter pro Anfrage wählen
Zusätzlich lässt sich der Anbieter je Anfrage bestimmen. Fehlt der Header, geht der Aufruf an den Upstream, den der Betrieb hinterlegt hat.
Erlaubt sind ausschliesslich Adressen aus einer serverseitigen Liste.
Steht der Wert nicht darin, antwortet der Proxy mit
400 und dem Fehlertyp
upstream_base_not_allowed — und kontaktiert
gar keinen Upstream. Voreingestellt sind fünf OpenAI-kompatible
Anbieter:
Eine frei wählbare Adresse hiesse, dass ein Aufruf den Proxy dazu bringen kann, beliebige Ziele anzusprechen — auch interne. Dagegen stehen zwei Schichten: Beim Start weigert sich der Aufbau der Liste, private oder lokale Adressen aufzunehmen, selbst wenn sie versehentlich in der Konfiguration stehen. Bei der Anfrage wird der Header per exaktem Zeichenkettenvergleich geprüft — der Nutzerwert wird nicht als URL zerlegt.
Das schliesst die üblichen Parser-Tricks aus. Etwa
https://[email protected]/v1:
der tatsächliche Host ist evil.example,
obwohl die Zeichenkette harmlos beginnt. Ohne Zerlegung gibt es
schlicht keinen Treffer.
Beides lässt sich kombinieren: Wird eine erlaubte Alt-Adresse gewählt, geht der mitgeschickte Schlüssel an genau diesen Anbieter. Die Bereinigung von Fehlerantworten gilt auch dann — ein Anbieter, der den Schlüssel zurückspiegelt, erreicht dich nicht im Klartext.
Stand: Beides ist im Proxy implementiert und durch
Tests abgedeckt — dass der mitgeschickte Schlüssel den Standard-Key
ersetzt, dass eine erlaubte Alt-Adresse wirklich angesprochen wird,
dass eine fremde oder interne Adresse mit
400 endet, ohne dass ein Upstream
kontaktiert wird, und dass die Schlüssel-Bereinigung auch bei
gewählter Alt-Adresse greift. Nutzbar ist das trotzdem erst, wenn der
Dienst erreichbar ist — siehe das Banner oben.
Chat Completions
Anfrage (Feldnamen wie bei der OpenAI-API):
| Feld | Typ | Beschreibung |
|---|---|---|
| model | string | Zielmodell, an das weitergereicht wird |
| messages | array | Nachrichtenverlauf mit role und content |
| stream | boolean | Bei true Antwort als Server-Sent Events |
| temperature | number | Optional, wird durchgereicht |
| max_tokens | integer | Optional, wird durchgereicht |
Mit dem offiziellen OpenAI-SDK genügt der geänderte Base-URL:
Streaming (SSE)
Mit "stream": true antwortet der Endpunkt als
text/event-stream. Die Chunks haben die
gewohnte Form, der Strom endet mit data: [DONE]:
Die vorgelagerte Analyse geschieht, bevor der erste Chunk fliesst. Die Zeit bis zum ersten Token ist dadurch höher als bei einem direkten Aufruf — wie viel, wird der Benchmark zeigen. Eine Zahl dazu gibt es noch nicht.
Fehler und Limits
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Bad Request | Anfrageformat prüfen. Beim Fehlertyp upstream_base_not_allowed stand ein nicht erlaubter Wert in X-Soul-Upstream-Base; die Antwort führt die zulässigen Adressen auf |
| 401 | Unauthorized | Schlüssel fehlt, ist ungültig oder widerrufen |
| 429 | Too Many Requests | Rate-Limit oder Kontingent erreicht; mit exponentiellem Backoff wiederholen |
| 5xx | Serverfehler | Erneut versuchen; hält es an, ist es unser Problem |
Die konkreten Grenzwerte für Rate-Limit und Kontingent stehen noch nicht fest. Sobald sie es tun, stehen sie hier — mit Zahlen, nicht mit Andeutungen.
Ein Konto lässt sich bereits anlegen. Die Schlüsselverwaltung im Dashboard ist gebaut und zeigt offen an, dass die API noch nicht antwortet — sie täuscht keinen Schlüssel vor, der nirgends gültig wäre.