Semantica Tutorial 2026: Agent Memory einrichten

Ein Installationslauf besteht bei Semantica nicht aus einem einzigen pip-Befehl: Die offizielle README nennt für den Health Check den CLI-Aufruf semantica doctor, der Python, Semantica, den Vektorspeicher und die Konfiguration prüft. (offizielle Semantica-README)

Symptom: Sie sehen bereits beim ersten Start mehrere optionale Abhängigkeiten, unklare Importfehler oder ein scheinbar leeres Agent Memory.
Schnellste Lösung: Starten Sie mit dem Kernpaket und einer kleinen lokalen Teststrecke: Installation → Health Check → Schreiben → Abfrage → Neustart und Laden. Externe Graphdatenbanken, Vektorspeicher und LLMs kommen erst danach.

Dieses Vorgehen eignet sich für Sie, wenn Sie Semantica zum ersten Mal installieren, aus Gesprächen oder Dokumenten ein überprüfbares Agent Memory erstellen oder eine wiederholbare Python-Bereitstellung für ein kleines Plattformteam vorbereiten. Wenn Sie bereits eine produktive Grapharchitektur betreiben, ist dieser Artikel bewusst nur der kontrollierte Basistest vor Ihrer Produktionsmigration.

Schritt 1: Einen kleinen Prüfgegenstand festlegen

Beginnen Sie nicht mit dem vollständigen Unternehmenswissen. Für den ersten Lauf brauchen Sie eine kleine Domäne, deren erwartete Ergebnisse Sie von Hand kontrollieren können. Ein geeignetes Beispiel besteht aus drei Knoten:

• Python als Programmiersprache,
• Semantica als Anwendung,
• Agent Memory als Funktionsbereich.

Daraus entstehen zwei Beziehungen:

• Python ermöglicht Semantica,
• Semantica unterstützt Agent Memory.

Die Datenmenge ist absichtlich klein. Sie prüfen damit nicht die Belastbarkeit einer Unternehmenspipeline, sondern ob Ihre Umgebung Daten überhaupt korrekt annimmt, strukturiert speichert und wieder ausgibt.

Legen Sie zunächst ein leeres Arbeitsverzeichnis an:

mkdir semantica-first-run
cd semantica-first-run
python -m venv .venv

Aktivieren Sie die Umgebung je nach Shell:

# macOS oder Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Prüfen Sie danach, ob python und pip tatsächlich aus dieser Umgebung stammen:

python --version
python -m pip --version

Speichern Sie die Ausgabe, bevor Sie weitere Pakete installieren:

python --version 2>&1 | tee python-version.log
python -m pip --version 2>&1 | tee pip-version.log

Das ist kein Selbstzweck. Wenn später ein optionales Modul fehlschlägt, können Sie unterscheiden, ob der Fehler aus Python, Pip, Semantica oder einer zusätzlichen Backend-Bibliothek stammt.

Hinweis: Verwenden Sie für diesen Test keine globale Python-Installation und kein bereits überladenes Projektverzeichnis. Eine isolierte Umgebung macht Abhängigkeitsfehler sichtbar, statt sie durch alte Pakete zu verdecken.

Definieren Sie außerdem vorab ein konkretes Akzeptanzkriterium: Nach dem Einfügen der Knoten muss die Abfrage nach den Nachbarn von Semantica die zuvor angelegten Beziehungen liefern. Eine grafische Oberfläche allein reicht nicht als Nachweis.

Schritt 2: Das Kernpaket installieren und die CLI prüfen

Die offizielle Installationsanweisung verwendet das Paket semantica. Für den ersten Durchlauf installieren Sie ausschließlich den Kern:

python -m pip install semantica

Die offizielle Dokumentation nennt zusätzlich Varianten wie semantica[all], LLM-Integrationen, Vektorspeicher und externe Graph-Backends. Diese Extras sind für den Minimaltest nicht notwendig und sollten nicht gleichzeitig installiert werden. (offizielle Semantica-README)

Prüfen Sie zunächst, ob die Kommandozeile gefunden wird:

semantica --help

Die CLI wird laut offizieller README mit dem Paket ausgeliefert. Zu den dokumentierten Befehlsgruppen gehören unter anderem ingest, extract, kg, reason, export, server, mcp, doctor und init. (offizielle CLI-Dokumentation)

Führen Sie anschließend den Health Check aus:

semantica doctor

Bei einer funktionierenden Installation sollten Sie eine erfolgreiche Prüfung der Python-Umgebung, der Semantica-Version und der verfügbaren Konfiguration erhalten. Die offizielle Beispielausgabe zeigt außerdem eine FAISS-Prüfung und eine Konfigurationsdatei unter ~/.semantica/config.yaml. Behandeln Sie diese Beispielwerte jedoch als erwartete Struktur, nicht als Beweis dafür, dass jede optionale Komponente in Ihrer Umgebung automatisch verfügbar ist. (offizielle Semantica-README)

Für eine reproduzierbare Diagnose speichern Sie die Ausgaben:

semantica doctor 2>&1 | tee doctor.log
semantica --help 2>&1 | tee cli-help.log
python -m pip freeze | tee pip-freeze.txt

So vermeiden Sie einen typischen Fehler: Sie reparieren eine Installation, löschen dabei aber genau die Versionsinformation, die den ursprünglichen Fehler erklärbar gemacht hätte.

Typische Installationsfehler eingrenzen

Wenn semantica nicht gefunden wird, prüfen Sie zuerst, ob die virtuelle Umgebung noch aktiv ist:

which python
which semantica

Unter Windows PowerShell verwenden Sie:

Get-Command python
Get-Command semantica

Wenn der Paketbefehl erfolgreich war, die CLI aber fehlt, vergleichen Sie den Installationspfad von Pip mit dem Pfad der ausführbaren Datei. Installieren Sie nicht sofort alle verfügbaren Extras. Dadurch würden zusätzliche native Bibliotheken, Zugangsdaten oder inkompatible Versionen gleichzeitig in die Fehlersuche gelangen.

Bei einem Importfehler sichern Sie den vollständigen Traceback. Entscheidend sind die erste fehlende Modulbezeichnung, der aktive Python-Pfad und die zuletzt installierte Paketversion. Historische Community-Beispiele können andere Paketnamen oder inzwischen veränderte Imports verwenden; maßgeblich sind die aktuelle README, die offizielle Referenz, der PyPI-Eintrag und die offiziellen Repository-Issues.

Schritt 3: Den ersten Knowledge Graph ohne LLM bauen

Für den ersten Graphen benötigen Sie kein LLM. Semantica beschreibt die Graphkonstruktion, das Reasoning und die Provenienz als Schichten, die unabhängig von einem Sprachmodell verwendet werden können. (offizielle Context-Referenz)

Erstellen Sie die Datei first_graph.py:

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=False)

graph.add_node(
    "python",
    "language",
    properties={"name": "Python"}
)

graph.add_node(
    "semantica",
    "framework",
    properties={"name": "Semantica"}
)

graph.add_node(
    "agent_memory",
    "capability",
    properties={"name": "Agent Memory"}
)

graph.add_edge("python", "semantica", "enables")
graph.add_edge("semantica", "agent_memory", "supports")

print("Graph-Statistik:")
print(graph.stats())

print("\nNachbarn von Semantica:")
print(graph.get_neighbors("semantica", hops=1))

Starten Sie das Skript aus dem Verzeichnis, in dem die Datei liegt:

python first_graph.py

Die offizielle Referenz dokumentiert ContextGraph, add_node(), add_edge(), get_neighbors() und stats() als Bestandteile des Context-Moduls. Die Dokumentation zeigt sowohl typisierte Knoten als auch die Abfrage von Nachbarschaften. Bei API-Abweichungen zwischen installierter Version und Beispielcode sollten Sie Ihre lokale Version gegen die offizielle Referenz und die Repository-Beispiele prüfen.

Die erwartete Prüfung besteht nicht darin, dass lediglich kein Fehler erscheint. Kontrollieren Sie mindestens:

