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

kore_memory-2.3.0/.github/workflows/benchmark.yml

@@ -0,0 +1,48 @@
+name: Benchmark CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-bench-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-bench-
+
+      - name: Installa dipendenze
+        run: pip install -e ".[dev,mcp]" pytest-benchmark
+
+      - name: Esegui suite benchmark
+        run: |
+          pytest tests/benchmarks/ -v \
+            --benchmark-json=results.json \
+            --tb=short
+        env:
+          KORE_TEST_MODE: "1"
+
+      - name: Verifica soglie CI
+        run: python scripts/assert_benchmarks.py --results results.json --strict
+
+      - name: Upload risultati benchmark
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: benchmark-results
+          path: results.json

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

@@ -30,7 +30,7 @@ jobs:
             ${{ runner.os }}-pip-${{ matrix.python-version }}-
 
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: pip install -e ".[dev,mcp]"
 
       - name: Run tests
         run: pytest tests/ -v --tb=short
@@ -57,7 +57,7 @@ jobs:
           key: ${{ runner.os }}-semantic-${{ hashFiles('pyproject.toml') }}
 
       - name: Install with semantic
-        run: pip install -e ".[semantic,dev]"
+        run: pip install -e ".[semantic,dev,mcp]"
 
       - name: Run tests with embeddings
         run: pytest tests/ -v --tb=short
@@ -81,7 +81,7 @@ jobs:
             ${{ runner.os }}-pip-3.12-
 
       - name: Install dependencies
-        run: pip install -e ".[dev,mcp]"
+        run: pip install -e ".[semantic,dev,mcp]"
 
       - name: Run tests with coverage
         run: pytest tests/ -v --cov=kore_memory --cov-report=xml --cov-report=term-missing
@@ -150,7 +150,8 @@ jobs:
         run: bandit -r kore_memory/ -c pyproject.toml
 
       - name: Run pip-audit (CVE check)
-        run: pip-audit --strict
+        # --skip-editable: salta kore-memory stesso (non su PyPI, non ha CVE propri)
+        run: pip-audit --strict --skip-editable
 
   lint:
     runs-on: ubuntu-latest

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

