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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memor-cli
-Version: 0.2.0
+Version: 0.3.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-153%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-179%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/)
 
@@ -65,7 +65,10 @@ pipx install memor-cli
 # Install the Claude Code hook + download embedding model (~60MB)
 memor install-hook
 
-# Start the background daemon
+# Start as a background service (macOS/Linux)
+memor service install
+
+# Or run in the foreground
 memor daemon
 ```
 
@@ -92,7 +95,13 @@ memor dashboard
   Embed query locally (model2vec, ~2ms)
       |
       v
-  Hybrid scoring: similarity + recency + kind weight + quality
+  Hybrid retrieval: dense vectors + lexical BM25, fused (RRF)
+      |
+      v
+  Relevance gate drops off-topic matches (inject nothing if nothing fits)
+      |
+      v
+  Rank: similarity + recency + kind weight + quality
       |
       v
   Inject relevant context into prompt
@@ -104,20 +113,31 @@ memor dashboard
 
 **Two background processes:**
 
-1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates. All local.
+1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates, tracks session-level token usage. All local.
 2. **Hook** — fires on every prompt, recalls relevant memories, injects them as context. Sub-15ms.
 
 **No API keys required.** Embeddings run locally via [model2vec](https://github.com/MinishLab/model2vec) (potion-base-8M, 256-dim). Vectors stored in [sqlite-vec](https://github.com/asg017/sqlite-vec). Everything runs on your machine.
 
 ---
 
-## Hybrid Scoring
+## Hybrid Retrieval
+
+Memor retrieves over two channels and fuses them, so it catches both semantic matches and exact terms:
+
+- **Dense** — local vector similarity (model2vec) for semantic recall.
+- **Lexical** — SQLite FTS5 / BM25 over the raw text, to recover exact identifiers, error strings, and API names that static embeddings blur together.
+
+The two rankings are combined with **Reciprocal Rank Fusion (RRF)**. A **relevance gate** drops anti-correlated (off-topic) candidates *before* ranking, so an unrelated prompt injects nothing rather than the least-bad guess. The lexical channel only activates when the dense channel finds the query on-topic, preventing generic words from pulling in noise.
+
+> Tunable via `MEMOR_MIN_SIMILARITY` (relevance floor, default 0.0) and `MEMOR_MAX_TOKENS` (injection budget, default 1500).
+
+## Scoring
 
-Memor doesn't just match keywords. Each memory is scored by four signals:
+Surviving candidates are ranked by four signals:
 
 | Signal | Weight | How it works |
 |---|---|---|
-| **Semantic similarity** | 50% | Vector cosine distance between query and memory |
+| **Semantic similarity** | 50% | Dense + lexical relevance, fused via RRF |
 | **Recency** | 25% | Exponential decay with 14-day half-life — recent decisions rank higher |
 | **Kind weight** | 15% | Distilled memories (1.3x) rank above raw session chunks (1.0x) |
 | **Quality** | 10% | Bayesian score from implicit feedback — memories the agent actually uses rank higher |
@@ -147,10 +167,11 @@ Memories are automatically classified as `decision`, `bugfix`, `lesson`, `snippe
 memor dashboard
 ```
 
-Shows:
-- **Memory bank** — session chunks, distilled memories, projects tracked
-- **Context efficiency** — overhead %, recall precision, quality scores per session
-- **Per-project breakdown** — which projects have the most context
+Dark fintech-inspired UI showing:
+- **Hero metrics** — total memories, recall count, avg latency, coverage — with sparkline bars
+- **Daily recall activity** — stacked bar chart of hits vs misses over time
+- **Session efficiency** — real token savings measured from API usage data (avg tokens/turn with vs without recall)
+- **Per-project breakdown** — artifact counts, token totals, last activity
 - **Recent recalls** — every hook event with scores, latency, and status
 
 ---
@@ -162,6 +183,11 @@ memor help                           Print the full manual
 memor install-hook                   Install Claude Code hook + download model
 memor daemon                         Auto-ingest + distill (background watcher)
 memor dashboard                      Web dashboard on localhost:8420
+memor version                        Print installed version
+memor service install                Run daemon as background service (launchd/systemd)
+memor service stop                   Stop the background service
+memor service uninstall              Remove the background service
+memor service status                 Check if the service is running
 memor query <text>                   Search memories from the CLI
 memor reingest                       Wipe DB and re-ingest everything
 memor reingest --project <name>      Re-ingest only one project
@@ -193,16 +219,17 @@ memor/
 +-- feedback.py           Implicit feedback analyzer (usage detection)
 |
 +-- retrieve/
-|   +-- retriever.py      Hybrid scoring: similarity + recency + kind + quality
+|   +-- retriever.py      Hybrid retrieval (dense + BM25, RRF) + relevance gate + scoring
 |
 +-- store/
-|   +-- sqlite_store.py   SQLite + sqlite-vec (WAL mode, dimension safety)
+|   +-- sqlite_store.py   SQLite + sqlite-vec + FTS5 (WAL mode, dimension safety)
 |
 +-- embed/
 |   +-- local.py          model2vec (potion-base-8M, 256-dim, ~60MB)
 |   +-- api.py            OpenAI-compatible embedding API (optional)
 |   +-- fake.py           Deterministic SHA-256 embedder (tests)
 |
++-- service.py            Background service management (launchd/systemd)
 +-- dashboard/
 |   +-- server.py         FastAPI dashboard backend
 |   +-- static/index.html Self-contained dashboard (no CDN deps)
@@ -227,7 +254,7 @@ skill/recall.py            Standalone recall script
 **Nothing leaves your machine.** In the default configuration:
 
 - **No telemetry, no analytics, no phone-home.** Zero outbound network calls.
-- **Embeddings run locally** via model2vec ONNX (one-time model download from HuggingFace — no user data sent).
+- **Embeddings run locally** via model2vec static token embeddings — no inference runtime, no GPU (one-time model download from HuggingFace — no user data sent).
 - **Hook transport is a Unix socket** (`~/.memor/hook.sock`), not a network port.
 - **Dashboard binds localhost only.**
 
@@ -263,7 +290,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 153 tests
+pytest  # 179 tests
 ```
 
 ---