1. Die Knotenanzahl entspricht Ihrer Eingabe.
2. Die Kantenanzahl entspricht den beiden Beziehungen.
3. Die Nachbarn von semantica enthalten agent_memory.
4. Der Beziehungstyp supports ist in der Ausgabe erkennbar.
5. Keine Entität wurde durch eine abweichende Schreibweise doppelt angelegt.

Gerade der letzte Punkt ist für Agent Memory wichtig. Semantica und semantica können je nach Datenmodell als unterschiedliche Kennungen behandelt werden. Verwenden Sie deshalb stabile IDs und bewahren Sie die menschenlesbare Bezeichnung in den Eigenschaften auf.

Schritt 4: Agent Memory schreiben und gezielt abfragen

Der Graph modelliert Beziehungen. Für eine typische Agent-Memory-Strecke verbinden Sie ihn mit einem AgentContext. Die offizielle Dokumentation verwendet dafür AgentContext, ContextGraph und einen VectorStore.

Legen Sie first_memory.py an:

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=ContextGraph(advanced_analytics=False),
)

memory_id = context.store(
    "Das Team verwendet Semantica für ein graphbasiertes Agent Memory.",
    metadata={
        "source": "first-run",
        "kind": "decision-record",
    },
    conversation_id="tutorial-2026",
)

print("Memory-ID:", memory_id)
print("Gesundheit:", context.health())

results = context.retrieve(
    "Wofür verwendet das Team Semantica?",
    max_results=5,
    use_graph=True,
)

for result in results:
    print(result)

Starten Sie das Skript aus demselben aktivierten virtuellen Environment:

python first_memory.py

Achten Sie auf eine wichtige Parametergrenze: Die Referenz nennt für retrieve() den Parameter max_results, nicht top_k. Wenn Sie Beispiele aus anderen Memory-Bibliotheken übernehmen, kann genau diese scheinbar kleine Abweichung zu einem Laufzeitfehler führen.

Prüfen Sie die Antwort anschließend gegen den Originalsatz. Eine semantisch plausible Ausgabe ist noch kein Beweis, dass die richtige Quelle gefunden wurde. Für einen ersten Test sollte die Ausgabe mindestens den Inhalt, die Memory-ID oder Metadaten enthalten, die Sie dem gespeicherten Datensatz zuordnen können.

Der Nutzen der Knowledge-Graph-Erweiterung zeigt sich bei Beziehungen, nicht bei jedem einzelnen Satz. Eine reine Vektorsuche beantwortet bevorzugt, was ähnlich klingt. Ein Graph kann zusätzlich untersuchen, welche Entitäten verbunden sind, über welche Kante die Verbindung läuft und welche Quellen zu einem Fakt gehören. Semantica verbindet diese Ebenen in einer Context-Schicht für Agenten.

Schritt 5: Persistenz mit einem echten Neustart nachweisen

Ein erfolgreicher Lauf im selben Prozess beweist nicht, dass Ihre Daten nach einem Neustart erhalten bleiben. Die offizielle Dokumentation weist darauf hin, dass der VectorStore nicht automatisch persistiert. Stattdessen sollen Sie den vollständigen Zustand mit context.save(path) speichern und später mit context.load(path) wiederherstellen. (offizielle Persistenz-Dokumentation)

Verwenden Sie deshalb ein separates Skript:

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

STATE_PATH = "agent_state"

def create_context():
    return AgentContext(
        vector_store=VectorStore(backend="faiss", dimension=768),
        knowledge_graph=ContextGraph(advanced_analytics=False),
    )

context = create_context()

context.store(
    "Semantica speichert strukturierte Beziehungen für Agent Memory.",
    metadata={"source": "persistence-test"},
    conversation_id="persistence-check",
)

context.save(STATE_PATH)
print(f"Zustand gespeichert: {STATE_PATH}")

Starten Sie es:

python save_memory.py

Erstellen Sie danach load_memory.py:

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=ContextGraph(advanced_analytics=False),
)

