memor-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{memor_cli-0.3.0/memor_cli.egg-info → memor_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memor-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Measured memory for coding agents. Fire and forget — no API keys needed.
 Author-email: Nimit Bhandari <nimitbhandari17@gmail.com>
 License-Expression: MIT
@@ -46,7 +46,7 @@ Dynamic: license-file
 ```
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-215%20passing-brightgreen.svg)]()
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memor-cli.svg)](https://pypi.org/project/memor-cli/)
 
@@ -290,7 +290,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 179 tests
+pytest  # 215 tests
 ```
 
 ---

{memor_cli-0.3.0 → memor_cli-0.4.0}/README.md

@@ -9,7 +9,7 @@
 ```
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-179%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-215%20passing-brightgreen.svg)]()
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memor-cli.svg)](https://pypi.org/project/memor-cli/)
 
@@ -253,7 +253,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 179 tests
+pytest  # 215 tests
 ```
 
 ---

memor_cli-0.4.0/memor/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/daemon.py

@@ -146,7 +146,7 @@ def distill_new_sessions(
     return distilled
 
 
-COMPACT_SIM_THRESHOLD = 0.90
+COMPACT_SIM_THRESHOLD = 0.85
 
 
 def compact_memories(store: SqliteStore, embedder) -> int:
@@ -239,12 +239,34 @@ def run_poll_cycle(
         for path, project in pending:
             session_id = path.stem
             try:
-                used = analyze_session_feedback(store, session_id, path)
+                used = analyze_session_feedback(store, session_id, path, embedder=embedder)
                 if used > 0:
                     print(f"  feedback: {used} memories confirmed used in {session_id[:12]}...")
             except Exception:
                 pass
 
+    # Turn-level metrics: parse tool calls per turn, correlate with recalls
+    if new_ingested:
+        from memor.turn_metrics import parse_turn_metrics, correlate_with_recalls
+        for path, project in pending:
+            session_id = path.stem
+            try:
+                metrics = parse_turn_metrics(path, session_id)
+                if metrics:
+                    metrics = correlate_with_recalls(metrics, store, session_id)
+                    store.save_turn_metrics(session_id, project, metrics)
+            except Exception:
+                pass
+
+    # Soft quality decay: unused memories lose quality over time
+    if new_ingested:
+        try:
+            decayed = store.decay_quality(stale_days=14, factor=0.5, deactivate_floor=0.03)
+            if decayed > 0:
+                print(f"  decayed quality for {decayed} stale memories")
+        except Exception:
+            pass
+
     # Compact near-duplicate memories (run occasionally, not every cycle)
     if new_ingested:
         try:

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/dashboard/server.py

@@ -134,6 +134,11 @@ def create_app(db_path: str | None = None) -> FastAPI:
         """, (f"-{days}",)).fetchall()
         return [dict(r) for r in rows]
 
+    @app.get("/api/roi")
+    def roi(project: str | None = Query(None)):
+        store = _store()
+        return store.get_token_roi(project=project)
+
     @app.get("/api/health")
     def health():
         store = _store()

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/dashboard/static/index.html

@@ -426,6 +426,32 @@
           </div>
         </div>
       </div>
+      <div class="chart-card">
+        <div class="chart-header">
+          <div class="chart-title">Token ROI</div>
+        </div>
+        <div id="roi-banner" style="display:none;background:var(--ok-dim);border:1px solid rgba(61,214,140,0.2);border-radius:var(--radius-sm);padding:12px 14px;margin-bottom:14px;">
+          <div style="font-size:22px;font-weight:700;color:var(--ok);letter-spacing:-0.5px;" id="roi-value">&ndash;</div>
+          <div style="font-size:11px;color:var(--text-muted);margin-top:2px;" id="roi-desc">fewer tool calls when Memor injects context</div>
+        </div>
+        <div class="side-stats" id="roi-side">
+          <div class="side-stat">
+            <div class="side-stat-label">Avg Tools / Turn (with recall)</div>
+            <div class="side-stat-value" id="roi-tools-with">&ndash;</div>
+            <div class="side-stat-sub">when Memor injected context</div>
+          </div>
+          <div class="side-stat">
+            <div class="side-stat-label">Avg Tools / Turn (without)</div>
+            <div class="side-stat-value" id="roi-tools-without">&ndash;</div>
+            <div class="side-stat-sub">when no context was injected</div>
+          </div>
+          <div class="side-stat">
+            <div class="side-stat-label">Turns Measured</div>
+            <div class="side-stat-value" id="roi-turns">&ndash;</div>
+            <div class="side-stat-sub" id="roi-turns-sub">with vs. without recall</div>
+          </div>
+        </div>
+      </div>
     </div>
   </section>
 
@@ -781,6 +807,38 @@
       msg.innerHTML = 'Status: <strong>' + esc(status) + '</strong>. Run <code>memor help</code> for guidance.';
   }
 
+  /* ── ROI renderer ─────────────────────────────────────── */
+  function renderROI(data) {
+    document.getElementById('roi-tools-with').textContent = data.avg_tools_with_recall;
+    document.getElementById('roi-tools-without').textContent = data.avg_tools_without_recall;
+    document.getElementById('roi-turns').textContent =
+      (data.turns_with_recall + data.turns_without_recall).toLocaleString();
+    document.getElementById('roi-turns-sub').textContent =
+      data.turns_with_recall + ' with recall · ' + data.turns_without_recall + ' without';
+
+    var banner = document.getElementById('roi-banner');
+    var roiValue = document.getElementById('roi-value');
+    var roiDesc = document.getElementById('roi-desc');
+    banner.style.display = 'none';
+    banner.style.background = 'var(--ok-dim)';
+    banner.style.borderColor = 'rgba(61,214,140,0.2)';
+    roiValue.style.color = 'var(--ok)';
+    roiValue.textContent = '–';
+    roiDesc.textContent = 'fewer tool calls when Memor injects context';
+
+    if (data.tool_call_reduction_pct > 0 && data.turns_with_recall >= 5 && data.turns_without_recall >= 5) {
+      roiValue.textContent = data.tool_call_reduction_pct + '% fewer';
+      banner.style.display = 'block';
+    } else if (data.tool_call_reduction_pct < 0 && data.turns_with_recall >= 5) {
+      roiValue.textContent = Math.abs(data.tool_call_reduction_pct) + '% more';
+      roiValue.style.color = 'var(--warn)';
+      roiDesc.textContent = 'tool calls with recall — investigating...';
+      banner.style.display = 'block';
+      banner.style.background = 'var(--warn-dim)';
+      banner.style.borderColor = 'rgba(232,147,32,0.2)';
+    }
+  }
+
   /* ── Data loaders ──────────────────────────────────────── */
   async function loadSummary()    { try { renderSummary(await api('/api/summary')); } catch(e) { console.warn('summary',e); } }
   async function loadProjects()   { try { renderProjects(await api('/api/projects')); } catch(e) { console.warn('projects',e); } }
@@ -788,6 +846,7 @@
   async function loadSessionEfficiency() { try { renderSessionEfficiency(await api('/api/session-efficiency')); } catch(e) { console.warn('session-efficiency',e); } }
   async function loadHealth()     { try { renderHealth(await api('/api/health')); } catch(e) { console.warn('health',e); } }
   async function loadTrend()      { try { renderTrend(await api('/api/recall-trend?days=30')); } catch(e) { console.warn('trend',e); } }
+  async function loadROI()        { try { renderROI(await api('/api/roi')); } catch(e) { console.warn('roi',e); } }
   async function loadRecalls() {
     try {
       var url = '/api/recalls?limit=50' + (projectFilter ? '&project=' + encodeURIComponent(projectFilter) : '');
@@ -796,7 +855,7 @@
   }
 
   async function refresh() {
-    await Promise.allSettled([loadSummary(), loadProjects(), loadEfficiency(), loadSessionEfficiency(), loadHealth(), loadTrend(), loadRecalls()]);
+    await Promise.allSettled([loadSummary(), loadProjects(), loadEfficiency(), loadSessionEfficiency(), loadHealth(), loadTrend(), loadRecalls(), loadROI()]);
     document.getElementById('last-updated').textContent = new Date().toLocaleTimeString();
 
     renderMiniBars('mb-chunks', null);

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/distill/distiller.py

@@ -99,11 +99,14 @@ class ExtractiveDistiller:
     def distill_session(
         self, session_id: str, chunks: list[Artifact], project: str
     ) -> list[str]:
-        from memor.distill.extractive import classify_chunk
+        from memor.distill.extractive import classify_chunk, score_chunks, MIN_MEMORY_SIGNAL
         key_chunks = extract_key_chunks(chunks, self.embedder)
+        scores = score_chunks(key_chunks)
         created = max((c.created_at for c in chunks), default=0.0)
         new_ids: list[str] = []
-        for c in key_chunks:
+        for c, score in zip(key_chunks, scores):
+            if score < MIN_MEMORY_SIGNAL:
+                continue
             mem_type = classify_chunk(c.text)
             mid = _store_memory(self.store, self.embedder, c.text, mem_type,
                                 session_id, project, created, [c])

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/distill/extractive.py

@@ -132,13 +132,13 @@ def _cluster_select(chunks: list[Artifact], embedder, max_clusters: int) -> list
     return selected
 
 
-def extract_key_chunks(
-    chunks: list[Artifact], embedder, *, max_extracts: int = MAX_EXTRACTS
-) -> list[Artifact]:
-    """Select the highest-signal chunks from a session. Pure local, no LLM."""
+MIN_MEMORY_SIGNAL = 0.3
+
+
+def score_chunks(chunks: list[Artifact]) -> list[float]:
+    """Score each chunk by TF-IDF + heuristic. Returns parallel list of scores."""
     if not chunks:
         return []
-    # Score each chunk: TF-IDF + heuristic
     tfidf = _tfidf_scores(chunks)
     max_tf = max(tfidf) or 1.0
     combined = []
@@ -148,6 +148,16 @@ def extract_key_chunks(
             combined.append(-999.0)
             continue
         combined.append((tfidf[i] / max_tf) + h)
+    return combined
+
+
+def extract_key_chunks(
+    chunks: list[Artifact], embedder, *, max_extracts: int = MAX_EXTRACTS
+) -> list[Artifact]:
+    """Select the highest-signal chunks from a session. Pure local, no LLM."""
+    if not chunks:
+        return []
+    combined = score_chunks(chunks)
     # Pre-filter: drop anything scored below 0
     viable_idx = [i for i, s in enumerate(combined) if s > 0]
     if not viable_idx:

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/feedback.py

@@ -2,7 +2,12 @@
 
 After a session ends, cross-references recall_log with the transcript to see
 if the agent's responses referenced recalled content. Updates memory_quality
-scores accordingly."""
+scores accordingly.
+
+Two matching strategies:
+1. N-gram overlap (fast, catches verbatim reuse)
+2. Semantic similarity via embeddings (catches paraphrased reuse)
+"""
 from __future__ import annotations
 import json
 import math
@@ -12,6 +17,7 @@ from memor.store.sqlite_store import SqliteStore
 _NGRAM_SIZE = 3
 _MIN_WORDS = 4
 _MATCH_RATIO = 0.10
+_SEMANTIC_SIM_THRESHOLD = 0.45
 
 
 def _extract_assistant_texts(transcript_path: Path) -> list[str]:
@@ -55,8 +61,25 @@ def _text_was_used(memory_text: str, assistant_texts: list[str]) -> bool:
     return matches >= max(1, math.ceil(len(ngrams) * _MATCH_RATIO))
 
 
+def _cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(x * x for x in b))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+def _semantic_match(memory_text: str, response_text: str, embedder) -> bool:
+    """Check if memory content appears in the response via embedding similarity.
+    Catches paraphrased reuse that n-gram matching misses."""
+    if len(memory_text.split()) < _MIN_WORDS:
+        return False
+    vecs = embedder.embed([memory_text, response_text])
+    return _cosine(vecs[0], vecs[1]) >= _SEMANTIC_SIM_THRESHOLD
+
+
 def analyze_session_feedback(
-    store: SqliteStore, session_id: str, transcript_path: Path
+    store: SqliteStore, session_id: str, transcript_path: Path,
+    *, embedder=None,
 ) -> int:
     recalled_ids = set()
     rows = store.db.execute("""
@@ -88,11 +111,16 @@ def analyze_session_feedback(
         return 0
 
     used_ids = []
+    combined_response = " ".join(assistant_texts) if embedder else ""
     for aid in recalled_ids:
         art = store.db.execute(
             "SELECT text FROM artifacts WHERE id=?", (aid,)
         ).fetchone()
-        if art and _text_was_used(art["text"], assistant_texts):
+        if not art:
+            continue
+        if _text_was_used(art["text"], assistant_texts):
+            used_ids.append(aid)
+        elif embedder and _semantic_match(art["text"], combined_response, embedder):
             used_ids.append(aid)
 
     if used_ids:

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/hook_server.py

@@ -11,19 +11,15 @@ SOCK_PATH = Path.home() / ".memor" / "hook.sock"
 PID_PATH = Path.home() / ".memor" / "hook.pid"
 DEFAULT_DB = str(Path.home() / ".memor" / "memor.db")
 IDLE_TIMEOUT_S = 600
-MIN_QUERY_WORDS = 10
-_TRIVIAL_PATTERNS = frozenset({
-    "yes", "no", "ok", "okay", "sure", "thanks", "thank you", "ty",
-    "looks good", "lgtm", "continue", "go ahead", "do it", "proceed",
-    "correct", "right", "yep", "yup", "nope", "agreed", "sounds good",
-    "perfect", "great", "nice", "cool", "done", "got it", "k",
-})
 
 _embedder = None
 _last_activity = 0.0
 _session_injected: dict[str, set[str]] = {}
 _MAX_TRACKED_SESSIONS = 50
 
+from memor.session_context import SessionContextWindow
+_session_ctx = SessionContextWindow(max_queries=5, max_sessions=_MAX_TRACKED_SESSIONS)
+
 _UNSET = object()  # sentinel for "auto-discover embedder"
 
 
@@ -62,9 +58,10 @@ def handle_request(req: dict, *, db_path: str = DEFAULT_DB,
             }
         }
 
-    query_stripped = query.strip().rstrip("?!.,").strip().lower()
-    query_word_count = len(query.split())
-    if query_word_count < MIN_QUERY_WORDS and query_stripped in _TRIVIAL_PATTERNS:
+    from memor.query_complexity import route_query, Tier
+
+    tier = route_query(query)
+    if tier == Tier.SKIP:
         msg = "Memor: skipped — trivial prompt"
         if Path(db_path).exists():
             try:
@@ -85,18 +82,23 @@ def handle_request(req: dict, *, db_path: str = DEFAULT_DB,
         }
 
     try:
-        max_tokens = max(0, int(os.environ.get("MEMOR_MAX_TOKENS", "1500")))
+        env_max = int(os.environ.get("MEMOR_MAX_TOKENS", "0"))
     except (ValueError, TypeError):
-        max_tokens = 1500
+        env_max = 0
+    max_tokens = env_max if env_max > 0 else tier.max_tokens
     try:
         min_similarity = float(os.environ.get("MEMOR_MIN_SIMILARITY", "0.0"))
     except (ValueError, TypeError):
         min_similarity = 0.0
+    retrieval_query = _session_ctx.enrich(query, session_id) if session_id else query
     already_injected = _session_injected.get(session_id, set()) if session_id else set()
-    result = recall(query, project, db_path, embedder=embedder, k=8, threshold=0.15,
-                    max_tokens=max_tokens, min_similarity=min_similarity,
+    result = recall(retrieval_query, project, db_path, embedder=embedder, k=tier.k,
+                    threshold=0.15, max_tokens=max_tokens, min_similarity=min_similarity,
                     exclude_ids=already_injected or None, session_id=session_id)
 
+    if session_id:
+        _session_ctx.record(session_id, query)
+
     if session_id and result.hit_ids:
         _session_injected.setdefault(session_id, set()).update(result.hit_ids)
         if len(_session_injected) > _MAX_TRACKED_SESSIONS:

memor_cli-0.4.0/memor/query_complexity.py

@@ -0,0 +1,92 @@
+"""Query complexity scoring and budget routing.
+
+Scores queries by word count, identifier density, path references, and
+question structure. Routes to budget tiers so trivial prompts skip recall,
+simple follow-ups get a light budget, and complex queries get full retrieval.
+"""
+from __future__ import annotations
+
+import enum
+import re
+
+_IDENTIFIER_RE = re.compile(
+    r"[A-Z][a-z]+[A-Z]"           # camelCase/PascalCase
+    r"|[a-z]+_[a-z]+"             # snake_case
+    r"|[A-Z]{2,}"                 # SCREAMING_CASE (min 2 chars)
+    r"|\b\w+\.\w+\.\w+"          # dotted.path.ref
+    r"|\w+::\w+"                  # C++ scope
+)
+
+_PATH_RE = re.compile(
+    r"[a-zA-Z0-9_\-]+/"           # path components with /
+    r"|\.\w{1,5}\b"               # file extensions (.py, .ts, .yml)
+)
+
+_QUESTION_RE = re.compile(r"\?\s*$")
+
+_ERROR_RE = re.compile(
+    r"(Error|Exception|Traceback|FAIL|panic|segfault|undefined|NaN|null|nil)\b",
+    re.I,
+)
+
+_TRIVIAL_PATTERNS = frozenset({
+    "yes", "no", "ok", "okay", "sure", "thanks", "thank you", "ty",
+    "looks good", "lgtm", "continue", "go ahead", "do it", "proceed",
+    "correct", "right", "yep", "yup", "nope", "agreed", "sounds good",
+    "perfect", "great", "nice", "cool", "done", "got it", "k",
+    "yes please", "no thanks",
+})
+
+
+class Tier(enum.Enum):
+    SKIP = (0, 0)
+    LIGHT = (4, 500)
+    FULL = (8, 1500)
+
+    def __init__(self, k: int, max_tokens: int):
+        self.k = k
+        self.max_tokens = max_tokens
+
+
+def score_query(query: str) -> float:
+    """Score query complexity on [0, 1]. Higher = more context needed."""
+    text = query.strip()
+    if not text:
+        return 0.0
+
+    normalized = text.rstrip("?!.,").strip().lower()
+    if normalized in _TRIVIAL_PATTERNS:
+        return 0.0
+
+    words = text.split()
+    n = len(words)
+
+    word_score = min(1.0, n * n / (n * n + 36))
+
+    id_matches = len(_IDENTIFIER_RE.findall(text))
+    id_score = min(id_matches / 3.0, 1.0)
+
+    path_matches = len(_PATH_RE.findall(text))
+    path_score = min(path_matches / 2.0, 1.0)
+
+    question_score = 0.1 if _QUESTION_RE.search(text) else 0.0
+    error_score = 0.15 if _ERROR_RE.search(text) else 0.0
+
+    raw = (
+        0.45 * word_score
+        + 0.20 * id_score
+        + 0.20 * path_score
+        + question_score
+        + error_score
+    )
+    return min(raw, 1.0)
+
+
+def route_query(query: str) -> Tier:
+    """Route a query to a retrieval budget tier based on its complexity."""
+    s = score_query(query)
+    if s < 0.05:
+        return Tier.SKIP
+    if s < 0.45:
+        return Tier.LIGHT
+    return Tier.FULL

memor_cli-0.4.0/memor/session_context.py

@@ -0,0 +1,42 @@
+"""Session context window — tracks recent queries per session to enrich
+sparse follow-up prompts with conversational context for retrieval.
+
+When a user types "try the other approach" after discussing OAuth2, the
+retriever gets the enriched query "implement OAuth2 PKCE flow ... try the
+other approach" instead of searching on 5 bare words.
+"""
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from memor.query_complexity import score_query
+
+_SPARSE_THRESHOLD = 0.35
+
+
+class SessionContextWindow:
+    def __init__(self, *, max_queries: int = 5, max_sessions: int = 50):
+        self._max_queries = max_queries
+        self._max_sessions = max_sessions
+        self._windows: OrderedDict[str, list[str]] = OrderedDict()
+
+    def record(self, session_id: str, query: str) -> None:
+        if session_id not in self._windows:
+            if len(self._windows) >= self._max_sessions:
+                self._windows.popitem(last=False)
+            self._windows[session_id] = []
+        else:
+            self._windows.move_to_end(session_id)
+        buf = self._windows[session_id]
+        buf.append(query)
+        if len(buf) > self._max_queries:
+            del buf[0]
+
+    def enrich(self, query: str, session_id: str) -> str:
+        if score_query(query) >= _SPARSE_THRESHOLD:
+            return query
+        history = self._windows.get(session_id)
+        if not history:
+            return query
+        context = " | ".join(history[-2:])
+        return f"{context} | {query}"

{memor_cli-0.3.0 → memor_cli-0.4.0}/memor/store/sqlite_store.py

@@ -20,6 +20,7 @@ class SqliteStore:
         self._init_schema()
         self._check_dim(dim)
         self._migrate_fts()
+        self._migrate_quality_decay()
 
     def _init_schema(self):
         self.db.executescript(f"""
@@ -43,7 +44,8 @@ class SqliteStore:
           recall_count INTEGER DEFAULT 0,
           use_count INTEGER DEFAULT 0,
           last_recalled REAL,
-          quality_score REAL DEFAULT 0.5);
+          quality_score REAL DEFAULT 0.5,
+          last_decayed_at REAL);
         CREATE TABLE IF NOT EXISTS recall_log(
           id INTEGER PRIMARY KEY AUTOINCREMENT,
           timestamp REAL, project TEXT, query_preview TEXT,
@@ -63,6 +65,15 @@ class SqliteStore:
           last_turn_at REAL,
           updated_at REAL NOT NULL DEFAULT 0);
         CREATE INDEX IF NOT EXISTS idx_session_stats_project ON session_stats(project);
+        CREATE TABLE IF NOT EXISTS turn_metrics(
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT NOT NULL,
+          project TEXT NOT NULL,
+          turn_idx INTEGER NOT NULL,
+          user_timestamp REAL,
+          tool_call_count INTEGER DEFAULT 0,
+          had_recall INTEGER DEFAULT 0);
+        CREATE INDEX IF NOT EXISTS idx_turn_metrics_session ON turn_metrics(session_id);
         """)
         self.db.commit()
 
@@ -77,6 +88,16 @@ class SqliteStore:
                 f"but current embedder has dim={dim}. Use the same embedder or re-ingest."
             )
 
+    def _migrate_quality_decay(self):
+        """Add last_decayed_at column to memory_quality if missing."""
+        cols = [r[1] for r in self.db.execute("PRAGMA table_info(memory_quality)").fetchall()]
+        if "last_decayed_at" not in cols:
+            try:
+                self.db.execute("ALTER TABLE memory_quality ADD COLUMN last_decayed_at REAL")
+                self.db.commit()
+            except Exception:
+                pass
+
     def _migrate_fts(self):
         """One-time backfill of the FTS index for databases created before
         lexical search existed. Runs only when artifacts exist but the index is
@@ -320,6 +341,39 @@ class SqliteStore:
         """, (cutoff, cutoff)).fetchall()
         return [r["id"] for r in rows]
 
+    def decay_quality(self, stale_days: int = 14, factor: float = 0.5,
+                      deactivate_floor: float = 0.03) -> int:
+        """Halve quality_score for memories not recalled in stale_days.
+        Only decays each memory once per stale_days interval (tracked via
+        last_decayed_at). Also catches memories with NULL last_recalled
+        that are old enough. If the decayed score drops below
+        deactivate_floor, deactivate the memory.
+        Returns number of memories decayed."""
+        import time as _time
+        now = _time.time()
+        recall_cutoff = now - (stale_days * 86400)
+        decay_cutoff = now - (stale_days * 86400)
+        rows = self.db.execute("""
+            SELECT q.artifact_id, q.quality_score
+            FROM memory_quality q
+            JOIN artifacts a ON a.id = q.artifact_id
+            WHERE a.kind = 'memory' AND a.active = 1
+              AND (q.last_recalled IS NULL OR q.last_recalled < ?)
+              AND (q.last_decayed_at IS NULL OR q.last_decayed_at < ?)
+        """, (recall_cutoff, decay_cutoff)).fetchall()
+        decayed = 0
+        for r in rows:
+            new_score = round(r["quality_score"] * factor, 4)
+            if new_score < deactivate_floor:
+                self.db.execute("UPDATE artifacts SET active=0 WHERE id=?",
+                                (r["artifact_id"],))
+            self.db.execute(
+                "UPDATE memory_quality SET quality_score=?, last_decayed_at=? WHERE artifact_id=?",
+                (new_score, now, r["artifact_id"]))
+            decayed += 1
+        self.db.commit()
+        return decayed
+
     def deactivate_stale(self, days: int = 30) -> int:
         ids = self.get_stale_memories(days)
         for aid in ids:
@@ -474,6 +528,49 @@ class SqliteStore:
             "sessions": sessions,
         }
 
+    def save_turn_metrics(self, session_id: str, project: str, metrics: list) -> None:
+        """Persist per-turn tool call metrics. Idempotent — deletes old metrics
+        for the session first."""
+        self.db.execute("DELETE FROM turn_metrics WHERE session_id=?", (session_id,))
+        for m in metrics:
+            self.db.execute(
+                "INSERT INTO turn_metrics(session_id, project, turn_idx, "
+                "user_timestamp, tool_call_count, had_recall) VALUES(?,?,?,?,?,?)",
+                (session_id, project, m.turn_idx, m.user_timestamp,
+                 m.tool_call_count, 1 if m.had_recall else 0))
+        self.db.commit()
+
+    def get_token_roi(self, project: str | None = None) -> dict:
+        """Compute tool-call ROI: avg tool calls per turn with vs without recall."""
+        where = "WHERE 1=1"
+        params: list = []
+        if project:
+            where += " AND project = ?"
+            params.append(project)
+
+        row = self.db.execute(f"""
+            SELECT
+              COUNT(CASE WHEN had_recall = 1 THEN 1 END) AS turns_with,
+              COUNT(CASE WHEN had_recall = 0 THEN 1 END) AS turns_without,
+              AVG(CASE WHEN had_recall = 1 THEN tool_call_count END) AS avg_with,
+              AVG(CASE WHEN had_recall = 0 THEN tool_call_count END) AS avg_without
+            FROM turn_metrics {where}
+        """, params).fetchone()
+
+        turns_with = row["turns_with"] or 0
+        turns_without = row["turns_without"] or 0
+        avg_with = round(row["avg_with"] or 0, 2)
+        avg_without = round(row["avg_without"] or 0, 2)
+        reduction = round((1 - avg_with / avg_without) * 100, 1) if avg_without > 0 else 0
+
+        return {
+            "turns_with_recall": turns_with,
+            "turns_without_recall": turns_without,
+            "avg_tools_with_recall": avg_with,
+            "avg_tools_without_recall": avg_without,
+            "tool_call_reduction_pct": reduction,
+        }
+
     def get_onboarding_status(self) -> str:
         chunks = self.db.execute(
             "SELECT COUNT(*) as c FROM artifacts WHERE kind='session_chunk' AND active=1"