{memor_cli-0.2.0 → memor_cli-0.3.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-153%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-179%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/)
 
@@ -28,7 +28,10 @@ pipx install memor-cli
 # Install the Claude Code hook + download embedding model (~60MB)
 memor install-hook
 
-# Start the background daemon
+# Start as a background service (macOS/Linux)
+memor service install
+
+# Or run in the foreground
 memor daemon
 ```
 
@@ -55,7 +58,13 @@ memor dashboard
   Embed query locally (model2vec, ~2ms)
       |
       v
-  Hybrid scoring: similarity + recency + kind weight + quality
+  Hybrid retrieval: dense vectors + lexical BM25, fused (RRF)
+      |
+      v
+  Relevance gate drops off-topic matches (inject nothing if nothing fits)
+      |
+      v
+  Rank: similarity + recency + kind weight + quality
       |
       v
   Inject relevant context into prompt
@@ -67,20 +76,31 @@ memor dashboard
 
 **Two background processes:**
 
-1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates. All local.
+1. **Daemon** — polls `~/.claude/projects/` for transcripts, embeds chunks, runs distillation, analyzes feedback, compacts duplicates, tracks session-level token usage. All local.
 2. **Hook** — fires on every prompt, recalls relevant memories, injects them as context. Sub-15ms.
 
 **No API keys required.** Embeddings run locally via [model2vec](https://github.com/MinishLab/model2vec) (potion-base-8M, 256-dim). Vectors stored in [sqlite-vec](https://github.com/asg017/sqlite-vec). Everything runs on your machine.
 
 ---
 
-## Hybrid Scoring
+## Hybrid Retrieval
+
+Memor retrieves over two channels and fuses them, so it catches both semantic matches and exact terms:
+
+- **Dense** — local vector similarity (model2vec) for semantic recall.
+- **Lexical** — SQLite FTS5 / BM25 over the raw text, to recover exact identifiers, error strings, and API names that static embeddings blur together.
+
+The two rankings are combined with **Reciprocal Rank Fusion (RRF)**. A **relevance gate** drops anti-correlated (off-topic) candidates *before* ranking, so an unrelated prompt injects nothing rather than the least-bad guess. The lexical channel only activates when the dense channel finds the query on-topic, preventing generic words from pulling in noise.
+
+> Tunable via `MEMOR_MIN_SIMILARITY` (relevance floor, default 0.0) and `MEMOR_MAX_TOKENS` (injection budget, default 1500).
+
+## Scoring
 
-Memor doesn't just match keywords. Each memory is scored by four signals:
+Surviving candidates are ranked by four signals:
 
 | Signal | Weight | How it works |
 |---|---|---|
-| **Semantic similarity** | 50% | Vector cosine distance between query and memory |
+| **Semantic similarity** | 50% | Dense + lexical relevance, fused via RRF |
 | **Recency** | 25% | Exponential decay with 14-day half-life — recent decisions rank higher |
 | **Kind weight** | 15% | Distilled memories (1.3x) rank above raw session chunks (1.0x) |
 | **Quality** | 10% | Bayesian score from implicit feedback — memories the agent actually uses rank higher |
@@ -110,10 +130,11 @@ Memories are automatically classified as `decision`, `bugfix`, `lesson`, `snippe
 memor dashboard
 ```
 
-Shows:
-- **Memory bank** — session chunks, distilled memories, projects tracked
-- **Context efficiency** — overhead %, recall precision, quality scores per session
-- **Per-project breakdown** — which projects have the most context
+Dark fintech-inspired UI showing:
+- **Hero metrics** — total memories, recall count, avg latency, coverage — with sparkline bars
+- **Daily recall activity** — stacked bar chart of hits vs misses over time
+- **Session efficiency** — real token savings measured from API usage data (avg tokens/turn with vs without recall)
+- **Per-project breakdown** — artifact counts, token totals, last activity
 - **Recent recalls** — every hook event with scores, latency, and status
 
 ---
@@ -125,6 +146,11 @@ memor help                           Print the full manual
 memor install-hook                   Install Claude Code hook + download model
 memor daemon                         Auto-ingest + distill (background watcher)
 memor dashboard                      Web dashboard on localhost:8420
+memor version                        Print installed version
+memor service install                Run daemon as background service (launchd/systemd)
+memor service stop                   Stop the background service
+memor service uninstall              Remove the background service
+memor service status                 Check if the service is running
 memor query <text>                   Search memories from the CLI
 memor reingest                       Wipe DB and re-ingest everything
 memor reingest --project <name>      Re-ingest only one project
@@ -156,16 +182,17 @@ memor/
 +-- feedback.py           Implicit feedback analyzer (usage detection)
 |
 +-- retrieve/
-|   +-- retriever.py      Hybrid scoring: similarity + recency + kind + quality
+|   +-- retriever.py      Hybrid retrieval (dense + BM25, RRF) + relevance gate + scoring
 |
 +-- store/
-|   +-- sqlite_store.py   SQLite + sqlite-vec (WAL mode, dimension safety)
+|   +-- sqlite_store.py   SQLite + sqlite-vec + FTS5 (WAL mode, dimension safety)
 |
 +-- embed/
 |   +-- local.py          model2vec (potion-base-8M, 256-dim, ~60MB)
 |   +-- api.py            OpenAI-compatible embedding API (optional)
 |   +-- fake.py           Deterministic SHA-256 embedder (tests)
 |
++-- service.py            Background service management (launchd/systemd)
 +-- dashboard/
 |   +-- server.py         FastAPI dashboard backend
 |   +-- static/index.html Self-contained dashboard (no CDN deps)
@@ -190,7 +217,7 @@ skill/recall.py            Standalone recall script
 **Nothing leaves your machine.** In the default configuration:
 
 - **No telemetry, no analytics, no phone-home.** Zero outbound network calls.
-- **Embeddings run locally** via model2vec ONNX (one-time model download from HuggingFace — no user data sent).
+- **Embeddings run locally** via model2vec static token embeddings — no inference runtime, no GPU (one-time model download from HuggingFace — no user data sent).
 - **Hook transport is a Unix socket** (`~/.memor/hook.sock`), not a network port.
 - **Dashboard binds localhost only.**
 
@@ -226,7 +253,7 @@ cd memor-ai
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 
-pytest  # 153 tests
+pytest  # 179 tests
 ```
 
 ---

