kore-memory 0.2.0__py3-none-any.whl

kore_memory-0.2.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: kore-memory
+Version: 0.2.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/juanauriti/kore-memory
+Project-URL: Repository, https://github.com/juanauriti/kore-memory
+Project-URL: Issues, https://github.com/juanauriti/kore-memory/issues
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,embeddings,llm,memory,rag,semantic-search
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=3.0.0; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# Kore Memory
+
+> **The memory layer that thinks like a human: remembers what matters, forgets what doesn't, and never calls home.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
+[![Zero Cloud Dependencies](https://img.shields.io/badge/cloud-zero-green.svg)]()
+
+---
+
+## Why Kore?
+
+Every AI agent memory tool out there has the same problem: they remember everything forever, require cloud APIs, or need an LLM just to decide what's worth storing.
+
+**Kore is different.**
+
+| Feature | Kore | Mem0 | Letta | Memori |
+|---|---|---|---|---|
+| Runs fully offline | ✅ | ❌ | ❌ | ❌ |
+| No LLM required | ✅ | ❌ | ❌ | ✅ |
+| Memory Decay (Ebbinghaus) | ✅ | ❌ | ❌ | ❌ |
+| Auto-importance scoring | ✅ local | ✅ via LLM | ❌ | ❌ |
+| Memory Compression | ✅ | ❌ | ❌ | ❌ |
+| Semantic search (50+ langs) | ✅ local | ✅ via API | ✅ | ✅ |
+| Timeline API | ✅ | ❌ | ❌ | ❌ |
+| Access reinforcement | ✅ | ❌ | ❌ | ❌ |
+| Install in 2 minutes | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## How It Works
+
+Kore models memory the way the human brain does:
+
+1. **Save** — store a memory with optional category and importance
+2. **Auto-score** — Kore calculates importance locally using content analysis (no API calls)
+3. **Decay** — memories fade over time using the [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve)
+4. **Reinforce** — retrieving a memory resets its clock and boosts its score
+5. **Compress** — similar memories are automatically merged to keep the DB lean
+6. **Search** — semantic search in any language, filtered by relevance and freshness
+
+---
+
+## Quickstart
+
+```bash
+pip install kore-memory
+pip install kore-memory[semantic]   # + multilingual embeddings (50+ languages)
+
+kore                                # starts server on http://localhost:8765
+```
+
+### Save a memory
+
+```bash
+curl -X POST http://localhost:8765/save \
+  -H "Content-Type: application/json" \
+  -d '{"content": "User prefers concise responses", "category": "preference"}'
+# → {"id": 1, "importance": 4, "message": "Memory saved"}
+# importance was auto-scored: "preference" category + keyword "prefers" → 4
+```
+
+### Search (any language)
+
+```bash
+# English query finds Italian content, French content, etc.
+curl "http://localhost:8765/search?q=user+preferences&limit=5"
+```
+
+### Run decay pass (call daily via cron)
+
+```bash
+curl -X POST http://localhost:8765/decay/run
+# → {"updated": 42, "message": "Decay pass complete"}
+```
+
+### Compress similar memories
+
+```bash
+curl -X POST http://localhost:8765/compress
+# → {"clusters_found": 3, "memories_merged": 7, "new_records_created": 3}
+```
+
+### Timeline: what did I know about X over time?
+
+```bash
+curl "http://localhost:8765/timeline?subject=project+alpha"
+```
+
+---
+
+## Memory Decay
+
+Kore uses the **Ebbinghaus forgetting curve** to assign each memory a `decay_score` between 0.0 and 1.0:
+
+```
+decay = e^(-t * ln(2) / half_life)
+```
+
+Where:
+- `t` = days since last access
+- `half_life` = base days before 50% decay, adjusted by importance level
+
+| Importance | Half-life | Meaning |
+|---|---|---|
+| 1 (low) | 7 days | Casual notes |
+| 2 (normal) | 14 days | General context |
+| 3 (important) | 30 days | Project info |
+| 4 (high) | 90 days | Critical decisions |
+| 5 (critical) | 365 days | Passwords, rules, never forget |
+
+Every time a memory is retrieved, its `access_count` increases and its half-life is extended by 15% — just like spaced repetition in human learning.
+
+---
+
+## Auto-Importance Scoring
+
+When you save a memory without an explicit importance level, Kore scores it automatically:
+
+- **Category baseline** — `preference` starts at 4, `finance` at 3, `general` at 1
+- **Keyword signals** — words like `password`, `token`, `urgente` → importance 5
+- **Content length** — detailed content gets a small boost
+
+Zero LLM calls. Zero API costs.
+
+---
+
+## API Reference
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/save` | Save a memory |
+| `GET` | `/search` | Semantic search (any language) |
+| `GET` | `/timeline` | Chronological history for a subject |
+| `DELETE` | `/memories/{id}` | Delete a memory |
+| `POST` | `/decay/run` | Update all decay scores |
+| `POST` | `/compress` | Merge similar memories |
+| `GET` | `/health` | Health check + capabilities |
+
+Full interactive docs: `http://localhost:8765/docs`
+
+---
+
+## Categories
+
+`general` · `project` · `trading` · `finance` · `person` · `preference` · `task` · `decision`
+
+---
+
+## Requirements
+
+- Python 3.11+
+- SQLite (built into Python)
+- Optional: `sentence-transformers` for semantic search
+
+No PostgreSQL. No Redis. No Docker. No API keys.
+
+---
+
+## License
+
+MIT — use it, fork it, build on it.
+
+---
+
+*Built with ❤️ for AI agents that deserve better memory.*

kore_memory-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+src/__init__.py,sha256=fiq5GIGazcLLUkNGCDmG05r1ELglKiOWFDXdB0n39wY,15
+src/auth.py,sha256=yLTOrBtY3lfqX7PWfk0btUlQcU54-9mu_HEIK9ThWxM,3513
+src/cli.py,sha256=1JPGeKRPTIvadhb377RQggstQjKgdYDkM5WmoSRw_lk,1046
+src/compressor.py,sha256=PxxBaup2UWtCHeQiaM3NcAiwu1AXyhku2CImmXXrxo8,4328
+src/database.py,sha256=mVg19jUXNOhFx9lET-TEQHtA2qiHwmD8kn0wel2h70w,3525
+src/decay.py,sha256=AwYnekog7u21QNjLr9xs-lb0-vC4obTedkfYwLp0yRc,2416
+src/embedder.py,sha256=dt9KKEd6ekuHSVoMMKfDgVPV15xW3SQ42p_IkHe6nQs,1425
+src/main.py,sha256=G8QBudnKrfqZmnBZBXu9mSrv2EfshIvgxEjphG6L_Jo,4552
+src/models.py,sha256=ye-l-b0blVsTHmXcx4ZqSk-tbLVwFZj35gG94WeJY0w,1430
+src/repository.py,sha256=jFr2D9lds_m5n1yQCmJYw7Q4bSU79movK2q1D9s7lfM,9410
+src/scorer.py,sha256=d8pOOLIQXpGDWlJ9iGqmVc5mBGuwKTBScOkeZiOlxiw,2271
+kore_memory-0.2.0.dist-info/METADATA,sha256=GBIRu20KTAaQqyOjHiQOsG2GZ4a2SOgupcbttgEp9Kw,6187
+kore_memory-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kore_memory-0.2.0.dist-info/entry_points.txt,sha256=sSks4ncnR0ur7xTqYrkhehtXy1K70wK-b2gVBYpAkhQ,39
+kore_memory-0.2.0.dist-info/licenses/LICENSE,sha256=UJe81-OhbzRibujLXWpETnCKbGvlZsjbhJ6zuwjz8F8,1068
+kore_memory-0.2.0.dist-info/RECORD,,

kore_memory-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kore_memory-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kore = kore.cli:main

kore_memory-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Auriti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/__init__.py

@@ -0,0 +1 @@
+# Kore package

src/auth.py

@@ -0,0 +1,107 @@
+"""
+Kore — Authentication & Authorization
+API key validation + agent namespace isolation.
+
+Config via environment variables:
+  KORE_API_KEY   — master key (required in non-local mode)
+  KORE_LOCAL_ONLY — if "1", skip auth for 127.0.0.1 requests (default: "1")
+"""
+
+import os
+import secrets
+from pathlib import Path
+
+from fastapi import Header, HTTPException, Request, status
+
+_KEY_FILE = Path(__file__).parent.parent / "data" / ".api_key"
+
+# ── Key management ────────────────────────────────────────────────────────────
+
+def get_or_create_api_key() -> str:
+    """
+    Load API key from env or file. Generate and persist one if missing.
+    Priority: KORE_API_KEY env → data/.api_key file → auto-generate
+    """
+    env_key = os.getenv("KORE_API_KEY")
+    if env_key:
+        return env_key
+
+    if _KEY_FILE.exists():
+        return _KEY_FILE.read_text().strip()
+
+    # Auto-generate a secure key on first run
+    new_key = secrets.token_urlsafe(32)
+    _KEY_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _KEY_FILE.write_text(new_key)
+    _KEY_FILE.chmod(0o600)  # owner read/write only
+    print(f"\n🔑 Kore API key generated: {new_key}")
+    print(f"   Saved to: {_KEY_FILE}")
+    print(f"   Set KORE_API_KEY env var or use X-Kore-Key header.\n")
+    return new_key
+
+
+_API_KEY: str | None = None
+
+
+def _loaded_key() -> str:
+    global _API_KEY
+    if _API_KEY is None:
+        _API_KEY = get_or_create_api_key()
+    return _API_KEY
+
+
+def _is_local(request: Request) -> bool:
+    client_host = request.client.host if request.client else ""
+    # "testclient" is the FastAPI TestClient host — treat as local in tests
+    return client_host in ("127.0.0.1", "::1", "localhost", "testclient")
+
+
+def _local_only_mode() -> bool:
+    return os.getenv("KORE_LOCAL_ONLY", "1") == "1"
+
+
+# ── FastAPI dependency ────────────────────────────────────────────────────────
+
+async def require_auth(
+    request: Request,
+    x_kore_key: str | None = Header(default=None, alias="X-Kore-Key"),
+) -> str:
+    """
+    FastAPI dependency: validates API key.
+    In local-only mode, skips auth for 127.0.0.1 requests.
+    Returns the validated API key (or 'local' for unauthenticated local requests).
+    """
+    if _local_only_mode() and _is_local(request):
+        return "local"
+
+    if not x_kore_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing API key. Pass X-Kore-Key header.",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+    if not secrets.compare_digest(x_kore_key, _loaded_key()):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid API key.",
+        )
+
+    return x_kore_key
+
+
+async def get_agent_id(
+    request: Request,
+    x_agent_id: str | None = Header(default=None, alias="X-Agent-Id"),
+) -> str:
+    """
+    FastAPI dependency: extracts agent namespace.
+    Defaults to 'default' when not provided.
+    Agent IDs are sanitized to alphanumeric + dash/underscore only.
+    """
+    agent_id = (x_agent_id or "default").strip()
+    # Sanitize: only allow safe chars
+    safe = "".join(c for c in agent_id if c.isalnum() or c in "-_")
+    if not safe:
+        safe = "default"
+    return safe[:64]  # max 64 chars

src/cli.py

@@ -0,0 +1,37 @@
+"""
+Kore — CLI entry point
+Usage: kore [--host HOST] [--port PORT] [--reload]
+"""
+
+import argparse
+import sys
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="kore",
+        description="Kore memory server — start the API.",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8765, help="Bind port (default: 8765)")
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload (dev mode)")
+    parser.add_argument("--log-level", default="warning", choices=["debug", "info", "warning", "error"])
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError:
+        print("Error: uvicorn not found. Run: pip install kore-memory", file=sys.stderr)
+        sys.exit(1)
+
+    uvicorn.run(
+        "kore.src.main:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level=args.log_level,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/compressor.py

@@ -0,0 +1,146 @@
+"""
+Kore — Memory Compressor
+Finds clusters of similar memories and merges them into a single richer record.
+
+Strategy:
+  1. Load all memories without a compressed_into reference
+  2. For each pair, compute cosine similarity
+  3. Cluster memories with similarity > threshold
+  4. Merge each cluster into one record (union of content, max importance)
+  5. Mark originals as compressed_into the new record
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .database import get_connection
+from .embedder import cosine_similarity, deserialize, embed, serialize
+from .models import MemorySaveRequest
+from .repository import save_memory
+
+SIMILARITY_THRESHOLD = 0.88  # memories above this are considered duplicates
+
+
+@dataclass
+class CompressionResult:
+    clusters_found: int
+    memories_merged: int
+    new_records_created: int
+
+
+def run_compression(agent_id: str = "default") -> CompressionResult:
+    """
+    Full compression pass: find similar memories, merge clusters.
+    Returns a summary of what was done.
+    """
+    memories = _load_compressible_memories(agent_id)
+    if len(memories) < 2:
+        return CompressionResult(0, 0, 0)
+
+    clusters = _find_clusters(memories)
+    if not clusters:
+        return CompressionResult(0, 0, 0)
+
+    merged = 0
+    created = 0
+    for cluster in clusters:
+        new_id = _merge_cluster(cluster, agent_id=agent_id)
+        if new_id:
+            merged += len(cluster)
+            created += 1
+
+    return CompressionResult(
+        clusters_found=len(clusters),
+        memories_merged=merged,
+        new_records_created=created,
+    )
+
+
+def _load_compressible_memories(agent_id: str = "default") -> list[dict]:
+    with get_connection() as conn:
+        rows = conn.execute(
+            """
+            SELECT id, content, category, importance, embedding
+            FROM memories
+            WHERE compressed_into IS NULL AND embedding IS NOT NULL AND agent_id = ?
+            """,
+            (agent_id,),
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _find_clusters(memories: list[dict]) -> list[list[dict]]:
+    """
+    Greedy clustering: group memories where any pair exceeds threshold.
+    Each memory belongs to at most one cluster.
+    """
+    used = set()
+    clusters = []
+
+    for i, mem_a in enumerate(memories):
+        if mem_a["id"] in used:
+            continue
+
+        vec_a = deserialize(mem_a["embedding"])
+        cluster = [mem_a]
+
+        for j, mem_b in enumerate(memories):
+            if i == j or mem_b["id"] in used:
+                continue
+            vec_b = deserialize(mem_b["embedding"])
+            if cosine_similarity(vec_a, vec_b) >= SIMILARITY_THRESHOLD:
+                cluster.append(mem_b)
+
+        if len(cluster) > 1:
+            for m in cluster:
+                used.add(m["id"])
+            clusters.append(cluster)
+
+    return clusters
+
+
+def _merge_cluster(cluster: list[dict], agent_id: str = "default") -> int | None:
+    """
+    Merge a cluster of memories into a single new record.
+    Returns the id of the new merged record, or None on failure.
+    """
+    if not cluster:
+        return None
+
+    # Build merged content: combine unique sentences
+    combined_parts = []
+    seen = set()
+    for mem in cluster:
+        for sentence in mem["content"].split("|"):
+            s = sentence.strip()
+            if s and s not in seen:
+                seen.add(s)
+                combined_parts.append(s)
+
+    merged_content = " | ".join(combined_parts)
+    if len(merged_content) > 4000:
+        merged_content = merged_content[:3997] + "..."
+
+    # Use the most common category and highest importance
+    categories = [m["category"] for m in cluster]
+    merged_category = max(set(categories), key=categories.count)
+    merged_importance = max(m["importance"] for m in cluster)
+
+    # Save the new merged record
+    req = MemorySaveRequest(
+        content=merged_content,
+        category=merged_category,
+        importance=merged_importance,
+    )
+    new_id = save_memory(req, agent_id=agent_id)
+
+    # Mark originals as compressed
+    ids = [m["id"] for m in cluster]
+    with get_connection() as conn:
+        conn.executemany(
+            "UPDATE memories SET compressed_into = ? WHERE id = ?",
+            [(new_id, mid) for mid in ids],
+        )
+
+    return new_id

src/database.py

@@ -0,0 +1,84 @@
+"""
+Kore - Database layer
+Handles SQLite connection and schema initialization.
+"""
+
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+
+DB_PATH = Path(__file__).parent.parent / "data" / "memory.db"
+
+
+def init_db() -> None:
+    """Initialize the database and create tables if they don't exist."""
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    # Ensure DB file exists before chmod
+    DB_PATH.touch(exist_ok=True)
+    DB_PATH.chmod(0o600)  # owner only — protects memory data
+
+    with get_connection() as conn:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                agent_id        TEXT    NOT NULL DEFAULT 'default',
+                content         TEXT    NOT NULL,
+                category        TEXT    NOT NULL DEFAULT 'general',
+                importance      INTEGER NOT NULL DEFAULT 1 CHECK (importance BETWEEN 1 AND 5),
+                decay_score     REAL    NOT NULL DEFAULT 1.0,
+                access_count    INTEGER NOT NULL DEFAULT 0,
+                last_accessed   TEXT    DEFAULT NULL,
+                compressed_into INTEGER DEFAULT NULL REFERENCES memories(id),
+                embedding       TEXT    DEFAULT NULL,
+                created_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+                updated_at      TEXT    NOT NULL DEFAULT (datetime('now'))
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_memories_agent      ON memories (agent_id);
+            CREATE INDEX IF NOT EXISTS idx_memories_decay      ON memories (decay_score DESC);
+            CREATE INDEX IF NOT EXISTS idx_memories_compressed ON memories (compressed_into);
+
+            CREATE INDEX IF NOT EXISTS idx_memories_category  ON memories (category);
+            CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories (importance DESC);
+            CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories (created_at DESC);
+
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+            USING fts5(content, category, content='memories', content_rowid='id', tokenize='unicode61');
+
+            CREATE TRIGGER IF NOT EXISTS memories_ai
+            AFTER INSERT ON memories BEGIN
+                INSERT INTO memories_fts (rowid, content, category)
+                VALUES (new.id, new.content, new.category);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_ad
+            AFTER DELETE ON memories BEGIN
+                INSERT INTO memories_fts (memories_fts, rowid, content, category)
+                VALUES ('delete', old.id, old.content, old.category);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_au
+            AFTER UPDATE ON memories BEGIN
+                INSERT INTO memories_fts (memories_fts, rowid, content, category)
+                VALUES ('delete', old.id, old.content, old.category);
+                INSERT INTO memories_fts (rowid, content, category)
+                VALUES (new.id, new.content, new.category);
+            END;
+        """)
+
+
+@contextmanager
+def get_connection():
+    """Yield a thread-safe SQLite connection with WAL mode enabled."""
+    conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    try:
+        yield conn
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()

src/decay.py

@@ -0,0 +1,69 @@
+"""
+Kore — Memory Decay Engine
+Implements human-like forgetting: memories fade over time unless reinforced.
+
+Formula inspired by Ebbinghaus forgetting curve:
+  decay = importance_factor * e^(-t / half_life)
+
+Where:
+  t              = days since last access
+  half_life      = base days before 50% decay (modulated by importance)
+  importance_fac = 1.0 to 2.0 (higher importance = slower decay)
+  access_count   = each retrieval resets the clock and boosts score
+"""
+
+import math
+from datetime import datetime, timezone
+
+# Half-life in days per importance level (higher importance = longer half-life)
+HALF_LIFE: dict[int, float] = {
+    1: 7.0,    # low — fades in ~1 week
+    2: 14.0,   # normal — fades in ~2 weeks
+    3: 30.0,   # important — fades in ~1 month
+    4: 90.0,   # very important — fades in ~3 months
+    5: 365.0,  # critical — fades in ~1 year
+}
+
+# Access reinforcement: each retrieval extends half-life by this factor
+ACCESS_BOOST = 0.15  # +15% half-life per access
+
+
+def compute_decay(
+    importance: int,
+    created_at: str,
+    last_accessed: str | None,
+    access_count: int,
+) -> float:
+    """
+    Compute current decay score (0.0–1.0) for a memory.
+    1.0 = perfectly fresh, 0.0 = completely faded.
+    """
+    reference_time = last_accessed or created_at
+    try:
+        ref_dt = datetime.fromisoformat(reference_time).replace(tzinfo=timezone.utc)
+    except ValueError:
+        ref_dt = datetime.now(timezone.utc)
+
+    now = datetime.now(timezone.utc)
+    days_elapsed = max(0.0, (now - ref_dt).total_seconds() / 86400)
+
+    base_half_life = HALF_LIFE.get(importance, 14.0)
+    effective_half_life = base_half_life * (1 + ACCESS_BOOST * access_count)
+
+    # Ebbinghaus formula: R = e^(-t/S) where S is stability (half-life)
+    decay = math.exp(-days_elapsed * math.log(2) / effective_half_life)
+    return round(min(1.0, max(0.0, decay)), 4)
+
+
+def effective_score(decay_score: float, importance: int) -> float:
+    """
+    Combined relevance score used for ranking search results.
+    Balances semantic similarity with memory freshness and importance.
+    """
+    importance_weight = importance / 5.0  # normalize to 0.2–1.0
+    return round(decay_score * importance_weight, 4)
+
+
+def should_forget(decay_score: float, threshold: float = 0.05) -> bool:
+    """Returns True when a memory has faded below the forgetting threshold."""
+    return decay_score < threshold

src/embedder.py

@@ -0,0 +1,50 @@
+"""
+Kore — Embedder (v2)
+Lazy-loaded sentence embeddings using a small multilingual model.
+Model: paraphrase-multilingual-MiniLM-L12-v2 (~120MB, supports Italian + English)
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
+MODEL_NAME = "paraphrase-multilingual-MiniLM-L12-v2"
+
+
+@lru_cache(maxsize=1)
+def get_model() -> "SentenceTransformer":
+    """Load model once and cache it in memory."""
+    from sentence_transformers import SentenceTransformer
+    return SentenceTransformer(MODEL_NAME)
+
+
+def embed(text: str) -> list[float]:
+    """Return embedding vector for a single text."""
+    model = get_model()
+    vector = model.encode(text, normalize_embeddings=True)
+    return vector.tolist()
+
+
+def embed_batch(texts: list[str]) -> list[list[float]]:
+    """Return embedding vectors for a list of texts."""
+    model = get_model()
+    vectors = model.encode(texts, normalize_embeddings=True, batch_size=32)
+    return [v.tolist() for v in vectors]
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Dot product of two normalized vectors = cosine similarity."""
+    return sum(x * y for x, y in zip(a, b))
+
+
+def serialize(vector: list[float]) -> str:
+    return json.dumps(vector)
+
+
+def deserialize(blob: str) -> list[float]:
+    return json.loads(blob)

src/main.py

@@ -0,0 +1,138 @@
+"""
+Kore — FastAPI application
+Memory layer with decay, auto-scoring, compression, semantic search, and auth.
+"""
+
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, HTTPException, Query
+from fastapi.responses import JSONResponse
+
+from .auth import get_agent_id, require_auth
+from .database import init_db
+from .models import (
+    CompressRunResponse,
+    DecayRunResponse,
+    MemorySaveRequest,
+    MemorySaveResponse,
+    MemorySearchResponse,
+)
+from .repository import (
+    delete_memory,
+    get_timeline,
+    run_decay_pass,
+    save_memory,
+    search_memories,
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    init_db()
+    yield
+
+
+app = FastAPI(
+    title="Kore",
+    description=(
+        "The memory layer that thinks like a human: "
+        "remembers what matters, forgets what doesn't, and never calls home."
+    ),
+    version="0.2.0",
+    lifespan=lifespan,
+)
+
+# Shared auth dependencies
+_Auth = Depends(require_auth)
+_Agent = Depends(get_agent_id)
+
+
+# ── Core endpoints ────────────────────────────────────────────────────────────
+
+@app.post("/save", response_model=MemorySaveResponse, status_code=201)
+def save(
+    req: MemorySaveRequest,
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> MemorySaveResponse:
+    """Save a memory scoped to the requesting agent. Importance is auto-scored if omitted."""
+    from .scorer import auto_score
+    importance = req.importance if req.importance > 1 else auto_score(req.content, req.category)
+    memory_id = save_memory(req, agent_id=agent_id)
+    return MemorySaveResponse(id=memory_id, importance=importance)
+
+
+@app.get("/search", response_model=MemorySearchResponse)
+def search(
+    q: str = Query(..., min_length=1, description="Search query (any language)"),
+    limit: int = Query(5, ge=1, le=20),
+    category: str | None = Query(None),
+    semantic: bool = Query(True),
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> MemorySearchResponse:
+    """Semantic search scoped to the requesting agent."""
+    results = search_memories(query=q, limit=limit, category=category, semantic=semantic, agent_id=agent_id)
+    return MemorySearchResponse(results=results, total=len(results))
+
+
+@app.get("/timeline", response_model=MemorySearchResponse)
+def timeline(
+    subject: str = Query(..., min_length=1),
+    limit: int = Query(20, ge=1, le=50),
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> MemorySearchResponse:
+    """Chronological memory history for a subject, scoped to agent."""
+    results = get_timeline(subject=subject, limit=limit, agent_id=agent_id)
+    return MemorySearchResponse(results=results, total=len(results))
+
+
+@app.delete("/memories/{memory_id}", status_code=204)
+def delete(
+    memory_id: int,
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> None:
+    """Delete a memory. Agents can only delete their own memories."""
+    if not delete_memory(memory_id, agent_id=agent_id):
+        raise HTTPException(status_code=404, detail="Memory not found")
+
+
+# ── Maintenance endpoints ─────────────────────────────────────────────────────
+
+@app.post("/decay/run", response_model=DecayRunResponse)
+def decay_run(
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> DecayRunResponse:
+    """Recalculate decay scores for agent's memories."""
+    updated = run_decay_pass(agent_id=agent_id)
+    return DecayRunResponse(updated=updated)
+
+
+@app.post("/compress", response_model=CompressRunResponse)
+def compress(
+    _: str = _Auth,
+    agent_id: str = _Agent,
+) -> CompressRunResponse:
+    """Merge similar memories for this agent."""
+    from .compressor import run_compression
+    result = run_compression(agent_id=agent_id)
+    return CompressRunResponse(
+        clusters_found=result.clusters_found,
+        memories_merged=result.memories_merged,
+        new_records_created=result.new_records_created,
+    )
+
+
+# ── Utility ───────────────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health() -> JSONResponse:
+    from .repository import _embeddings_available
+    return JSONResponse({
+        "status": "ok",
+        "version": app.version,
+        "semantic_search": _embeddings_available(),
+    })

src/models.py

@@ -0,0 +1,68 @@
+"""
+Kore — Pydantic models
+Request/response schemas with validation.
+"""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+Category = Literal[
+    "general",
+    "project",
+    "trading",
+    "finance",
+    "person",
+    "preference",
+    "task",
+    "decision",
+]
+
+
+class MemorySaveRequest(BaseModel):
+    content: str = Field(..., min_length=3, max_length=4000)
+    category: Category = Field("general")
+    importance: int = Field(1, ge=1, le=5, description="1=auto-scored, 2-5=explicit")
+
+    @field_validator("content")
+    @classmethod
+    def content_must_not_be_blank(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Content cannot be blank")
+        return v.strip()
+
+
+class MemoryRecord(BaseModel):
+    id: int
+    content: str
+    category: str
+    importance: int
+    decay_score: float = 1.0
+    created_at: datetime
+    updated_at: datetime
+    score: float | None = None
+
+
+class MemorySaveResponse(BaseModel):
+    id: int
+    importance: int
+    message: str = "Memory saved"
+
+
+class MemorySearchResponse(BaseModel):
+    results: list[MemoryRecord]
+    total: int
+
+
+class DecayRunResponse(BaseModel):
+    updated: int
+    message: str = "Decay pass complete"
+
+
+class CompressRunResponse(BaseModel):
+    clusters_found: int
+    memories_merged: int
+    new_records_created: int
+    message: str = "Compression complete"

src/repository.py

@@ -0,0 +1,269 @@
+"""
+Kore — Repository layer
+All database operations, keeping business logic out of routes.
+"""
+
+from datetime import datetime, timezone
+
+from .database import get_connection
+from .decay import compute_decay, effective_score, should_forget
+from .models import MemoryRecord, MemorySaveRequest
+from .scorer import auto_score
+
+_EMBEDDINGS_AVAILABLE: bool | None = None
+
+
+def _embeddings_available() -> bool:
+    global _EMBEDDINGS_AVAILABLE
+    if _EMBEDDINGS_AVAILABLE is None:
+        try:
+            import sentence_transformers  # noqa: F401
+            _EMBEDDINGS_AVAILABLE = True
+        except ImportError:
+            _EMBEDDINGS_AVAILABLE = False
+    return _EMBEDDINGS_AVAILABLE
+
+
+def save_memory(req: MemorySaveRequest, agent_id: str = "default") -> int:
+    """
+    Persist a new memory record scoped to agent_id.
+    Auto-scores importance if not explicitly set.
+    Returns the new row id.
+    """
+    importance = req.importance
+    if importance == 1:
+        importance = auto_score(req.content, req.category)
+
+    embedding_blob = None
+    if _embeddings_available():
+        from .embedder import embed, serialize
+        embedding_blob = serialize(embed(req.content))
+
+    with get_connection() as conn:
+        cursor = conn.execute(
+            """
+            INSERT INTO memories (agent_id, content, category, importance, embedding)
+            VALUES (:agent_id, :content, :category, :importance, :embedding)
+            """,
+            {
+                "agent_id": agent_id,
+                "content": req.content,
+                "category": req.category,
+                "importance": importance,
+                "embedding": embedding_blob,
+            },
+        )
+        return cursor.lastrowid
+
+
+def search_memories(
+    query: str,
+    limit: int = 5,
+    category: str | None = None,
+    semantic: bool = True,
+    agent_id: str = "default",
+) -> list[MemoryRecord]:
+    """
+    Search memories. Uses semantic (embedding) search when available,
+    falls back to FTS5 full-text search, then LIKE.
+    Filters out fully-decayed memories. Reinforces access count on results.
+    """
+    if semantic and _embeddings_available():
+        results = _semantic_search(query, limit * 2, category, agent_id)
+    else:
+        results = _fts_search(query, limit * 2, category, agent_id)
+
+    # Filter forgotten memories, re-rank by effective score
+    alive = [r for r in results if not should_forget(r.decay_score or 1.0)]
+    alive.sort(key=lambda r: effective_score(r.decay_score or 1.0, r.importance), reverse=True)
+    top = alive[:limit]
+
+    # Reinforce access for retrieved memories
+    if top:
+        _reinforce([r.id for r in top])
+
+    return top
+
+
+def delete_memory(memory_id: int, agent_id: str = "default") -> bool:
+    """Delete a memory by id, scoped to agent. Returns True if deleted."""
+    with get_connection() as conn:
+        cursor = conn.execute(
+            "DELETE FROM memories WHERE id = ? AND agent_id = ?",
+            (memory_id, agent_id),
+        )
+        return cursor.rowcount > 0
+
+
+def run_decay_pass(agent_id: str | None = None) -> int:
+    """
+    Recalculate decay_score for all active memories (optionally scoped to agent).
+    Returns the count of memories updated.
+    """
+    with get_connection() as conn:
+        sql = "SELECT id, importance, created_at, last_accessed, access_count FROM memories WHERE compressed_into IS NULL"
+        params: list = []
+        if agent_id:
+            sql += " AND agent_id = ?"
+            params.append(agent_id)
+        rows = conn.execute(sql, params).fetchall()
+
+    updated = 0
+    for row in rows:
+        new_score = compute_decay(
+            importance=row["importance"],
+            created_at=row["created_at"],
+            last_accessed=row["last_accessed"],
+            access_count=row["access_count"],
+        )
+        with get_connection() as conn:
+            conn.execute(
+                "UPDATE memories SET decay_score = ?, updated_at = datetime('now') WHERE id = ?",
+                (new_score, row["id"]),
+            )
+        updated += 1
+
+    return updated
+
+
+def get_timeline(subject: str, limit: int = 20, agent_id: str = "default") -> list[MemoryRecord]:
+    """Return memories about a subject ordered by creation time (oldest first)."""
+    if _embeddings_available():
+        results = _semantic_search(subject, limit, category=None, agent_id=agent_id)
+    else:
+        results = _fts_search(subject, limit, category=None, agent_id=agent_id)
+    return sorted(results, key=lambda r: r.created_at)
+
+
+# ── Private helpers ──────────────────────────────────────────────────────────
+
+def _reinforce(memory_ids: list[int]) -> None:
+    """Increment access_count and update last_accessed for retrieved memories."""
+    now = datetime.now(timezone.utc).isoformat()
+    with get_connection() as conn:
+        conn.executemany(
+            """
+            UPDATE memories
+            SET access_count = access_count + 1,
+                last_accessed = ?,
+                decay_score   = MIN(1.0, decay_score + 0.05),
+                updated_at    = datetime('now')
+            WHERE id = ?
+            """,
+            [(now, mid) for mid in memory_ids],
+        )
+
+
+def _fts_search(query: str, limit: int, category: str | None, agent_id: str = "default") -> list[MemoryRecord]:
+    """Full-text search via SQLite FTS5 with prefix wildcards, scoped to agent."""
+    with get_connection() as conn:
+        safe_query = _sanitize_fts_query(query)
+
+        if safe_query:
+            sql = """
+                SELECT m.id, m.content, m.category, m.importance,
+                       m.decay_score, m.access_count, m.last_accessed,
+                       m.created_at, m.updated_at, rank AS score
+                FROM memories_fts
+                JOIN memories m ON memories_fts.rowid = m.id
+                WHERE memories_fts MATCH :query
+                  AND m.agent_id = :agent_id
+                  AND m.compressed_into IS NULL
+                  {category_filter}
+                ORDER BY rank, m.importance DESC
+                LIMIT :limit
+            """
+            params: dict = {"query": safe_query, "limit": limit, "agent_id": agent_id}
+        else:
+            sql = """
+                SELECT id, content, category, importance,
+                       decay_score, access_count, last_accessed,
+                       created_at, updated_at, NULL AS score
+                FROM memories
+                WHERE content LIKE :query
+                  AND agent_id = :agent_id
+                  AND compressed_into IS NULL
+                  {category_filter}
+                ORDER BY importance DESC, created_at DESC
+                LIMIT :limit
+            """
+            params = {"query": f"%{query}%", "limit": limit, "agent_id": agent_id}
+
+        category_filter = (
+            "AND m.category = :category" if safe_query and category
+            else "AND category = :category" if category
+            else ""
+        )
+        if category:
+            params["category"] = category
+
+        rows = conn.execute(sql.format(category_filter=category_filter), params).fetchall()
+
+    return [_row_to_record(r) for r in rows]
+
+
+def _semantic_search(query: str, limit: int, category: str | None, agent_id: str = "default") -> list[MemoryRecord]:
+    """Cosine similarity search over stored embeddings, scoped to agent."""
+    from .embedder import cosine_similarity, deserialize, embed
+
+    query_vec = embed(query)
+
+    with get_connection() as conn:
+        sql = """
+            SELECT id, content, category, importance,
+                   decay_score, access_count, last_accessed,
+                   embedding, created_at, updated_at
+            FROM memories
+            WHERE embedding IS NOT NULL
+              AND compressed_into IS NULL
+              AND agent_id = ?
+        """
+        params: list = [agent_id]
+        if category:
+            sql += " AND category = ?"
+            params.append(category)
+        rows = conn.execute(sql, params).fetchall()
+
+    scored = []
+    for row in rows:
+        vec = deserialize(row["embedding"])
+        sim = cosine_similarity(query_vec, vec)
+        scored.append((sim, row))
+
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    return [
+        MemoryRecord(
+            id=row["id"],
+            content=row["content"],
+            category=row["category"],
+            importance=row["importance"],
+            decay_score=row["decay_score"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            score=round(sim, 4),
+        )
+        for sim, row in scored[:limit]
+    ]
+
+
+def _sanitize_fts_query(query: str) -> str:
+    special = set('"^():-')
+    cleaned = "".join(c if c not in special else " " for c in query).strip()
+    if not cleaned:
+        return ""
+    tokens = [t for t in cleaned.split() if t]
+    return " OR ".join(f"{t}*" for t in tokens)
+
+
+def _row_to_record(row) -> MemoryRecord:
+    return MemoryRecord(
+        id=row["id"],
+        content=row["content"],
+        category=row["category"],
+        importance=row["importance"],
+        decay_score=row["decay_score"] if "decay_score" in row.keys() else 1.0,
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+        score=row["score"],
+    )

src/scorer.py

@@ -0,0 +1,70 @@
+"""
+Kore — Auto-Importance Scorer
+Calculates memory importance (1–5) locally, without any LLM API call.
+
+Scoring factors:
+  1. Content length       — longer = more detailed = more important
+  2. Keyword signals      — critical words bump importance up
+  3. Category baseline    — some categories are inherently more important
+  4. Uniqueness           — if similar memories exist with high importance, inherit it
+"""
+
+import re
+
+# Keywords that signal high importance
+HIGH_IMPORTANCE_KEYWORDS = {
+    5: [
+        "password", "token", "chiave", "secret", "api key", "credenziali",
+        "urgente", "critico", "never", "mai", "sempre", "always",
+        "private key", "segreto",
+    ],
+    4: [
+        "decisione", "decision", "importante", "important", "priorità", "priority",
+        "deadline", "scadenza", "pagamento", "payment", "debito", "debt",
+        "errore critico", "bug critico", "non fare", "do not", "regola",
+    ],
+    3: [
+        "progetto", "project", "strategia", "strategy", "obiettivo", "goal",
+        "configurazione", "config", "server", "deploy", "produzione",
+    ],
+    2: [
+        "nota", "note", "reminder", "appunto", "considerare", "consider",
+    ],
+}
+
+# Category importance baselines
+CATEGORY_BASELINE: dict[str, int] = {
+    "general":    1,
+    "preference": 4,
+    "decision":   4,
+    "finance":    3,
+    "trading":    3,
+    "project":    3,
+    "task":       2,
+    "person":     2,
+}
+
+
+def auto_score(content: str, category: str) -> int:
+    """
+    Return an importance score (1–5) based on content analysis.
+    Used when importance is not explicitly set.
+    """
+    score = CATEGORY_BASELINE.get(category, 2)
+    content_lower = content.lower()
+
+    # Keyword signals — take the highest match
+    for level in sorted(HIGH_IMPORTANCE_KEYWORDS.keys(), reverse=True):
+        for kw in HIGH_IMPORTANCE_KEYWORDS[level]:
+            if kw in content_lower:
+                score = max(score, level)
+                break
+
+    # Length bonus: detailed content is likely more important
+    word_count = len(content.split())
+    if word_count > 60:
+        score = min(5, score + 1)
+    elif word_count > 30:
+        score = min(5, score + 0)  # no change, just don't penalize
+
+    return max(1, min(5, score))