kore-memory 2.4.0__tar.gz → 2.5.0__tar.gz

{kore_memory-2.4.0 → kore_memory-2.5.0}/CHANGELOG.md

@@ -11,6 +11,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.5.0] - 2026-04-14
+
+### Theme: "Filesystem Watcher — Live Overlay Sync"
+
+### Added
+
+#### Filesystem Watcher (`kore_memory/filesystem_watcher.py`)
+- **Nuovo modulo** che monitora in background le directory tramite `watchdog` e aggiorna automaticamente il filesystem overlay quando i file cambiano su disco
+- `_WatcherRegistry`: thread-safe registry dei watcher attivi, keyed by `agent_id:base_path`
+- `_KoreFileHandler`: gestisce CREATE/MODIFY con debounce 1s (evita burst da IDE auto-save), DELETE immediato, MOVE = remove vecchio + reindex nuovo
+- Estensioni monitorate: `.md .rst .toml .txt .json .yaml .yml .py .cfg` + nomi file da `DEFAULT_PATTERNS`
+- **Graceful degradation**: se `watchdog` non è installato, il modulo carica senza crash (`_HAS_WATCHDOG` flag), `start_watcher()` solleva `ImportError` chiaro
+- API pubblica: `start_watcher`, `stop_watcher`, `stop_all_watchers`, `list_watchers`, `is_available`
+- Graceful shutdown: `stop_all_watchers()` chiamato nel lifespan FastAPI prima del pool cleanup
+
+#### Nuovi endpoint REST
+- `POST /overlay/watch` — avvia watcher per `base_path` (503 se watchdog non installato, 400 se path non valido)
+- `DELETE /overlay/watch?path=...` — ferma watcher per path/agent
+- `GET /overlay/watchers` — lista watcher attivi con statistiche (`events_processed`, `active`, `started_at`)
+
+#### Nuovi modelli Pydantic
+- `OverlayWatchRequest`, `OverlayWatchResponse`, `OverlayWatcherRecord`, `OverlayWatchersResponse`
+
+#### Nuova optional dependency
+- `pip install 'kore-memory[watcher]'` installa `watchdog>=4.0.0`
+
+### Tests
+- **35 test** nel nuovo `tests/test_wave3_watcher.py` (2 skip se watchdog non installato):
+  - `TestWatcherAvailability` (3 test): flag, is_available(), ImportError senza watchdog
+  - `TestWatcherRegistry` (8 test): key format, add/get/remove, stop_all
+  - `TestKoreFileHandler` (12 test): is_relevant, debounce, on_modified/created/deleted/moved, do_reindex/do_remove
+  - `TestStartStopWatcher` (7 test): start/stop lifecycle, already_running, list
+  - `TestWatcherEndpoints` (6 test): REST API GET/POST/DELETE + full lifecycle
+- Suite totale: **629 test** (da 572 → +57 inclusi test v2.4.0 precedenti)
+
+---
+
 ## [2.4.0] - 2026-04-14
 
 ### Theme: "Dashboard Fixes + MCP Auto-Session"

{kore_memory-2.4.0 → kore_memory-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kore-memory
-Version: 2.4.0
+Version: 2.5.0
 Summary: The memory layer that thinks like a human: remembers what matters, forgets what doesn't, and never calls home.
 Project-URL: Homepage, https://github.com/auriti-labs/kore-memory
 Project-URL: Documentation, https://auritidesign.it/docs
@@ -43,6 +43,8 @@ Requires-Dist: pydantic-ai>=0.0.49; extra == 'pydantic-ai'
 Provides-Extra: semantic
 Requires-Dist: sentence-transformers>=3.0.0; extra == 'semantic'
 Requires-Dist: sqlite-vec>=0.1.1; extra == 'semantic'
+Provides-Extra: watcher
+Requires-Dist: watchdog>=4.0.0; extra == 'watcher'
 Description-Content-Type: text/markdown
 
 <div align="center">

{kore_memory-2.4.0 → kore_memory-2.5.0}/kore_memory/config.py

@@ -85,4 +85,4 @@ CONFLICT_MAX_CANDIDATES = int(os.getenv("KORE_CONFLICT_MAX_CANDIDATES", "10"))
 
 # ── Version ───────────────────────────────────────────────────────────────────
 
-VERSION = "2.4.0"
+VERSION = "2.5.0"

kore_memory-2.5.0/kore_memory/filesystem_watcher.py

@@ -0,0 +1,343 @@
+"""
+Kore — Filesystem Watcher (Wave 3, issue #025)
+
+Auto-aggiorna il filesystem overlay quando i file monitorati cambiano su disco.
+Richiede: pip install kore-memory[watcher]  (watchdog>=4.0.0)
+
+Funzionalità:
+- Monitora i file dell'overlay in background via watchdog Observer
+- CREATE/MODIFY → re-index con debounce da 1s (evita burst da auto-save IDE)
+- DELETE → remove_file_from_overlay()
+- Watcher per (base_path, agent_id) — multipli watchers supportati
+- Graceful degradation: se watchdog non disponibile, errori chiari senza crash
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .filesystem_overlay import DEFAULT_PATTERNS, index_files, remove_file_from_overlay
+
+logger = logging.getLogger(__name__)
+
+# ── Disponibilità watchdog ────────────────────────────────────────────────────
+
+try:
+    from watchdog.events import FileSystemEventHandler
+    from watchdog.observers import Observer as _Observer
+
+    _HAS_WATCHDOG = True
+except ImportError:
+    _HAS_WATCHDOG = False
+    # Fallback per type annotations senza watchdog installato
+    FileSystemEventHandler = object  # type: ignore[assignment,misc]
+
+_DEBOUNCE_SECONDS = 1.0  # attesa dopo l'ultimo evento prima di re-indexare
+
+# Estensioni di file monitorate dal watcher
+_WATCHED_EXTENSIONS = frozenset({".md", ".rst", ".toml", ".txt", ".json", ".yaml", ".yml", ".py", ".cfg"})
+
+
+# ── Struttura dati watcher ────────────────────────────────────────────────────
+
+
+class _WatcherEntry:
+    """Rappresenta un watcher attivo per una (base_path, agent_id)."""
+
+    def __init__(
+        self,
+        base_path: str,
+        agent_id: str,
+        patterns: list[str] | None,
+        include_extra_md: bool,
+        max_depth: int,
+    ) -> None:
+        self.base_path = base_path
+        self.agent_id = agent_id
+        self.patterns = patterns
+        self.include_extra_md = include_extra_md
+        self.max_depth = max_depth
+        self.observer: Any = None
+        self.started_at: str = datetime.now(UTC).isoformat()
+        self.events_processed: int = 0
+
+
+class _WatcherRegistry:
+    """Registry thread-safe dei watcher attivi."""
+
+    def __init__(self) -> None:
+        self._watchers: dict[str, _WatcherEntry] = {}
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def _key(base_path: str, agent_id: str) -> str:
+        return f"{agent_id}:{base_path}"
+
+    def add(self, entry: _WatcherEntry) -> None:
+        with self._lock:
+            self._watchers[self._key(entry.base_path, entry.agent_id)] = entry
+
+    def remove(self, base_path: str, agent_id: str) -> _WatcherEntry | None:
+        with self._lock:
+            return self._watchers.pop(self._key(base_path, agent_id), None)
+
+    def get(self, base_path: str, agent_id: str) -> _WatcherEntry | None:
+        with self._lock:
+            return self._watchers.get(self._key(base_path, agent_id))
+
+    def list_all(self) -> list[dict]:
+        with self._lock:
+            return [
+                {
+                    "base_path": e.base_path,
+                    "agent_id": e.agent_id,
+                    "started_at": e.started_at,
+                    "events_processed": e.events_processed,
+                    "active": e.observer is not None and e.observer.is_alive(),
+                }
+                for e in self._watchers.values()
+            ]
+
+    def stop_all(self) -> int:
+        """Ferma tutti i watcher — chiamato al shutdown del server."""
+        with self._lock:
+            entries = list(self._watchers.values())
+            self._watchers.clear()
+        count = 0
+        for entry in entries:
+            if entry.observer:
+                try:
+                    entry.observer.stop()
+                    entry.observer.join(timeout=2)
+                    count += 1
+                except Exception:
+                    pass
+        return count
+
+
+_registry = _WatcherRegistry()
+
+
+# ── Event handler ─────────────────────────────────────────────────────────────
+
+
+class _KoreFileHandler(FileSystemEventHandler):  # type: ignore[misc]
+    """Gestisce gli eventi del filesystem e aggiorna l'overlay con debounce."""
+
+    def __init__(self, entry: _WatcherEntry) -> None:
+        if _HAS_WATCHDOG:
+            super().__init__()
+        self._entry = entry
+        self._timers: dict[str, threading.Timer] = {}
+        self._timers_lock = threading.Lock()
+
+    # ── Debounce ──────────────────────────────────────────────────────────────
+
+    def _schedule_reindex(self, filepath: str) -> None:
+        """Annulla il timer pendente e ne avvia uno nuovo (debounce 1s)."""
+        with self._timers_lock:
+            existing = self._timers.get(filepath)
+            if existing:
+                existing.cancel()
+            timer = threading.Timer(_DEBOUNCE_SECONDS, self._do_reindex, args=[filepath])
+            self._timers[filepath] = timer
+            timer.start()
+
+    def _do_reindex(self, filepath: str) -> None:
+        """Re-indicizza il file nel filesystem overlay."""
+        with self._timers_lock:
+            self._timers.pop(filepath, None)
+
+        try:
+            path = Path(filepath)
+            if not path.exists() or not path.is_file():
+                return
+            stats = index_files(
+                filepaths=[path],
+                agent_id=self._entry.agent_id,
+                replace_existing=True,
+            )
+            self._entry.events_processed += 1
+            logger.info(
+                "Watcher re-indexed %s (agent=%s, updated=%d, indexed=%d)",
+                filepath,
+                self._entry.agent_id,
+                stats.get("updated", 0),
+                stats.get("indexed", 0),
+            )
+        except Exception as exc:
+            logger.error("Watcher: errore re-index %s: %s", filepath, exc)
+
+    def _do_remove(self, filepath: str) -> None:
+        """Rimuove le memories del file eliminato dall'overlay."""
+        try:
+            removed = remove_file_from_overlay(filepath, agent_id=self._entry.agent_id)
+            if removed:
+                self._entry.events_processed += 1
+                logger.info(
+                    "Watcher: rimosso overlay per file eliminato %s (agent=%s, memories=%d)",
+                    filepath,
+                    self._entry.agent_id,
+                    removed,
+                )
+        except Exception as exc:
+            logger.error("Watcher: errore rimozione overlay %s: %s", filepath, exc)
+
+    # ── Filtro file ───────────────────────────────────────────────────────────
+
+    def _is_relevant(self, filepath: str) -> bool:
+        """
+        True se il file è dentro base_path e ha un'estensione o nome rilevante.
+        """
+        path = Path(filepath)
+        try:
+            path.relative_to(self._entry.base_path)
+        except ValueError:
+            return False
+
+        if path.suffix.lower() in _WATCHED_EXTENSIONS:
+            return True
+
+        watched_names = set(self._entry.patterns or DEFAULT_PATTERNS)
+        return path.name in watched_names
+
+    # ── Handlers watchdog ─────────────────────────────────────────────────────
+
+    def on_modified(self, event: Any) -> None:
+        if not event.is_directory and self._is_relevant(event.src_path):
+            self._schedule_reindex(event.src_path)
+
+    def on_created(self, event: Any) -> None:
+        if not event.is_directory and self._is_relevant(event.src_path):
+            self._schedule_reindex(event.src_path)
+
+    def on_deleted(self, event: Any) -> None:
+        if not event.is_directory:
+            self._do_remove(event.src_path)
+
+    def on_moved(self, event: Any) -> None:
+        """Rinomina = elimina vecchio + indicizza nuovo."""
+        if not event.is_directory:
+            self._do_remove(event.src_path)
+            if self._is_relevant(event.dest_path):
+                self._schedule_reindex(event.dest_path)
+
+
+# ── API pubblica ──────────────────────────────────────────────────────────────
+
+
+def start_watcher(
+    base_path: str,
+    agent_id: str = "default",
+    patterns: list[str] | None = None,
+    include_extra_md: bool = True,
+    max_depth: int = 2,
+) -> dict:
+    """
+    Avvia un watcher per base_path. Richiede watchdog installato.
+
+    Raises:
+        ImportError: se watchdog non è installato
+        ValueError: se base_path non è una directory esistente
+    """
+    if not _HAS_WATCHDOG:
+        raise ImportError("watchdog non installato. Eseguire: pip install 'kore-memory[watcher]'")
+
+    resolved = str(Path(base_path).resolve())
+    if not Path(resolved).is_dir():
+        raise ValueError(f"base_path deve essere una directory esistente: {resolved!r}")
+
+    # Watcher già attivo per questa coppia (path, agent)?
+    existing = _registry.get(resolved, agent_id)
+    if existing and existing.observer and existing.observer.is_alive():
+        return {
+            "watching": True,
+            "already_running": True,
+            "base_path": resolved,
+            "agent_id": agent_id,
+            "started_at": existing.started_at,
+            "message": "Watcher già attivo",
+        }
+
+    entry = _WatcherEntry(
+        base_path=resolved,
+        agent_id=agent_id,
+        patterns=patterns,
+        include_extra_md=include_extra_md,
+        max_depth=max_depth,
+    )
+
+    handler = _KoreFileHandler(entry)
+    observer = _Observer()
+    observer.schedule(handler, resolved, recursive=True)
+    observer.start()
+
+    entry.observer = observer
+    _registry.add(entry)
+
+    logger.info("Watcher avviato: base_path=%s agent=%s", resolved, agent_id)
+    return {
+        "watching": True,
+        "already_running": False,
+        "base_path": resolved,
+        "agent_id": agent_id,
+        "started_at": entry.started_at,
+        "message": "Watcher avviato",
+    }
+
+
+def stop_watcher(base_path: str, agent_id: str = "default") -> dict:
+    """Ferma il watcher per (base_path, agent_id)."""
+    resolved = str(Path(base_path).resolve())
+    entry = _registry.remove(resolved, agent_id)
+
+    if not entry:
+        return {
+            "stopped": False,
+            "base_path": resolved,
+            "agent_id": agent_id,
+            "message": "Nessun watcher attivo trovato",
+        }
+
+    if entry.observer:
+        try:
+            entry.observer.stop()
+            entry.observer.join(timeout=3)
+        except Exception as exc:
+            logger.warning("Errore stop observer %s: %s", resolved, exc)
+
+    logger.info(
+        "Watcher fermato: base_path=%s agent=%s events=%d",
+        resolved,
+        agent_id,
+        entry.events_processed,
+    )
+    return {
+        "stopped": True,
+        "base_path": resolved,
+        "agent_id": agent_id,
+        "events_processed": entry.events_processed,
+        "message": "Watcher fermato",
+    }
+
+
+def stop_all_watchers() -> int:
+    """Ferma tutti i watcher attivi. Chiamato al shutdown del server."""
+    count = _registry.stop_all()
+    if count:
+        logger.info("Watcher: fermati %d observer al shutdown", count)
+    return count
+
+
+def list_watchers() -> list[dict]:
+    """Restituisce la lista dei watcher attivi con statistiche."""
+    return _registry.list_all()
+
+
+def is_available() -> bool:
+    """True se watchdog è installato e il watcher è disponibile."""
+    return _HAS_WATCHDOG

{kore_memory-2.4.0 → kore_memory-2.5.0}/kore_memory/main.py

@@ -57,6 +57,10 @@ from .models import (
     OverlayFilesResponse,
     OverlayIndexRequest,
     OverlayIndexResponse,
+    OverlayWatcherRecord,
+    OverlayWatchersResponse,
+    OverlayWatchRequest,
+    OverlayWatchResponse,
     PluginListResponse,
     RelationRecord,
     RelationRequest,
@@ -222,6 +226,10 @@ async def lifespan(app: FastAPI):
 
         register_audit_handler()
     yield
+    # Graceful shutdown: ferma i watcher attivi
+    from .filesystem_watcher import stop_all_watchers
+
+    stop_all_watchers()
     # Graceful shutdown: close the SQLite connection pool
     from .database import _pool
 
@@ -1283,6 +1291,64 @@ def overlay_remove_file(
     return {"removed": removed, "path": path}
 
 
+# ── Filesystem Watcher (issue #025) ──────────────────────────────────────────
+
+
+@app.post("/overlay/watch", response_model=OverlayWatchResponse)
+def overlay_watch_start(
+    body: OverlayWatchRequest,
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> OverlayWatchResponse:
+    """
+    Avvia un watcher su base_path che auto-aggiorna l'overlay al cambio dei file.
+    Richiede: pip install kore-memory[watcher]
+    """
+    from .filesystem_watcher import start_watcher
+
+    try:
+        patterns = body.patterns if body.patterns else None
+        result = start_watcher(
+            base_path=body.base_path,
+            agent_id=agent_id,
+            patterns=patterns,
+            include_extra_md=body.include_extra_md,
+            max_depth=body.max_depth,
+        )
+        return OverlayWatchResponse(**result)
+    except ImportError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.delete("/overlay/watch", response_model=dict)
+def overlay_watch_stop(
+    path: str = Query(..., description="base_path del watcher da fermare"),
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> dict:
+    """Ferma il watcher attivo per base_path."""
+    from .filesystem_watcher import stop_watcher
+
+    return stop_watcher(base_path=path, agent_id=agent_id)
+
+
+@app.get("/overlay/watchers", response_model=OverlayWatchersResponse)
+def overlay_watchers(
+    _: str = _Auth,
+) -> OverlayWatchersResponse:
+    """Lista tutti i watcher attivi con statistiche."""
+    from .filesystem_watcher import is_available, list_watchers
+
+    watchers = list_watchers()
+    return OverlayWatchersResponse(
+        watchers=[OverlayWatcherRecord(**w) for w in watchers],
+        total=len(watchers),
+        watcher_available=is_available(),
+    )
+
+
 # ── Audit log ────────────────────────────────────────────────────────────────
 
 

{kore_memory-2.4.0 → kore_memory-2.5.0}/kore_memory/models.py

@@ -443,6 +443,43 @@ class OverlayFilesResponse(BaseModel):
     total: int
 
 
+# ── Filesystem Watcher (issue #025) ──────────────────────────────────────────
+
+
+class OverlayWatchRequest(BaseModel):
+    base_path: str = Field(..., min_length=1, max_length=1024, description="Directory da monitorare")
+    patterns: list[str] = Field(
+        default_factory=list,
+        description="Pattern filename da monitorare (vuoto = DEFAULT_PATTERNS)",
+        max_length=50,
+    )
+    include_extra_md: bool = Field(True, description="Monitora anche file .md extra")
+    max_depth: int = Field(2, ge=1, le=5, description="Profondità massima di scansione al re-index")
+
+
+class OverlayWatcherRecord(BaseModel):
+    base_path: str
+    agent_id: str
+    started_at: str
+    events_processed: int
+    active: bool
+
+
+class OverlayWatchResponse(BaseModel):
+    watching: bool
+    already_running: bool = False
+    base_path: str
+    agent_id: str
+    started_at: str = ""
+    message: str
+
+
+class OverlayWatchersResponse(BaseModel):
+    watchers: list[OverlayWatcherRecord]
+    total: int
+    watcher_available: bool
+
+
 # ── Summarization ────────────────────────────────────────────────────────────
 
 

{kore_memory-2.4.0 → kore_memory-2.5.0}/kore_memory/repository/search.py

@@ -346,7 +346,9 @@ def _count_active_memories(
             params: dict = {"query": safe_query, "agent_id": agent_id}
         else:
             # Caso speciale: q=* → conta tutte le memorie attive (wildcard globale)
-            escaped = "" if query.strip() == "*" else query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            escaped = (
+                "" if query.strip() == "*" else query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+            )
             sql = f"""
                 SELECT COUNT(*) FROM memories
                 WHERE content LIKE :query ESCAPE '\\'

{kore_memory-2.4.0 → kore_memory-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kore-memory"
-version = "2.4.0"
+version = "2.5.0"
 description = "The memory layer that thinks like a human: remembers what matters, forgets what doesn't, and never calls home."
 readme = "README.md"
 license = { text = "MIT" }
@@ -50,6 +50,9 @@ pydantic-ai = [
 openai-agents = [
     "openai-agents>=0.2.0",
 ]
+watcher = [
+    "watchdog>=4.0.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",

{kore_memory-2.4.0 → kore_memory-2.5.0}/sdk/js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kore-memory-client",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "JavaScript/TypeScript client for Kore Memory - the memory layer that thinks like a human",
   "type": "module",
   "main": "./dist/index.cjs",