memor_cli-0.3.0/memor/__init__.py

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

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

@@ -410,9 +410,9 @@
             <div class="side-stat-sub" id="e-avg-input-sub">across all sessions</div>
           </div>
           <div class="side-stat">
-            <div class="side-stat-label">Recall Precision</div>
-            <div class="side-stat-value" id="e-precision">&ndash;</div>
-            <div class="side-stat-sub">% of prompts with relevant context</div>
+            <div class="side-stat-label">Recall Coverage</div>
+            <div class="side-stat-value" id="e-coverage">&ndash;</div>
+            <div class="side-stat-sub">% of prompts where context was injected</div>
           </div>
           <div class="side-stat">
             <div class="side-stat-label">Avg Latency</div>
@@ -581,7 +581,7 @@
 
   /* ── Efficiency ────────────────────────────────────────── */
   function renderEfficiency(data) {
-    document.getElementById('e-precision').textContent = fmtPct(data.precision * 100);
+    document.getElementById('e-coverage').textContent = fmtPct(data.coverage * 100);
   }
 
   function renderSessionEfficiency(data) {

{memor_cli-0.2.0 → memor_cli-0.3.0}/memor/eval/runner.py

@@ -72,7 +72,8 @@ def run_ablation(*, query, project, relevant_ids, store, embedder, k=8):
                      "ndcg@k": ndcg_at_k(ids, relevant_ids, k)}
     return out
 
