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

{kore_memory-2.3.0 → kore_memory-2.5.0}/.github/workflows/ci.yml

@@ -150,8 +150,14 @@ jobs:
         run: bandit -r kore_memory/ -c pyproject.toml
 
       - name: Run pip-audit (CVE check)
-        # --skip-editable: salta kore-memory stesso (non su PyPI, non ha CVE propri)
-        run: pip-audit --strict --skip-editable
+        # Audita solo le dipendenze installate, non il package locale (non è su PyPI)
+        # Usiamo -r requirements-audit.txt generato al volo per evitare problemi con editable installs
+        run: |
+          pip list --format=freeze \
+            | grep -v "^kore-memory==" \
+            | grep -v "^kore_memory==" \
+            > /tmp/audit_reqs.txt
+          pip-audit -r /tmp/audit_reqs.txt
 
   lint:
     runs-on: ubuntu-latest

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

@@ -11,6 +11,72 @@ 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"
+
+### Added
+
+#### MCP Auto-Session
+- **Auto-creazione sessione** all'avvio di `kore-mcp`: il primo `memory_save` per ogni `agent_id` crea automaticamente una sessione con ID `kore-mcp-{agent_id}-{YYYYMMDD-HHMMSS}`
+- **Thread-safe**: creazione lazy con double-checked locking (`_get_or_create_session`)
+- **atexit handler**: chiude tutte le sessioni aperte alla terminazione del processo MCP
+- **Propagazione automatica** a `memory_save`, `memory_save_batch`, `memory_save_decision`, `memory_log_regression`
+- La risposta di `memory_save` include ora `session_id` per tracciabilità
+- La tab **Sessions** della dashboard si popola organicamente con una riga per ogni conversazione Claude/MCP
+
+### Fixed
+
+#### Dashboard
+- **Tab Memories**: `_count_active_memories` non gestiva il wildcard `q=*` come `_fts_search` — con query `*` costruiva `LIKE "%*%"` (cerca il carattere asterisco) invece di `LIKE "%%"` (match all). `total` tornava 2 invece di 40
+- **Checkbox Semantic**: rimosso `checked` di default — gli utenti senza `sentence-transformers` ottenevano risultati imprevedibili; il default sicuro è `semantic=false`
+- **Tab Timeline**: mancava `case 'timeline':` in `loadPageData()` — la tab si apriva con `#timeline-list` completamente vuoto, senza messaggi né dati. Fix: auto-carica le ultime memorie in ordine cronologico (`subject=*`) con header contestuale
+
+#### Database
+- **`idx_relations_strength`**: l'indice era nell'`executescript()` iniziale prima che la colonna `strength` venisse aggiunta via ALTER TABLE. Su DB pre-esistenti causava `no such column: strength` al startup. Spostato in `executescript()` separato dopo `_v23_relation_migrations`
+
+### Tests
+- Suite invariata: **572 test**, coverage ≥ 88%
+
+---
+
 ## [2.3.0] - 2026-04-14
 
 ### Theme: "Wave 3 — Graph Engine + Filesystem Overlay"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kore-memory
-Version: 2.3.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.3.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.3.0"
+VERSION = "2.5.0"

{kore_memory-2.3.0 → kore_memory-2.5.0}/kore_memory/database.py

@@ -215,7 +215,7 @@ def init_db() -> None:
             );
             CREATE INDEX IF NOT EXISTS idx_relations_source ON memory_relations (source_id);
             CREATE INDEX IF NOT EXISTS idx_relations_target ON memory_relations (target_id);
-            CREATE INDEX IF NOT EXISTS idx_relations_strength ON memory_relations (strength DESC);
+            -- idx_relations_strength creato dopo la migrazione v2.3 (colonna strength)
 
             -- Audit / event log
             CREATE TABLE IF NOT EXISTS event_logs (
@@ -308,9 +308,11 @@ def init_db() -> None:
         for col, sql in _v23_relation_migrations.items():
             if col not in relation_cols:
                 conn.execute(sql)
-        conn.execute("""
+        # Indice su strength — creato qui (dopo ALTER TABLE) per DB pre-esistenti
+        # e per DB nuovi (la CREATE TABLE usa IF NOT EXISTS, l'indice viene saltato sopra)
+        conn.executescript("""
             CREATE INDEX IF NOT EXISTS idx_relations_strength
-                ON memory_relations (strength DESC)
+                ON memory_relations (strength DESC);
         """)
 
 

{kore_memory-2.3.0 → kore_memory-2.5.0}/kore_memory/filesystem_overlay.py

@@ -287,10 +287,7 @@ def index_files(
 
         for chunk_content_text, chunk_idx in chunks:
             chunk_label = f" [{chunk_idx + 1}/{len(chunks)}]" if len(chunks) > 1 else ""
-            enriched_content = (
-                f"[File: {Path(filepath).name}{chunk_label}]\n"
-                f"{chunk_content_text.strip()}"
-            )
+            enriched_content = f"[File: {Path(filepath).name}{chunk_label}]\n{chunk_content_text.strip()}"
             # Tronca a 4000 chars (limite modello)
             enriched_content = enriched_content[:4000]
 

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.3.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 ────────────────────────────────────────────────────────────────