context.load("agent_state")

results = context.retrieve(
    "Was speichert Semantica für Agent Memory?",
    max_results=5,
    use_graph=True,
)

print(results)

Beenden Sie den ersten Prozess vollständig und starten Sie danach:

python load_memory.py

Die Abfrage muss nach dem Laden ein Ergebnis aus dem gespeicherten Zustand liefern. Prüfen Sie zusätzlich den Inhalt des Verzeichnisses agent_state und sichern Sie diesen Zustand in Ihrer Testumgebung. Verlassen Sie sich nicht auf index_path= am VectorStore; dieser Parameter ersetzt keinen nachgewiesenen save()- und load()-Ablauf.

Erfahrung aus dem Runbook: Wiederholen Sie den Import derselben Eingabe mindestens einmal. Wenn dadurch zusätzliche Knoten, neue Memory-Einträge oder widersprüchliche Beziehungen entstehen, haben Sie eine wichtige Produktionsfrage gefunden: Wie behandelt Ihre konkrete Version Duplikate, Konflikte und Aktualisierungen?

Schritt 6: Abfragen, Beziehungen und Herkunft einzeln abnehmen

Nehmen Sie die erste Version nicht über eine Oberfläche ab, sondern über kleine, reproduzierbare Prüfungen. Ein brauchbarer Testfall enthält jeweils die Eingabe, die erwartete Beziehung und die Quelle.

Für den Mini-Graphen können Sie folgende Prüfungen dokumentieren:

• Exakte Entität: Existiert der Knoten semantica mit dem erwarteten Typ?
• Direkte Beziehung: Verweist semantica über supports auf agent_memory?
• Nachbarschaft: Liefert get_neighbors("semantica", hops=1) die erwarteten Knoten?
• Semantische Abfrage: Findet context.retrieve() den gespeicherten Satz?
• Provenienz: Bleiben die Metadaten source und kind im Ergebnis nachvollziehbar?
• Neustart: Liefert ein neu erzeugter Context nach load() weiterhin ein Ergebnis?
• Doppelte Eingabe: Bleibt die Struktur stabil, wenn derselbe Datensatz erneut importiert wird?

Semantica stellt im Context-Modul außerdem Methoden wie health(), stats(), save(), load(), export() und import_data() bereit. Welche Methode Sie verwenden, hängt davon ab, ob Sie den laufenden Zustand prüfen, ihn als vollständigen Snapshot speichern oder Daten zwischen Umgebungen übertragen möchten.

Für eine kleine Testdokumentation genügt zunächst eine Datei verification.md mit drei Abschnitten:

Eingabe:
Semantica speichert strukturierte Beziehungen für Agent Memory.

Erwartung:
Die Abfrage nach Semantica findet Agent Memory.

Nachweis:
Ausgabe aus load_memory.py, Datum, Python-Version, Semantica-Version.

Damit können Sie spätere Änderungen an der API oder an den optionalen Backends gegen denselben Ausgangspunkt testen.

Schritt 7: Externe Backends erst nach dem Minimalpfad ergänzen

Nach dem lokalen Nachweis können Sie die Architektur schrittweise erweitern. Die offizielle Dokumentation führt unter anderem Neo4j, FalkorDB, Apache AGE und Amazon Neptune als Graphspeicher sowie FAISS, Pinecone, Weaviate, Qdrant, Milvus und PgVector als Vektorspeicher auf. (offizielle Semantica-Dokumentation)

Installieren Sie immer nur eine zusätzliche Schicht:

python -m pip install "semantica[graph-neo4j]"

Danach erstellen Sie einen neuen Testfall für genau dieses Backend. Vermischen Sie ihn nicht sofort mit LLM-Extraktion, MCP, REST und einem externen Vektorspeicher.

Die offiziellen Installationsbeispiele unterscheiden zwischen dem Kernpaket und optionalen Extras wie semantica[llm-litellm], semantica[graph-neo4j] oder semantica[vectorstore-qdrant]. (offizielle Semantica-README) Praktisch bedeutet das: Jede Zusatzkomponente ist ein eigener Änderungs- und Rückrollpunkt.

Wenn Sie einen externen Graphspeicher anschließen, testen Sie zunächst nur diesen Ablauf:

1. Verbindung mit einer leeren Testdatenbank herstellen.
2. Einen einzelnen Knoten schreiben.
3. Diesen Knoten über die vorgesehene Abfrageschnittstelle lesen.
4. Den Prozess neu starten.
5. Den Knoten erneut lesen.
6. Erst danach den vollständigen Import ausführen.

Für eine produktive Agent-Memory-Architektur sollten Sie außerdem Datenschutz, Zugangsdaten, Verschlüsselung, Löschprozesse und DSGVO-Anforderungen getrennt dokumentieren. Die Möglichkeit, Daten lokal oder selbstverwaltet zu betreiben, ersetzt keine eigene Prüfung der Datenflüsse.

Ihre Abnahme-Checkliste vor dem ersten Teamtest

• [ ] Die virtuelle Python-Umgebung ist aktiviert.
• [ ] python -m pip --version zeigt auf diese Umgebung.
• [ ] python -m pip install semantica läuft ohne ungeprüfte Extras durch.
• [ ] semantica --help zeigt die CLI-Befehlsgruppen.
• [ ] semantica doctor und die Ausgabe in doctor.log sind nachvollziehbar.
• [ ] Der Mini-Graph enthält nur die vorher festgelegten Knoten und Beziehungen.
• [ ] Eine direkte Nachbarschaftsabfrage liefert das erwartete Ergebnis.
• [ ] Ein Agent-Memory-Eintrag besitzt eine nachvollziehbare Quelle.
• [ ] context.save("agent_state") erzeugt einen speicherbaren Zustand.
• [ ] Ein neuer Prozess kann diesen Zustand mit context.load() laden.
• [ ] Der doppelte Import wurde geprüft und sein Verhalten dokumentiert.
• [ ] Jede optionale Erweiterung besitzt einen eigenen Test und einen Rückrollpunkt.

Wenn Sie diese Punkte nicht vollständig abhaken können, ist der nächste Schritt nicht die Installation von all, sondern die Eingrenzung des letzten funktionierenden Zustands. Bei einem Importfehler prüfen Sie die installierte Version und den konkreten Traceback zuerst in der Macstripe-Hilfe zur Fehleranalyse. Für größere Installationsvarianten können Sie anschließend Ihre Mac-Konfiguration für reproduzierbare Entwicklungsumgebungen planen.

Der sinnvollere nächste Schritt für Ihre Umgebung

Wenn der Minimalpfad funktioniert, ist eine saubere, zurücksetzbare Entwicklungsumgebung oft wertvoller als ein weiterer Versuch auf einer bereits belasteten lokalen Installation. Eine gemietete Mac-Umgebung von Macstripe kann Ihnen dabei helfen, ein unverändertes Image für die Kernversion und eine getrennte Umgebung für die vollständigen Abhängigkeiten bereitzuhalten. Das ist besonders nützlich, wenn Sie Installationsfehler reproduzieren, Neustarts testen oder mehrere Python-Setups vergleichen müssen.

Für einen dauerhaften Hochlastbetrieb, spezielle physische Schnittstellen oder langfristig unveränderte Workloads kann ein eigener Mac wirtschaftlicher sein. Für kurzfristige Semantica-Tests, saubere Reproduktionen und wechselnde Agent-Memory-Abhängigkeiten bietet eine zurücksetzbare Umgebung jedoch den entscheidenden Vorteil: Sie können nach einem fehlerhaften Backend-Test wieder auf den geprüften Zustand „Installation—Health Check—Schreiben—Abfrage—Persistenz“ zurückgehen, statt Ihr Hauptsystem weiter zu verunreinigen.

Weiterführende Lektüre

• Wissensdatenbanken mit Vektorspeichern richtig planen
• Wissensgraphen für KI und große Codebasen verstehen
• Warum ein virtuelles Dateisystem für KI-Agenten wichtig ist