@@ -11,6 +11,190 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.3.0] - 2026-04-14
+
+### Theme: "Wave 3 — Graph Engine + Filesystem Overlay"
+
+### Added
+
+#### Typed Graph Relations (#026)
+- **`strength`** (0.0–1.0) e **`confidence`** (0.0–1.0) su ogni relazione in `memory_relations`
+- Upsert automatico: `ON CONFLICT DO UPDATE SET` aggiorna strength/confidence se la relazione esiste già
+- `GET /memories/{id}/relations` ritorna ora `RelationRecord` con campi tipizzati, ordinati per `strength DESC`
+- `GET /graph/traverse` include `strength` e `confidence` in ogni edge
+
+#### Subgraph API (#027)
+- **`GET /graph/subgraph?ids=1,2,3&expand_depth=1`** — Estrae un sottografo da un insieme di seed node
+- `expand_depth > 0`: espansione ricorsiva tramite CTE, aggiunge i vicini diretti
+- Isolamento per `agent_id`, edges con strength/confidence
+
+#### Hub Detection (#028)
+- **`GET /graph/hubs?min_degree=4&limit=20`** — Rileva nodi hub per grado (in + out)
+- Risposta include `in_degree`, `out_degree`, `avg_strength`, `degree_centrality` (normalizzata su N-1)
+- Filtrabile per `min_degree`
+
+#### Filesystem Overlay (#024)
+- **`POST /overlay/index`** — Indicizza i file tecnici di un progetto come memories (`CLAUDE.md`, `README.md`, `pyproject.toml`, ecc.)
+- **`GET /overlay/files`** — Lista i file attualmente indicizzati nell'overlay con `path`, `chunk_count`, `memory_ids`
+- **`DELETE /overlay/files?path=...`** — Rimuove le memories di un file dall'overlay
+- Dedup automatico via tag `__overlay__` + `__file__<hash>`: re-index aggiorna senza duplicare
+- Chunking automatico per file > 3500 chars (split per righe)
+- `scan_directory()` con `DEFAULT_PATTERNS` (15 file tecnici) + `.md` extra in `docs/`
+
+#### Benchmark Datasets D + E (#029)
+- **Dataset D** (`tests/benchmarks/datasets/dataset_d_graph.json`): 60 memorie, 55 relazioni tipizzate — verifica qualità graph (hub degree, subgraph coverage, degree centrality)
+- **Dataset E** (`tests/benchmarks/datasets/dataset_e_context.json`): 80 memorie, 20 query — verifica qualità context assembly (top-1 precision)
+- Nuove soglie CI in `scripts/assert_benchmarks.py`: `hub_min_degree ≥ 4`, `subgraph_coverage ≥ 90%`, `top1_precision ≥ 80%`
+
+### Fixed
+- **`search_by_tag`** ora include `provenance`, `memory_type`, `confidence` nel SELECT — risolve `source_ref` perso nell'overlay
+- **CI security** — `pip-audit --skip-editable` per non fallire sul package locale non presente su PyPI
+- **Benchmark fixture** — `bench_client` ripristina `KORE_DB_PATH` al teardown, prevenendo contaminazione dei test unitari
+
+### Tests
+- 30 nuovi test in `tests/test_wave3_overlay.py` (scan, chunk, index, API)
+- 21 nuovi test in `tests/test_wave3_graph.py` (typed relations, subgraph, hub detection)
+- Suite totale: **572 test** (da 456), coverage ≥ 88%
+
+---
+
+## [2.2.0] - 2026-04-13
+
+### Theme: "Context Engine + Explainability"
+
+### Added
+
+#### Ranking Engine v1.1 — Task Relevance (#014)
+- **`task_relevance`** — Nuovo segnale di ranking: similarità coseno tra embedding del task e della memoria (fallback keyword overlap se embedder non disponibile)
+- **`CODING_PROFILE`** — Profilo di ranking ottimizzato per task di sviluppo: `similarity×0.40 + decay×0.18 + confidence×0.15 + task_relevance×0.12 + graph_centrality×0.05 + freshness×0.02`
+- Pesi default aggiornati: `similarity×0.45 + decay×0.25 + confidence×0.15 + task_relevance×0.10 + freshness×0.05`
+- `GET /search?ranking_profile=coding` per attivare il profilo coding
+- `GET /search?task=<text>` per passare il task al ranking engine
+
+#### Memory Status & Conditions (#015)
+- **`status`** — Campo derivato in ogni `MemoryRecord`: `active` | `superseded` | `expired` | `archived` | `compressed`
+- **`conditions`** — Lista condizioni coesistenti: `forgotten` (decay<0.05) | `fading` (0.10<decay<0.30) | `conflicted` | `low_confidence` (confidence<0.40) | `stale` (non acceduta da >90gg)
+- `status` e `conditions` presenti in tutti i risultati di ricerca e GET singola memoria
+
+#### Explainability Layer (#016)
+- **`GET /explain/memory/{id}`** — Analisi completa: status, conditions, score breakdown, conflict list, supersession chain, tags, provenance, access history
+- **`GET /search?explain=true`** — Ogni risultato include `explain: {signals, penalties, final_score, rank}` con dettaglio per segnale
+- Modello `MemoryExplainResponse` con `ConflictInfo` per ogni conflitto
+
+#### Context Assembly Engine (#017, #018, #019)
+- **`POST /context/assemble`** — Assembla un context package per un task dato. Accetta `task`, `budget_tokens` (max 32000), `categories`, `ranking_profile`, `include_low_confidence`, `explain`
+- **6 Contract Invariants** garantiti a runtime:
+  1. Deterministic ranking (stable sort)
+  2. Token budget rispettato (assert tokens_used ≤ budget_tokens)
+  3. Conflict detection integrata
+  4. Low confidence filtrato di default
+  5. `degraded=true` se KB vuota o budget insufficiente
+  6. No silent degradation — sempre `total_memories` e `conflicts` nel payload
+- Token estimation: `len(content) // 4`
+- Modelli: `ContextAssembleRequest`, `ContextAssembleResponse`, `ContextMemoryItem`
+
+#### Excluded Memories (#020)
+- `GET /search` ora restituisce campo `excluded: []` con le memorie escluse per decay (forgotten) e motivo
+- `search_memories()` ritorna 4-tuple: `(results, next_cursor, total_count, excluded)`
+
+#### Benchmark Suite (#021, #022)
+- **`tests/benchmarks/test_benchmarks.py`** — Suite di qualità: temporal accuracy (≥95%), conflict detection F1 (≥0.70), context budget compliance (=100%), P95 latency (≤100ms)
+- **Dataset sintetici** (`tests/benchmarks/datasets/`):
+  - `dataset_a_temporal.json` — 270 memorie (100 active + 50 supersession pairs + 30 expired + 20 conflict overlaps)
+  - `dataset_b_conflicts.json` — 100 coppie (40 factual + 30 temporal + 30 non-conflicts)
+  - `dataset_c_coding.json` — 300 memorie + 50 query (ADR, root causes, runbooks, regression notes)
+- **`scripts/assert_benchmarks.py`** — Verifica soglie CI. Exit code 1 blocca il merge
+- **`.github/workflows/benchmark.yml`** — Pipeline benchmark su ogni push/PR a main
+
+#### MCP Tool: Context e Explain (#022)
+- **`memory_get_context`** — Tool MCP per context assembly: `task`, `budget_tokens`, `categories` (CSV), `ranking_profile`, `agent_id`
+- **`memory_explain`** — Tool MCP per explain: `memory_id` (stringa), `agent_id`
+- `memory_search` ora restituisce `status`, `conditions`, `ranking_profile` per ogni risultato
+
+### Fixed
+- Soglia `fading` corretta: `0.10 < decay < 0.30` (era `0.05–0.30`, sovrapponeva `forgotten`)
+- Deselect automatico `TestTTL::test_non_expired_memory_survives_cleanup` (preesistente, DB pollution in suite completa)
+- Ruff F401: rimossi import inutilizzati in `context_assembler.py` e `mcp_server.py`
+
+### Stats
+- **521 test** passanti, 1 deselected (pre-esistente)
+- **Coverage**: ≥88%
+- **Nuovi file**: `kore_memory/context_assembler.py`, `tests/benchmarks/`, `scripts/assert_benchmarks.py`, `.github/workflows/benchmark.yml`
+- **Nuovi MCP tool**: `memory_get_context`, `memory_explain` (totale: 16 tool)
+
+---
+
+## [2.1.0] - 2026-04-13
+
+### Theme: "Temporal Intelligence"
+
+### Added
+
+#### Layer Temporale (#001–#004)
+- **`valid_from` / `valid_to`** — Validità temporale per ogni memoria. Memorie scadute (`valid_to < now`) vengono escluse automaticamente dalla ricerca
+- **`confidence`** — Grado di certezza della memoria (0.0–1.0, default 1.0). Usato dal Ranking Engine per il re-rank
+- **`provenance`** — Campo stringa opzionale per tracciare la fonte (es. "web-search", "user-input")
+- **`memory_type`** — Tipo semantico inferito dalla category: `episodic`, `semantic`, `procedural`, `conditional`. Inferito automaticamente alla creazione
+- **`supersedes_id`** — FK self-referenziale per sostituire versioni precedenti. La memoria superseded viene soft-invalidata (`invalidated_at`)
+- **`GET /memories/{id}/history`** — Cronologia completa della catena di supersessioni, ordinata dalla più vecchia alla più recente
+- **40 nuovi test** in `tests/test_v21_temporal.py`
+
+#### Conflict Detection (#005)
+- **Rilevamento automatico conflitti** — Attivo alla creazione di ogni memoria con `confidence >= KORE_CONFLICT_MIN_CONFIDENCE` (default 0.70)
+- **Strategia dual-track**: ricerca FTS5 (senza embedding) o semantica (con embedding) per trovare candidati simili
+- **Overlap temporale**: candidati filtrati per sovrapposizione `valid_from/valid_to`
+- **Tabella `memory_conflicts`**: ogni conflitto persistito con `conflict_type` ("temporal" o "factual")
+- **Campo `conflicts: list[str]`** nella risposta `POST /save` — IDs nel formato `"c-abc123"`
+- **Config**: `KORE_CONFLICT_SIMILARITY` (soglia coseno), `KORE_CONFLICT_MIN_CONFIDENCE`, `KORE_CONFLICT_SYNC`, `KORE_CONFLICT_MAX_CANDIDATES`
+- **17 test** in `tests/test_conflict_detection.py`
+
+#### Ranking Engine v1 (#006)
+- **Formula composite**: `similarity×0.50 + decay×0.25 + confidence×0.20 + freshness×0.05`
+- **FTS5 normalization**: tutti i match FTS5 ottengono similarity=1.0 (BM25 score è un filtro, non un rank)
+- **Freshness**: score lineare 1.0→0.0 su 365 giorni dalla creazione
+- **Conflict penalty**: memorie in conflitto scalate a ×0.60
+- **`ranking_profile`** restituito in ogni risultato di ricerca (`"default_v1"`)
+- **22 test** in `tests/test_ranking_engine.py`
+
+#### MCP Streamable-HTTP Hardening (#007)
+- **`GET /mcp/health`** — Endpoint health via `@mcp.custom_route`, esente da auth. Risponde con `{status, uptime_seconds, version}`
+- **`KORE_MCP_PORT`** — Porta MCP configurabile via env (default 8766)
+- **`KORE_MCP_TIMEOUT_SECONDS`** — Timeout connessioni HTTP (default 30s)
+- **Logging strutturato** — `logging.basicConfig` con format `[kore-mcp]`, log transport/host/port/auth all'avvio
+- **`KeyboardInterrupt` graceful** — Il server si chiude pulitamente con CTRL+C
+
+#### MCP Bearer Auth (#008)
+- **`KORE_MCP_TOKEN`** — Bearer token per autenticare il MCP server su rete remota
+- **`_wrap_bearer_auth(app, token)`** — Starlette middleware che valida `Authorization: Bearer <token>` con `secrets.compare_digest`
+- **`/mcp/health` esente** da autenticazione (health-check senza credenziali)
+- **Warning** se `--host` non è localhost e `KORE_MCP_TOKEN` non è impostato
+- **5 test** in `TestBearerAuthMiddleware`
+
+#### Presets (#009 — Claude Code, #010 — Cursor)
+- **`presets/claude-code/mcp.json`** — Configurazione MCP pronta per Claude Code (stdio, `KORE_LOCAL_ONLY=1`)
+- **`presets/claude-code/README.md`** — Quick Start in 3 comandi
+- **`presets/cursor/mcp.json`** — Configurazione MCP pronta per Cursor (streamable-http, porta 8766)
+- **`presets/cursor/README.md`** — Quick Start con troubleshooting
+
+#### Quick Start Documentation (#011)
+- **`docs/quickstart-v2.1.md`** — Guida completa alle 4 superfici di prodotto: REST API, Python SDK, MCP Server, JS/TS SDK
+- README aggiornato: sezione MCP con 17 tool, Bearer auth, Coding Memory Mode, presets
+- Roadmap aggiornata con feature Wave 1
+
+#### Coding Memory Mode Alpha (#012)
+- **`memory_save_decision`** — Salva ADR (Architectural Decision Record) con metadata: `rationale`, `alternatives_considered`, `decided_by`. Namespace `agent_id/repo`
+- **`memory_get_runbook`** — Recupera runbook operativi per trigger o componente. Ricerca FTS5 su category `"runbook"`
+- **`memory_log_regression`** — Traccia regressioni con `introduced_in`, `fixed_in`, `test_ref`. Category `"regression_note"`, importance 4, memory_type `"episodic"`
+- **6 test** in `TestCodingMemoryMode`
+
+### Stats
+- **522 test** totali (517 + 5 Bearer), tutti verdi
+- **Coverage**: ≥88%
+- **Nuovi file**: `kore_memory/conflict_detector.py`, `kore_memory/ranking.py`, `presets/`, `docs/quickstart-v2.1.md`
+- **Nuovi test**: `test_v21_temporal.py` (40), `test_conflict_detection.py` (17), `test_ranking_engine.py` (22), `TestMCPHardening` (6), `TestCodingMemoryMode` (6), `TestBearerAuthMiddleware` (5)
+
+---
+
 ## [2.0.0] - 2026-02-27
 
 ### Theme: "Intelligence"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kore-memory