-def run_contradiction_eval(*, query, project, stale_id, current_id, store, embedder, k=8):
-    r = Retriever(store, embedder, k=k, edge_expand=True)
+def run_contradiction_eval(*, query, project, stale_id, current_id, store, embedder,
+                           k=8, min_similarity=0.0):
+    r = Retriever(store, embedder, k=k, edge_expand=True, min_similarity=min_similarity)
     ids = [h.artifact.id for h in r.query(query, Scope(project=project)).hits]
     return (current_id in ids) and (stale_id not in ids)

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

@@ -5,10 +5,13 @@ if the agent's responses referenced recalled content. Updates memory_quality
 scores accordingly."""
 from __future__ import annotations
 import json
+import math
 from pathlib import Path
 from memor.store.sqlite_store import SqliteStore
 
-MIN_OVERLAP_TOKENS = 5
+_NGRAM_SIZE = 3
+_MIN_WORDS = 4
+_MATCH_RATIO = 0.10
 
 
 def _extract_assistant_texts(transcript_path: Path) -> list[str]:
@@ -36,44 +39,46 @@ def _extract_assistant_texts(transcript_path: Path) -> list[str]:
 
 def _text_was_used(memory_text: str, assistant_texts: list[str]) -> bool:
     words = memory_text.lower().split()
-    if len(words) < MIN_OVERLAP_TOKENS:
+    if len(words) < _MIN_WORDS:
         return False
-    key_phrases = []
-    for i in range(0, len(words) - 4):
-        key_phrases.append(" ".join(words[i:i+5]))
-    if not key_phrases:
+    ngrams = []
+    for i in range(len(words) - _NGRAM_SIZE + 1):
+        ngrams.append(" ".join(words[i:i + _NGRAM_SIZE]))
+    if not ngrams:
         return False
     matches = 0
-    for phrase in key_phrases:
+    for phrase in ngrams:
         for text in assistant_texts:
             if phrase in text:
                 matches += 1
                 break
-    return matches >= max(2, len(key_phrases) // 5)
+    return matches >= max(1, math.ceil(len(ngrams) * _MATCH_RATIO))
 
 
 def analyze_session_feedback(
     store: SqliteStore, session_id: str, transcript_path: Path
 ) -> int:
-    recalls = store.db.execute(
-        "SELECT * FROM recall_log WHERE session_id=? AND hits_count > 0",
-        (session_id,)
-    ).fetchall()
-    if not recalls:
-        return 0
-
     recalled_ids = set()
-    for r in recalls:
-        log_id = r["id"]
-        rl_time = r["timestamp"]
-        nearby = store.db.execute("""
-            SELECT q.artifact_id FROM memory_quality q
-            JOIN artifacts a ON a.id = q.artifact_id
-            WHERE q.last_recalled BETWEEN ? - 2 AND ? + 2
-              AND a.active = 1
-        """, (rl_time, rl_time)).fetchall()
-        for row in nearby:
-            recalled_ids.add(row["artifact_id"])
+    rows = store.db.execute("""
+        SELECT q.artifact_id FROM memory_quality q
+        JOIN artifacts a ON a.id = q.artifact_id
+        WHERE a.active = 1
+          AND a.project = (
+              SELECT project FROM recall_log
+              WHERE session_id = ? AND hits_count > 0
+              LIMIT 1
+          )
+          AND q.last_recalled >= (
+              SELECT MIN(timestamp) FROM recall_log
+              WHERE session_id = ? AND hits_count > 0
+          )
+          AND q.last_recalled <= (
+              SELECT MAX(timestamp) FROM recall_log
+              WHERE session_id = ? AND hits_count > 0
+          ) + 5
+    """, (session_id, session_id, session_id)).fetchall()
+    for row in rows:
+        recalled_ids.add(row["artifact_id"])
 
     if not recalled_ids:
         return 0

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

@@ -11,9 +11,18 @@ 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
 
 _UNSET = object()  # sentinel for "auto-discover embedder"
 
@@ -53,8 +62,46 @@ 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:
+        msg = "Memor: skipped — trivial prompt"
+        if Path(db_path).exists():
+            try:
+                from memor.store.sqlite_store import SqliteStore
+                store = SqliteStore(db_path, dim=embedder.dim)
+                store.log_recall(
+                    project=project, query_preview=query[:100],
+                    hits_count=0, top_score=0.0,
+                    tokens_injected=0, latency_ms=0.0,
+                    status="skipped_trivial", session_id=session_id)
+            except Exception:
+                pass
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": f"---\n{msg}",
+            }
+        }
+
+    try:
+        max_tokens = max(0, int(os.environ.get("MEMOR_MAX_TOKENS", "1500")))
+    except (ValueError, TypeError):
+        max_tokens = 1500
+    try:
+        min_similarity = float(os.environ.get("MEMOR_MIN_SIMILARITY", "0.0"))
+    except (ValueError, TypeError):
+        min_similarity = 0.0
+    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,
-                    session_id=session_id)
+                    max_tokens=max_tokens, min_similarity=min_similarity,
+                    exclude_ids=already_injected or None, session_id=session_id)
+
+    if session_id and result.hit_ids:
+        _session_injected.setdefault(session_id, set()).update(result.hit_ids)
+        if len(_session_injected) > _MAX_TRACKED_SESSIONS:
+            oldest = next(iter(_session_injected))
+            del _session_injected[oldest]
 
     if Path(db_path).exists():
         try:

{memor_cli-0.2.0 → memor_cli-0.3.0}/memor/recall.py

@@ -47,11 +47,31 @@ def _status_message(status: str, project: str, hits_count: int,
         return 'Memor: memory store is empty — run "memor daemon" to start ingesting sessions'
     if status == "no_embedder":
         return "Memor: inactive — run 'memor setup-model' to download the embedding model"
+    if status == "skipped_trivial":
+        return "Memor: skipped — trivial prompt"
     return f"Memor: status={status}"
 
 
+DEFAULT_MAX_TOKENS = 1500
+_TEXT_TRUNCATE_LEN = 600
+
+
+def _injected_token_count(artifact) -> int:
+    """Token cost of the text actually injected (after 600-char truncation)."""
+    if len(artifact.text) <= _TEXT_TRUNCATE_LEN:
+        return artifact.token_count
+    from memor.tokencount import count_tokens
+    return max(1, count_tokens(artifact.text[:_TEXT_TRUNCATE_LEN]))
+
+
+DEFAULT_MIN_SIMILARITY = 0.0
+
+
 def recall(query: str, project: str, db_path: str, *,
            embedder=None, k: int = 8, threshold: float = 0.3,
+           max_tokens: int = DEFAULT_MAX_TOKENS,
+           min_similarity: float = DEFAULT_MIN_SIMILARITY,
+           exclude_ids: set[str] | None = None,
            session_id: str = "") -> RecallResult:
     t0 = time.perf_counter()
 
@@ -67,16 +87,28 @@ def recall(query: str, project: str, db_path: str, *,
     from memor.retrieve.retriever import Retriever
 
     store = SqliteStore(db_path, dim=embedder.dim)
-    retriever = Retriever(store, embedder, k=k)
+    retriever = Retriever(store, embedder, k=k, min_similarity=min_similarity)
     trace = retriever.query(query, Scope(project=project))
 
     hits = list(trace.hits)
     if session_id:
         hits = [h for h in hits if h.artifact.meta.get("session_id") != session_id]
+    if exclude_ids:
+        hits = [h for h in hits if h.artifact.id not in exclude_ids]
     if threshold > 0.0:
         hits = [h for h in hits if h.score >= threshold]
+    if max_tokens > 0:
+        budget_hits = []
+        running = 0
+        for h in hits:
+            cost = _injected_token_count(h.artifact)
+            if running + cost > max_tokens and budget_hits:
+                break
+            budget_hits.append(h)
+            running += cost
+        hits = budget_hits
     top_score = hits[0].score if hits else 0.0
-    tokens = sum(h.artifact.token_count for h in hits)
+    tokens = sum(_injected_token_count(h.artifact) for h in hits)
 
     if not hits:
         status = "no_hits"
@@ -92,7 +124,7 @@ def recall(query: str, project: str, db_path: str, *,
         for i, h in enumerate(hits, 1):
             a = h.artifact
             kind_tag = a.meta.get("mem_type", a.kind)
-            text = a.text if len(a.text) <= 600 else a.text[:600] + "..."
+            text = a.text if len(a.text) <= _TEXT_TRUNCATE_LEN else a.text[:_TEXT_TRUNCATE_LEN] + "..."
             source_parts = []
             sid = a.meta.get("session_id")
             if sid: