kepta 0.1.0__tar.gz

kepta-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# deps
+node_modules/
+.pnp/
+.pnp.js
+
+# build
+dist/
+out/
+release/
+build/*
+!build/icon.icns
+!build/icon.png
+!build/icon.iconset
+!build/icon.iconset/**
+*.tsbuildinfo
+
+# os
+.DS_Store
+Thumbs.db
+
+# logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env & secrets
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+firebase-applet-config.json
+!firebase-applet-config.example.json
+
+# electron
+*.dmg
+*.blockmap
+*.zip
+*.snap
+*.AppImage
+*.exe
+
+# editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# caches
+.cache/
+.parcel-cache/
+project.tar.gz
+*.tar.gz
+
+# lokale Agent-Konfiguration
+.mcp.json
+
+# coverage
+coverage/
+
+# Python
+__pycache__/
+*.egg-info/
+.pytest_cache/
+*.py[cod]

kepta-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: kepta
+Version: 0.1.0
+Summary: Python-Client für KEPTA — das lokale Gedächtnis für KI-Agenten. Ohne Cloud, ohne Konto.
+Project-URL: Homepage, https://github.com/DamianTodorovic/kepta
+Project-URL: Repository, https://github.com/DamianTodorovic/kepta
+Project-URL: Issues, https://github.com/DamianTodorovic/kepta/issues
+Project-URL: Changelog, https://github.com/DamianTodorovic/kepta/blob/main/CHANGELOG.md
+Author-email: KEPTA <hello@kepta.app>
+License: MIT
+Keywords: agents,ai,knowledge-graph,local-first,mcp,memory,privacy,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kepta
+
+**Python-Client für [KEPTA](https://github.com/DamianTodorovic/kepta) — dem lokalen Gedächtnis für KI-Agenten.**
+
+Deine Agenten vergessen dich nach jedem Gespräch. KEPTA behebt das — mit einer SQLite-Datei auf deinem Rechner. Kein Konto, keine Cloud, keine Telemetrie.
+
+Dieses Paket ist der **Client, nicht die App**. KEPTA läuft als Desktop-Anwendung auf demselben Gerät; hier verbindest du dich damit.
+
+```bash
+pip install kepta
+```
+
+## In dreißig Sekunden
+
+```python
+from kepta import KeptaClient
+
+kepta = KeptaClient()          # findet die laufende Instanz von allein
+
+kepta.save("Rezept Carbonara", "Guanciale, Pecorino, Eigelb. Keine Sahne.", tags=["kochen"])
+
+for hit in kepta.search("was koche ich mit Nudeln"):
+    print(f"{hit.score:.2f}  {hit.memory.title}")
+```
+
+Das Wort *Nudeln* steht in der Notiz nicht. Gefunden wird sie trotzdem — die Suche kombiniert Volltext, Vektoren und Wissensgraph per Reciprocal Rank Fusion.
+
+## Warum das interessant ist
+
+**Dasselbe Gedächtnis wie deine Agenten.** Claude Desktop und Cursor sprechen über MCP mit derselben Datenbank. Was dein Python-Skript schreibt, weiß Claude in der nächsten Antwort.
+
+**Erinnerungen altern.** Jede hat Typ, Gültigkeit und Konfidenz. Zieht jemand um, verdrängt die neue Adresse die alte — die alte bleibt als Historie und fällt im Ranking ab. Widersprüche stapeln sich nicht.
+
+```python
+alt = kepta.save("Wohnort", "Alex wohnt in Hamburg.")
+kepta.update(alt.id, valid_to=1788400000000)      # abgelaufen ab diesem Zeitpunkt
+kepta.save("Wohnort aktuell", "Alex wohnt jetzt in Leipzig.")
+
+m = kepta.list()[0]
+m.is_expired, m.is_superseded                      # Zustand direkt am Objekt
+```
+
+**Keine Abhängigkeiten.** Nur die Standardbibliothek. Ein Gedächtnis, das Privatsphäre verspricht, sollte keinen fremden Code in deinen Prozess holen.
+
+## Die Verbindung finden
+
+`KeptaClient()` sucht in dieser Reihenfolge:
+
+1. Umgebungsvariable `KEPTA_URL`
+2. `~/.kepta/endpoint.json` — die Adressdatei, die KEPTA beim Start schreibt
+3. `http://127.0.0.1:3000` als Rückfall für den Entwicklungsmodus
+
+Schritt 2 ist der wichtige: Die gepackte App wählt einen zufälligen Port. Explizit geht natürlich auch:
+
+```python
+kepta = KeptaClient("http://127.0.0.1:52341")
+```
+
+Läuft nichts, bekommst du keinen kryptischen Netzwerkfehler, sondern einen Satz, der sagt, was zu tun ist:
+
+```python
+if not kepta.is_alive():
+    print("KEPTA läuft nicht — App starten oder KEPTA_URL setzen.")
+```
+
+## Was der Client kann
+
+| Methode | Zweck |
+|---|---|
+| `health()` · `is_alive()` | Status, Version, Anzahl Knoten |
+| `list(trash=False)` | Alle Erinnerungen oder den Papierkorb |
+| `search(query, top_k, tags, type, scope)` | Hybride Suche mit temporaler Gewichtung |
+| `save(title, content, …)` | Anlegen — Typ, Tags, Konfidenz, Gültigkeit |
+| `update(id, **felder)` | Ändern; `valid_to=` statt `validTo=` |
+| `delete(id, permanent=False)` | Papierkorb, auf Wunsch endgültig |
+| `restore(id)` | Aus dem Papierkorb zurückholen |
+| `graph()` | Entitäten und Relationen |
+
+`Memory` und `SearchHit` sind eingefrorene Dataclasses mit Typannotationen. `SearchHit` zeigt neben dem Gesamtwert auch die Einzelspuren `vector_score` und `lexical_score`.
+
+## KEPTA installieren
+
+Die App gibt es für macOS, Windows und Linux unter [Releases](https://github.com/DamianTodorovic/kepta/releases) — jeweils Intel und ARM. MIT-Lizenz, kostenlos.
+
+## Lizenz
+
+MIT

kepta-0.1.0/README.md

@@ -0,0 +1,87 @@
+# kepta
+
+**Python-Client für [KEPTA](https://github.com/DamianTodorovic/kepta) — dem lokalen Gedächtnis für KI-Agenten.**
+
+Deine Agenten vergessen dich nach jedem Gespräch. KEPTA behebt das — mit einer SQLite-Datei auf deinem Rechner. Kein Konto, keine Cloud, keine Telemetrie.
+
+Dieses Paket ist der **Client, nicht die App**. KEPTA läuft als Desktop-Anwendung auf demselben Gerät; hier verbindest du dich damit.
+
+```bash
+pip install kepta
+```
+
+## In dreißig Sekunden
+
+```python
+from kepta import KeptaClient
+
+kepta = KeptaClient()          # findet die laufende Instanz von allein
+
+kepta.save("Rezept Carbonara", "Guanciale, Pecorino, Eigelb. Keine Sahne.", tags=["kochen"])
+
+for hit in kepta.search("was koche ich mit Nudeln"):
+    print(f"{hit.score:.2f}  {hit.memory.title}")
+```
+
+Das Wort *Nudeln* steht in der Notiz nicht. Gefunden wird sie trotzdem — die Suche kombiniert Volltext, Vektoren und Wissensgraph per Reciprocal Rank Fusion.
+
+## Warum das interessant ist
+
+**Dasselbe Gedächtnis wie deine Agenten.** Claude Desktop und Cursor sprechen über MCP mit derselben Datenbank. Was dein Python-Skript schreibt, weiß Claude in der nächsten Antwort.
+
+**Erinnerungen altern.** Jede hat Typ, Gültigkeit und Konfidenz. Zieht jemand um, verdrängt die neue Adresse die alte — die alte bleibt als Historie und fällt im Ranking ab. Widersprüche stapeln sich nicht.
+
+```python
+alt = kepta.save("Wohnort", "Alex wohnt in Hamburg.")
+kepta.update(alt.id, valid_to=1788400000000)      # abgelaufen ab diesem Zeitpunkt
+kepta.save("Wohnort aktuell", "Alex wohnt jetzt in Leipzig.")
+
+m = kepta.list()[0]
+m.is_expired, m.is_superseded                      # Zustand direkt am Objekt
+```
+
+**Keine Abhängigkeiten.** Nur die Standardbibliothek. Ein Gedächtnis, das Privatsphäre verspricht, sollte keinen fremden Code in deinen Prozess holen.
+
+## Die Verbindung finden
+
+`KeptaClient()` sucht in dieser Reihenfolge:
+
+1. Umgebungsvariable `KEPTA_URL`
+2. `~/.kepta/endpoint.json` — die Adressdatei, die KEPTA beim Start schreibt
+3. `http://127.0.0.1:3000` als Rückfall für den Entwicklungsmodus
+
+Schritt 2 ist der wichtige: Die gepackte App wählt einen zufälligen Port. Explizit geht natürlich auch:
+
+```python
+kepta = KeptaClient("http://127.0.0.1:52341")
+```
+
+Läuft nichts, bekommst du keinen kryptischen Netzwerkfehler, sondern einen Satz, der sagt, was zu tun ist:
+
+```python
+if not kepta.is_alive():
+    print("KEPTA läuft nicht — App starten oder KEPTA_URL setzen.")
+```
+
+## Was der Client kann
+
+| Methode | Zweck |
+|---|---|
+| `health()` · `is_alive()` | Status, Version, Anzahl Knoten |
+| `list(trash=False)` | Alle Erinnerungen oder den Papierkorb |
+| `search(query, top_k, tags, type, scope)` | Hybride Suche mit temporaler Gewichtung |
+| `save(title, content, …)` | Anlegen — Typ, Tags, Konfidenz, Gültigkeit |
+| `update(id, **felder)` | Ändern; `valid_to=` statt `validTo=` |
+| `delete(id, permanent=False)` | Papierkorb, auf Wunsch endgültig |
+| `restore(id)` | Aus dem Papierkorb zurückholen |
+| `graph()` | Entitäten und Relationen |
+
+`Memory` und `SearchHit` sind eingefrorene Dataclasses mit Typannotationen. `SearchHit` zeigt neben dem Gesamtwert auch die Einzelspuren `vector_score` und `lexical_score`.
+
+## KEPTA installieren
+
+Die App gibt es für macOS, Windows und Linux unter [Releases](https://github.com/DamianTodorovic/kepta/releases) — jeweils Intel und ARM. MIT-Lizenz, kostenlos.
+
+## Lizenz
+
+MIT

kepta-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kepta"
+version = "0.1.0"
+description = "Python-Client für KEPTA — das lokale Gedächtnis für KI-Agenten. Ohne Cloud, ohne Konto."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "KEPTA", email = "hello@kepta.app" }]
+keywords = ["memory", "ai", "agents", "mcp", "local-first", "privacy", "knowledge-graph", "rag"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+# Bewusst ohne Abhängigkeiten: nur die Standardbibliothek. Ein Gedächtnis, das
+# Privatsphäre verspricht, sollte keinen fremden Code in deinen Prozess holen.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/DamianTodorovic/kepta"
+Repository = "https://github.com/DamianTodorovic/kepta"
+Issues = "https://github.com/DamianTodorovic/kepta/issues"
+Changelog = "https://github.com/DamianTodorovic/kepta/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kepta"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

kepta-0.1.0/src/kepta/__init__.py

@@ -0,0 +1,39 @@
+"""KEPTA — lokales Gedächtnis für KI-Agenten, von Python aus.
+
+Dieses Paket ist der Client, nicht die App. KEPTA selbst läuft als Desktop-App
+auf demselben Rechner; hier verbindest du dich damit.
+
+    from kepta import KeptaClient
+
+    kepta = KeptaClient()          # findet die laufende Instanz von allein
+    kepta.save("Wohnort", "Alex wohnt in Hamburg.", tags=["personal"])
+    for hit in kepta.search("wo wohnt Alex"):
+        print(hit.memory.title, hit.score)
+
+Alles bleibt auf dem Gerät: Der Server lauscht nur auf 127.0.0.1.
+"""
+
+from .client import (
+    DEFAULT_URL,
+    KeptaClient,
+    KeptaError,
+    Memory,
+    MemoryType,
+    SearchHit,
+    data_dir,
+    discover_url,
+)
+
+__all__ = [
+    "KeptaClient",
+    "KeptaError",
+    "Memory",
+    "MemoryType",
+    "SearchHit",
+    "discover_url",
+    "data_dir",
+    "DEFAULT_URL",
+    "__version__",
+]
+
+__version__ = "0.1.0"

kepta-0.1.0/src/kepta/client.py

@@ -0,0 +1,247 @@
+"""Python-Client für ein lokal laufendes KEPTA.
+
+KEPTA selbst ist eine Desktop-App (Electron). Dieses Paket installiert sie nicht —
+es spricht mit der HTTP-API der laufenden Instanz, damit Python-Agenten dasselbe
+Gedächtnis nutzen wie Claude Desktop oder Cursor.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Literal
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+MemoryType = Literal["semantic", "episodic", "procedural"]
+
+DEFAULT_URL = "http://127.0.0.1:3000"
+ENDPOINT_FILE = "endpoint.json"
+
+
+class KeptaError(RuntimeError):
+    """KEPTA war nicht erreichbar oder hat einen Fehler zurückgegeben."""
+
+
+def data_dir() -> Path:
+    """Datenverzeichnis von KEPTA. `KEPTA_DATA_DIR` hat Vorrang, sonst ~/.kepta."""
+    override = os.environ.get("KEPTA_DATA_DIR")
+    return Path(override) if override else Path.home() / ".kepta"
+
+
+def discover_url() -> str:
+    """Findet die laufende Instanz.
+
+    Reihenfolge: `KEPTA_URL`, dann die Adressdatei, die der Server beim Start
+    schreibt, sonst der Entwicklungs-Standardport. Die gepackte App wählt einen
+    zufälligen Port — ohne die Datei wäre sie nicht auffindbar.
+    """
+    env = os.environ.get("KEPTA_URL")
+    if env:
+        return env.rstrip("/")
+    try:
+        raw = (data_dir() / ENDPOINT_FILE).read_text(encoding="utf-8")
+        url = json.loads(raw).get("url")
+        if isinstance(url, str) and url:
+            return url.rstrip("/")
+    except (OSError, ValueError):
+        pass
+    return DEFAULT_URL
+
+
+@dataclass(frozen=True)
+class Memory:
+    """Eine Erinnerung. Zeitstempel sind Millisekunden seit Epoch."""
+
+    id: str
+    title: str
+    content: str
+    tags: list[str] = field(default_factory=list)
+    type: MemoryType = "semantic"
+    scope: str = "user"
+    confidence: float | None = None
+    valid_from: int | None = None
+    valid_to: int | None = None
+    superseded_by: str | None = None
+    deleted_at: int | None = None
+    created_at: int | None = None
+    updated_at: int | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        """Gültigkeit abgelaufen? Solche Treffer wertet KEPTA im Ranking ab."""
+        return self.valid_to is not None and self.valid_to < time.time() * 1000
+
+    @property
+    def is_superseded(self) -> bool:
+        """Wurde durch eine neuere Erinnerung ersetzt."""
+        return bool(self.superseded_by)
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> "Memory":
+        return cls(
+            id=str(d.get("id", "")),
+            title=str(d.get("title", "")),
+            content=str(d.get("content", "")),
+            tags=list(d.get("tags") or []),
+            type=d.get("type") or "semantic",
+            scope=d.get("scope") or "user",
+            confidence=d.get("confidence"),
+            valid_from=d.get("validFrom"),
+            valid_to=d.get("validTo"),
+            superseded_by=d.get("supersededBy"),
+            deleted_at=d.get("deletedAt"),
+            created_at=d.get("createdAt"),
+            updated_at=d.get("updatedAt"),
+        )
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    """Ein Suchtreffer mit den Einzelwerten der Suchspuren."""
+
+    memory: Memory
+    score: float
+    vector_score: float = 0.0
+    lexical_score: float = 0.0
+
+    @classmethod
+    def from_api(cls, d: dict[str, Any]) -> "SearchHit":
+        return cls(
+            memory=Memory.from_api(d.get("memory") or {}),
+            score=float(d.get("score") or 0.0),
+            vector_score=float(d.get("cosineScore") or 0.0),
+            lexical_score=float(d.get("bm25Score") or 0.0),
+        )
+
+
+class KeptaClient:
+    """Sprechverbindung zu einer laufenden KEPTA-Instanz.
+
+    >>> kepta = KeptaClient()
+    >>> kepta.save("Rezept Carbonara", "Guanciale, Pecorino, Eigelb.", tags=["kochen"])
+    >>> [h.memory.title for h in kepta.search("was koche ich mit Nudeln")]
+    """
+
+    def __init__(self, url: str | None = None, timeout: float = 20.0) -> None:
+        self.url = (url or discover_url()).rstrip("/")
+        self.timeout = timeout
+
+    # ---------- HTTP ----------
+
+    def _request(self, method: str, path: str, body: Any = None, params: dict[str, Any] | None = None) -> Any:
+        target = f"{self.url}{path}"
+        if params:
+            cleaned = {k: v for k, v in params.items() if v is not None}
+            if cleaned:
+                target += "?" + urlencode(cleaned)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = Request(target, data=data, method=method)
+        req.add_header("Content-Type", "application/json")
+        try:
+            with urlopen(req, timeout=self.timeout) as res:
+                raw = res.read().decode("utf-8")
+                return json.loads(raw) if raw else None
+        except HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:400]
+            raise KeptaError(f"{method} {path} scheiterte ({e.code}): {detail}") from e
+        except (URLError, TimeoutError) as e:
+            raise KeptaError(
+                f"KEPTA unter {self.url} nicht erreichbar. Läuft die App? "
+                f"Alternativ KEPTA_URL setzen. Ursache: {e}"
+            ) from e
+
+    # ---------- Lesen ----------
+
+    def health(self) -> dict[str, Any]:
+        """Statusabfrage — Version, Anzahl Knoten, Pfad der Datenbank."""
+        return self._request("GET", "/api/health")
+
+    def is_alive(self) -> bool:
+        """True, wenn eine Instanz antwortet."""
+        try:
+            return bool(self.health().get("ok"))
+        except KeptaError:
+            return False
+
+    def list(self, *, trash: bool = False) -> list[Memory]:
+        """Alle Erinnerungen. Mit `trash=True` stattdessen den Papierkorb."""
+        data = self._request("GET", "/api/memories", params={"trash": "1" if trash else None})
+        return [Memory.from_api(d) for d in (data or [])]
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        tags: Iterable[str] | None = None,
+        type: MemoryType | None = None,
+        scope: str | None = None,
+    ) -> list[SearchHit]:
+        """Hybride Suche: Volltext, Vektoren und Wissensgraph, per RRF verschmolzen."""
+        body: dict[str, Any] = {"query": query, "topK": max(1, min(int(top_k), 100))}
+        if tags:
+            body["tags"] = list(tags)
+        if type:
+            body["type"] = type
+        if scope:
+            body["scope"] = scope
+        data = self._request("POST", "/api/search", body)
+        return [SearchHit.from_api(d) for d in (data or {}).get("results", [])]
+
+    def graph(self) -> dict[str, Any]:
+        """Entitäten und Relationen des Wissensgraphen."""
+        return self._request("GET", "/api/graph")
+
+    # ---------- Schreiben ----------
+
+    def save(
+        self,
+        title: str,
+        content: str,
+        *,
+        tags: Iterable[str] | None = None,
+        type: MemoryType | None = None,
+        confidence: float | None = None,
+        valid_from: int | None = None,
+        valid_to: int | None = None,
+    ) -> Memory:
+        """Legt eine Erinnerung an."""
+        body: dict[str, Any] = {"title": title, "content": content}
+        if tags is not None:
+            body["tags"] = list(tags)
+        if type is not None:
+            body["type"] = type
+        if confidence is not None:
+            body["confidence"] = max(0.0, min(1.0, float(confidence)))
+        if valid_from is not None:
+            body["validFrom"] = valid_from
+        if valid_to is not None:
+            body["validTo"] = valid_to
+        data = self._request("POST", "/api/memories", body)
+        return Memory.from_api((data or {}).get("memory") or data or {})
+
+    def update(self, memory_id: str, **patch: Any) -> Memory:
+        """Ändert Felder einer Erinnerung. Schlüssel wie bei `save`."""
+        mapping = {"valid_from": "validFrom", "valid_to": "validTo"}
+        body: dict[str, Any] = {"id": memory_id}
+        for key, value in patch.items():
+            body[mapping.get(key, key)] = list(value) if key == "tags" and value is not None else value
+        data = self._request("POST", "/api/memories", body)
+        return Memory.from_api((data or {}).get("memory") or {})
+
+    def delete(self, memory_id: str, *, permanent: bool = False) -> bool:
+        """In den Papierkorb. Mit `permanent=True` endgültig — nicht umkehrbar."""
+        data = self._request(
+            "DELETE", f"/api/memories/{memory_id}", params={"permanent": "1" if permanent else None}
+        )
+        return bool((data or {}).get("ok"))
+
+    def restore(self, memory_id: str) -> bool:
+        """Holt eine Erinnerung aus dem Papierkorb zurück."""
+        data = self._request("POST", f"/api/memories/{memory_id}/restore")
+        return bool((data or {}).get("ok", True))

kepta-0.1.0/tests/test_client.py

@@ -0,0 +1,204 @@
+"""Tests gegen einen Stub-Server — kein laufendes KEPTA nötig."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from kepta import KeptaClient, KeptaError, Memory, SearchHit, discover_url
+
+CALLS: list[tuple[str, str, dict | None]] = []
+
+
+class Stub(BaseHTTPRequestHandler):
+    def log_message(self, *args):  # Testlauf ruhig halten
+        pass
+
+    def _send(self, payload, status=200):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _read(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        return json.loads(self.rfile.read(n)) if n else None
+
+    def do_GET(self):
+        CALLS.append(("GET", self.path, None))
+        if self.path.startswith("/api/health"):
+            return self._send({"ok": True, "version": "2.5.1", "count": 2})
+        if self.path.startswith("/api/memories"):
+            trash = "trash=1" in self.path
+            return self._send([{"id": "m2" if trash else "m1",
+                                "title": "Papierkorb" if trash else "Wohnort",
+                                "content": "x", "tags": ["personal"], "type": "semantic"}])
+        if self.path.startswith("/api/graph"):
+            return self._send({"entities": [], "relations": []})
+        return self._send({"error": "unbekannt"}, 404)
+
+    def do_POST(self):
+        body = self._read()
+        CALLS.append(("POST", self.path, body))
+        if self.path.startswith("/api/search"):
+            return self._send({"results": [
+                {"memory": {"id": "m1", "title": "Rezept Carbonara", "content": "Guanciale",
+                            "tags": ["kochen"], "type": "semantic"},
+                 "score": 0.91, "cosineScore": 0.7, "bm25Score": 0.5}
+            ]})
+        if self.path.endswith("/restore"):
+            return self._send({"ok": True})
+        if self.path.startswith("/api/memories"):
+            return self._send({"memory": {"id": body.get("id", "neu"), "title": body.get("title", ""),
+                                          "content": body.get("content", ""), "tags": body.get("tags", []),
+                                          "type": body.get("type", "semantic")}})
+        return self._send({"error": "unbekannt"}, 404)
+
+    def do_DELETE(self):
+        CALLS.append(("DELETE", self.path, None))
+        return self._send({"ok": True, "permanent": "permanent=1" in self.path})
+
+
+@pytest.fixture()
+def client():
+    CALLS.clear()
+    srv = HTTPServer(("127.0.0.1", 0), Stub)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    yield KeptaClient(f"http://127.0.0.1:{srv.server_address[1]}")
+    srv.shutdown()
+
+
+def test_health_und_is_alive(client):
+    assert client.health()["version"] == "2.5.1"
+    assert client.is_alive() is True
+
+
+def test_list_liefert_memories(client):
+    memories = client.list()
+    assert isinstance(memories[0], Memory)
+    assert memories[0].title == "Wohnort"
+
+
+def test_list_trash_setzt_parameter(client):
+    assert client.list(trash=True)[0].title == "Papierkorb"
+    assert "trash=1" in CALLS[-1][1]
+
+
+def test_list_ohne_trash_haengt_keinen_parameter_an(client):
+    client.list()
+    assert "?" not in CALLS[-1][1]
+
+
+def test_search_liefert_treffer_mit_teilwerten(client):
+    hits = client.search("was koche ich mit Nudeln", top_k=3)
+    assert isinstance(hits[0], SearchHit)
+    assert hits[0].memory.title == "Rezept Carbonara"
+    assert hits[0].score == pytest.approx(0.91)
+    assert hits[0].vector_score == pytest.approx(0.7)
+    assert CALLS[-1][2]["topK"] == 3
+
+
+def test_search_begrenzt_top_k(client):
+    client.search("x", top_k=9999)
+    assert CALLS[-1][2]["topK"] == 100
+    client.search("x", top_k=0)
+    assert CALLS[-1][2]["topK"] == 1
+
+
+def test_search_reicht_filter_durch(client):
+    client.search("x", tags=["kochen"], type="episodic", scope="agent")
+    body = CALLS[-1][2]
+    assert body["tags"] == ["kochen"] and body["type"] == "episodic" and body["scope"] == "agent"
+
+
+def test_save_schickt_felder(client):
+    m = client.save("Titel", "Inhalt", tags=["a"], type="procedural", confidence=0.8)
+    assert m.title == "Titel"
+    body = CALLS[-1][2]
+    assert body["tags"] == ["a"] and body["type"] == "procedural" and body["confidence"] == 0.8
+
+
+def test_save_klemmt_konfidenz_in_den_bereich(client):
+    client.save("t", "c", confidence=5)
+    assert CALLS[-1][2]["confidence"] == 1.0
+    client.save("t", "c", confidence=-3)
+    assert CALLS[-1][2]["confidence"] == 0.0
+
+
+def test_update_uebersetzt_schluessel_nach_camelcase(client):
+    client.update("m1", valid_to=123, tags=["x"])
+    body = CALLS[-1][2]
+    assert body["id"] == "m1" and body["validTo"] == 123 and body["tags"] == ["x"]
+    assert "valid_to" not in body
+
+
+def test_delete_standard_ist_papierkorb(client):
+    assert client.delete("m1") is True
+    assert "permanent" not in CALLS[-1][1]
+
+
+def test_delete_permanent_setzt_parameter(client):
+    client.delete("m1", permanent=True)
+    assert "permanent=1" in CALLS[-1][1]
+
+
+def test_restore(client):
+    assert client.restore("m1") is True
+
+
+def test_graph(client):
+    assert client.graph() == {"entities": [], "relations": []}
+
+
+def test_fehler_bei_nicht_erreichbarem_server():
+    c = KeptaClient("http://127.0.0.1:9")  # Port 9 nimmt keine Verbindungen an
+    with pytest.raises(KeptaError, match="nicht erreichbar"):
+        c.health()
+    assert c.is_alive() is False
+
+
+def test_http_fehler_wird_zu_kepta_error(client):
+    with pytest.raises(KeptaError, match="404"):
+        client._request("GET", "/api/gibtesnicht")
+
+
+class TestMemory:
+    def test_abgelaufen(self):
+        assert Memory(id="1", title="t", content="c", valid_to=1).is_expired is True
+        assert Memory(id="1", title="t", content="c", valid_to=None).is_expired is False
+
+    def test_ersetzt(self):
+        assert Memory(id="1", title="t", content="c", superseded_by="m2").is_superseded is True
+        assert Memory(id="1", title="t", content="c").is_superseded is False
+
+    def test_from_api_faengt_fehlende_felder_ab(self):
+        m = Memory.from_api({})
+        assert m.id == "" and m.tags == [] and m.type == "semantic"
+
+
+class TestDiscoverUrl:
+    def test_env_hat_vorrang(self, monkeypatch):
+        monkeypatch.setenv("KEPTA_URL", "http://beispiel.test:1234/")
+        assert discover_url() == "http://beispiel.test:1234"
+
+    def test_liest_adressdatei(self, monkeypatch, tmp_path):
+        monkeypatch.delenv("KEPTA_URL", raising=False)
+        monkeypatch.setenv("KEPTA_DATA_DIR", str(tmp_path))
+        (tmp_path / "endpoint.json").write_text(json.dumps({"url": "http://127.0.0.1:59999"}))
+        assert discover_url() == "http://127.0.0.1:59999"
+
+    def test_faellt_auf_standard_zurueck(self, monkeypatch, tmp_path):
+        monkeypatch.delenv("KEPTA_URL", raising=False)
+        monkeypatch.setenv("KEPTA_DATA_DIR", str(tmp_path))
+        assert discover_url() == "http://127.0.0.1:3000"
+
+    def test_kaputte_adressdatei_bricht_nicht(self, monkeypatch, tmp_path):
+        monkeypatch.delenv("KEPTA_URL", raising=False)
+        monkeypatch.setenv("KEPTA_DATA_DIR", str(tmp_path))
+        (tmp_path / "endpoint.json").write_text("kein json")
+        assert discover_url() == "http://127.0.0.1:3000"