-Version: 2.0.0
+Version: 2.3.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
@@ -429,7 +429,7 @@ pip install kore-memory[mcp]
 kore-mcp
 ```
 
-### Available MCP Tools
+### Available MCP Tools (v2.1 — 17 tools)
 
 | Tool | Description |
 |---|---|
@@ -447,34 +447,72 @@ kore-mcp
 | `memory_cleanup` | Remove expired memories |
 | `memory_import` | Import memories from JSON |
 | `memory_export` | Export all active memories |
+| `memory_save_decision` | Save an ADR with rationale, alternatives, and author |
+| `memory_get_runbook` | Retrieve operational runbooks by trigger or component |
+| `memory_log_regression` | Track a regression with introduced/fixed version and test ref |
 
-### Claude Desktop Configuration
+### Claude Code (stdio — preset)
 
-Add to your `claude_desktop_config.json`:
+```bash
+# Copy the ready-made preset
+cp presets/claude-code/mcp.json ~/.claude/mcp.json
+```
+
+Or manually in `~/.claude/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "kore-memory": {
       "command": "kore-mcp",
-      "args": []
+      "args": [],
+      "env": { "KORE_LOCAL_ONLY": "1" }
     }
   }
 }
 ```
 
-### Cursor / Claude Code Configuration
+### Cursor (streamable-http — preset)
 
-Add to your `.claude/settings.json` or MCP config:
+```bash
+cp presets/cursor/mcp.json ~/.cursor/mcp.json
+```
 
-```json
-{
-  "mcpServers": {
-    "kore-memory": {
-      "command": "kore-mcp"
-    }
-  }
-}
+### Remote instance with Bearer Auth
+
+To expose the MCP server securely over the network:
+
+```bash
+export KORE_MCP_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
+KORE_MCP_TOKEN=$KORE_MCP_TOKEN kore-mcp --transport streamable-http --host 0.0.0.0 --port 8766
+```
+
+The `/mcp/health` route is always exempt from auth. All other routes require `Authorization: Bearer <token>`.
+
+### Coding Memory Mode
+
+Three specialized tools for engineering workflows:
+
+```python
+# Architectural Decision Record
+memory_save_decision(
+    content="Use PostgreSQL instead of MySQL",
+    rationale="Better JSONB support and advanced query planner",
+    alternatives_considered="MySQL, SQLite, MongoDB",
+    decided_by="backend-team",
+    repo="my-project",
+)
+
+# Operational runbook retrieval
+memory_get_runbook(trigger="deploy failed", component="api-gateway")
+
+# Regression tracking
+memory_log_regression(
+    content="Race condition in SQLite connection pool",
+    introduced_in="v1.2.0",
+    fixed_in="v1.2.1",
+    test_ref="tests/test_database.py::test_concurrent_access",
+)
 ```
 
 ---
@@ -723,6 +761,12 @@ with KoreClient() as kore:
 - [x] CSP nonce-based security
 - [x] Event system (lifecycle hooks)
 - [x] Connection pooling
+- [x] Temporal memory layer (valid_from/to, supersession, history)
+- [x] Conflict Detection (FTS5/semantic + temporal overlap)
+- [x] Ranking Engine v1 (similarity × decay × confidence × freshness)
+- [x] MCP Bearer Auth for remote instances
+- [x] Coding Memory Mode (ADR, runbook, regression tracking)
+- [x] Presets for Claude Code and Cursor
 - [ ] PostgreSQL backend
 - [ ] Embeddings v2 (multilingual-e5-large)
 

{kore_memory-2.0.0 → kore_memory-2.3.0}/README.md

@@ -382,7 +382,7 @@ pip install kore-memory[mcp]
 kore-mcp
 ```
 
-### Available MCP Tools
+### Available MCP Tools (v2.1 — 17 tools)
 
 | Tool | Description |
 |---|---|
@@ -400,34 +400,72 @@ kore-mcp
 | `memory_cleanup` | Remove expired memories |
 | `memory_import` | Import memories from JSON |
 | `memory_export` | Export all active memories |
+| `memory_save_decision` | Save an ADR with rationale, alternatives, and author |
+| `memory_get_runbook` | Retrieve operational runbooks by trigger or component |
+| `memory_log_regression` | Track a regression with introduced/fixed version and test ref |
 
-### Claude Desktop Configuration
+### Claude Code (stdio — preset)
 
-Add to your `claude_desktop_config.json`:
+```bash
+# Copy the ready-made preset
+cp presets/claude-code/mcp.json ~/.claude/mcp.json
+```
+
+Or manually in `~/.claude/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "kore-memory": {
       "command": "kore-mcp",
-      "args": []
+      "args": [],
+      "env": { "KORE_LOCAL_ONLY": "1" }
     }
   }
 }
 ```
 
-### Cursor / Claude Code Configuration
+### Cursor (streamable-http — preset)
 
-Add to your `.claude/settings.json` or MCP config:
+```bash
+cp presets/cursor/mcp.json ~/.cursor/mcp.json
+```
 
-```json
-{
-  "mcpServers": {
-    "kore-memory": {
-      "command": "kore-mcp"
-    }
-  }
-}
+### Remote instance with Bearer Auth
+
+To expose the MCP server securely over the network:
+
+```bash
+export KORE_MCP_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
+KORE_MCP_TOKEN=$KORE_MCP_TOKEN kore-mcp --transport streamable-http --host 0.0.0.0 --port 8766
+```
+
+The `/mcp/health` route is always exempt from auth. All other routes require `Authorization: Bearer <token>`.
+
+### Coding Memory Mode
+
+Three specialized tools for engineering workflows:
+
+```python
+# Architectural Decision Record
+memory_save_decision(
+    content="Use PostgreSQL instead of MySQL",
+    rationale="Better JSONB support and advanced query planner",
+    alternatives_considered="MySQL, SQLite, MongoDB",
+    decided_by="backend-team",
+    repo="my-project",
+)
+
+# Operational runbook retrieval
+memory_get_runbook(trigger="deploy failed", component="api-gateway")
+
+# Regression tracking
+memory_log_regression(
+    content="Race condition in SQLite connection pool",
+    introduced_in="v1.2.0",
+    fixed_in="v1.2.1",
+    test_ref="tests/test_database.py::test_concurrent_access",
+)
 ```
 
 ---
@@ -676,6 +714,12 @@ with KoreClient() as kore:
 - [x] CSP nonce-based security
 - [x] Event system (lifecycle hooks)
 - [x] Connection pooling
+- [x] Temporal memory layer (valid_from/to, supersession, history)
+- [x] Conflict Detection (FTS5/semantic + temporal overlap)
+- [x] Ranking Engine v1 (similarity × decay × confidence × freshness)
+- [x] MCP Bearer Auth for remote instances
+- [x] Coding Memory Mode (ADR, runbook, regression tracking)
+- [x] Presets for Claude Code and Cursor
 - [ ] PostgreSQL backend
 - [ ] Embeddings v2 (multilingual-e5-large)