runtime-memory 3.0.0__tar.gz → 3.1.0__tar.gz

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runtime-memory
-Version: 3.0.0
+Version: 3.1.0
 Summary: Persistent memory for AI coding agents with outcome-based learning
 Project-URL: Homepage, https://github.com/runtimenoteslabs/memory-layer
 Project-URL: Documentation, https://github.com/runtimenoteslabs/memory-layer#readme

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/src/runtime_memory/__init__.py

@@ -10,7 +10,7 @@ This package provides:
 
 from __future__ import annotations
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 __author__ = "exitcode42"
 
 from runtime_memory.core.legacy_env import apply_legacy_env

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/src/runtime_memory/core/config.py

@@ -92,8 +92,13 @@ class EmbeddingConfig(BaseModel):
     )
 
 
-class RetrievalConfig(BaseModel):
-    """Retrieval system configuration."""
+class RetrievalSettings(BaseModel):
+    """Retrieval weights as settings.
+
+    Named apart from ``RetrievalConfig`` in core/retrieval.py, which is what
+    actually scores a search. Two classes sharing one name is how the shipped
+    weights drifted from the documented ones without anyone noticing.
+    """
 
     semantic_weight: float = Field(
         default=0.35,
@@ -174,7 +179,7 @@ class ExtractionConfig(BaseModel):
     """LLM extraction configuration."""
 
     model: str = Field(
-        default="claude-3-haiku-20240307",
+        default="claude-haiku-4-5",
         description="LLM model for extraction",
     )
     max_tokens: int = Field(
@@ -280,7 +285,7 @@ class Settings(BaseSettings):
     # Component configs
     database: DatabaseConfig = Field(default_factory=DatabaseConfig)
     embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
-    retrieval: RetrievalConfig = Field(default_factory=RetrievalConfig)
+    retrieval: RetrievalSettings = Field(default_factory=RetrievalSettings)
     server: ServerConfig = Field(default_factory=ServerConfig)
     extraction: ExtractionConfig = Field(default_factory=ExtractionConfig)
     logging: LoggingConfig = Field(default_factory=LoggingConfig)

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/src/runtime_memory/core/retrieval.py

@@ -12,11 +12,12 @@ Provides intelligent memory retrieval with:
 from __future__ import annotations
 
 import math
+import os
 import re
 from collections import Counter
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
-from typing import ClassVar
+from typing import Any, ClassVar
 
 from runtime_memory.core.embeddings import EmbeddingProvider  # noqa: TC001
 from runtime_memory.core.logging import get_logger
@@ -32,11 +33,15 @@ EmbeddingVector = list[float]
 class RetrievalConfig:
     """Configuration for the retrieval system."""
 
-    # Scoring weights (should sum to 1.0 for normalized scoring)
-    semantic_weight: float = 0.5
-    recency_weight: float = 0.25
+    # Scoring weights. These are the five signals the README and the design
+    # notes document, and they sum to 1.0. RetrievalSettings in core/config.py
+    # carries the same numbers for settings-file configuration; a test asserts
+    # the two agree, because they silently disagreed once.
+    semantic_weight: float = 0.35
+    outcome_weight: float = 0.25
+    recency_weight: float = 0.15
     frequency_weight: float = 0.15
-    outcome_weight: float = 0.1
+    confidence_weight: float = 0.10
 
     # BM25 parameters
     bm25_k1: float = 1.5  # Term frequency saturation
@@ -53,6 +58,28 @@ class RetrievalConfig:
     frequency_log_base: float = 2.0  # Log base for frequency scaling
     max_frequency_boost: float = 2.0  # Maximum frequency boost
 
+    # Whether a memory's outcome record limits its frequency boost. Off by
+    # default, which scores exactly as before. Retrieval counts as use, so a
+    # memory that keeps being retrieved keeps gaining frequency even while every
+    # outcome recorded against it is a failure, and once its outcome score is at
+    # the floor of -1.0 further failures cost it nothing. With this on, the
+    # frequency score is scaled by 1 + outcome_score, clamped to [0, 1]: a memory
+    # at or above zero is untouched and a memory at the floor gets no boost.
+    outcome_gates_frequency: bool = False
+
+    # Two-stage retrieval. None, the default, scores exactly as before: every
+    # candidate competes on the full score, of which only the semantic signal
+    # depends on the query, so category boost, outcome and frequency can seat a
+    # memory that barely matches the query above one that matches it well. The
+    # Tier 2 evaluation found a gotcha ranked 25th of 38 on relevance injected
+    # first. Set to a factor of at least 1.0, a search first keeps the
+    # ceil(limit x factor) candidates with the highest semantic score, dropping
+    # any with none at all, and only that pool competes on the full score. The
+    # other signals then choose among relevant memories rather than decide
+    # whether an unrelated one gets in. At 1.0 they can only reorder; above it
+    # they can replace a relevant memory that keeps failing with the next one.
+    relevance_pool_factor: float | None = None
+
     # Category boosting
     category_boosts: dict[MemoryCategory, float] = field(default_factory=dict)
 
@@ -62,7 +89,16 @@ class RetrievalConfig:
     dedup_threshold: float = 0.95  # Similarity threshold for deduplication
 
     def __post_init__(self) -> None:
-        """Set default category boosts if not provided."""
+        """Set default category boosts if not provided, and check the pool factor.
+
+        Raises:
+            ValueError: If ``relevance_pool_factor`` is below 1.0, which would make
+                the pool smaller than the limit it is meant to fill.
+        """
+        if self.relevance_pool_factor is not None and self.relevance_pool_factor < 1.0:
+            raise ValueError(
+                f"relevance_pool_factor must be at least 1.0, got {self.relevance_pool_factor}"
+            )
         if not self.category_boosts:
             self.category_boosts = {
                 MemoryCategory.GOTCHA: 1.3,  # Boost gotchas (important warnings)
@@ -76,6 +112,34 @@ class RetrievalConfig:
                 MemoryCategory.COMMAND: 0.9,
             }
 
+    @classmethod
+    def from_env(cls, **overrides: Any) -> RetrievalConfig:
+        """Build a config, letting the environment override any signal weight.
+
+        Reads ``RUNTIME_MEMORY_SEMANTIC_WEIGHT`` and the matching names for
+        outcome, recency, frequency and confidence. Weights are applied as
+        given, never renormalised: an ablation that zeroes one signal should
+        leave the others exactly where they were, not silently reweight them.
+        ``RUNTIME_MEMORY_RELEVANCE_POOL_FACTOR`` turns on two-stage retrieval;
+        unset or empty leaves it off.
+
+        Args:
+            **overrides: Field values that win over both defaults and env.
+
+        Returns:
+            A config with any environment overrides applied.
+        """
+        values: dict[str, Any] = {}
+        for signal in ("semantic", "outcome", "recency", "frequency", "confidence"):
+            raw = os.environ.get(f"RUNTIME_MEMORY_{signal.upper()}_WEIGHT")
+            if raw is not None:
+                values[f"{signal}_weight"] = float(raw)
+        pool = os.environ.get("RUNTIME_MEMORY_RELEVANCE_POOL_FACTOR", "").strip()
+        if pool:
+            values["relevance_pool_factor"] = float(pool)
+        values.update(overrides)
+        return cls(**values)
+
 
 class BM25Index:
     """BM25 index for text search.
@@ -268,9 +332,10 @@ class HybridRetriever:
 
     Implements the scoring formula:
     final_score = (semantic_weight * semantic_score +
+                   outcome_weight * outcome_score +
                    recency_weight * recency_score +
                    frequency_weight * frequency_score +
-                   outcome_weight * outcome_score) * category_boost
+                   confidence_weight * confidence) * category_boost
     """
 
     def __init__(
@@ -396,11 +461,17 @@ class HybridRetriever:
             return []
 
         # Score all candidates
-        results: list[SearchResult] = []
-        for memory in candidates:
-            result = self._score_memory(memory, query, query_embedding)
-            if result.score >= min_score:
-                results.append(result)
+        results = [
+            self._score_memory(memory, query, query_embedding) for memory in candidates
+        ]
+
+        # See RetrievalConfig.relevance_pool_factor. Relevance is decided before
+        # min_score, so a relevant memory with a poor record is not replaced in
+        # the pool by a less relevant one that happens to clear the threshold.
+        if self.config.relevance_pool_factor is not None:
+            results = self._relevance_pool(results, limit)
+
+        results = [result for result in results if result.score >= min_score]
 
         # Sort by score descending
         results.sort(key=lambda r: r.score, reverse=True)
@@ -410,6 +481,23 @@ class HybridRetriever:
 
         return results[:limit]
 
+    def _relevance_pool(self, results: list[SearchResult], limit: int) -> list[SearchResult]:
+        """Keep the candidates most relevant to the query, the first retrieval stage.
+
+        Args:
+            results: Scored candidates.
+            limit: The number of results the search will return.
+
+        Returns:
+            Up to ``ceil(limit x relevance_pool_factor)`` results with a semantic
+            score above zero, most relevant first.
+        """
+        factor = self.config.relevance_pool_factor or 1.0
+        size = math.ceil(limit * factor)
+        relevant = [result for result in results if result.semantic_score > 0]
+        relevant.sort(key=lambda r: r.semantic_score, reverse=True)
+        return relevant[:size]
+
     def _get_candidates(
         self,
         category: MemoryCategory | None = None,
@@ -468,15 +556,19 @@ class HybridRetriever:
         # Get outcome score (already in -1 to 1 range, normalize to 0-1)
         outcome_score = (memory.outcome_score + 1.0) / 2.0
 
+        # Extraction confidence, already 0-1
+        confidence_score = memory.confidence
+
         # Get category boost
         category_boost = self.config.category_boosts.get(memory.category, 1.0)
 
         # Calculate final weighted score
         final_score = (
             self.config.semantic_weight * semantic_score
+            + self.config.outcome_weight * outcome_score
             + self.config.recency_weight * recency_score
             + self.config.frequency_weight * frequency_score
-            + self.config.outcome_weight * outcome_score
+            + self.config.confidence_weight * confidence_score
         ) * category_boost
 
         return SearchResult(
@@ -577,6 +669,11 @@ class HybridRetriever:
         max_expected = math.log(1 + 100, log_base)
         normalized = min(score / max_expected, 1.0)
 
+        # See RetrievalConfig.outcome_gates_frequency. Without the gate, being
+        # retrieved pays the same whether the memory helped or kept failing.
+        if self.config.outcome_gates_frequency:
+            normalized *= min(1.0, max(0.0, 1.0 + memory.outcome_score))
+
         return normalized
 
     def _deduplicate(self, results: list[SearchResult]) -> list[SearchResult]:

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/src/runtime_memory/extraction/extractor.py

@@ -317,14 +317,25 @@ class ExtractionConfig:
     """Configuration for the extraction pipeline."""
 
     # LLM settings
-    model: str = "claude-sonnet-4-20250514"
-    """Model to use for extraction."""
+    model: str = "claude-sonnet-5"
+    """Model to use for extraction.
+
+    Extraction is a bulk structured-output task, so it runs on a cheaper model
+    than a reasoning workload would. Claude 4.x ids still resolve today but are
+    a generation behind and will eventually retire.
+    """
 
     max_tokens: int = 4096
     """Maximum tokens in response."""
 
     temperature: float = 0.1
-    """Temperature for generation (low for consistency)."""
+    """Ignored since the move to Claude 5.
+
+    ``temperature`` was removed on Claude 4.6 and later and the API rejects it
+    with a 400. The field stays so existing configuration keeps loading, and it
+    records the original intent of deterministic extraction, but it is no longer
+    sent. Determinism now comes from the prompt and the schema.
+    """
 
     # Rate limiting
     rate_limit_rpm: int = 50
@@ -701,10 +712,11 @@ class MemoryExtractor:
         await self._rate_limiter.acquire(estimated_tokens)
 
         client = self._get_client()
+        # No temperature: the parameter was removed on Claude 4.6 and later and
+        # sending it returns a 400.
         response = await client.messages.create(
             model=self.config.model,
             max_tokens=self.config.max_tokens,
-            temperature=self.config.temperature,
             system=system_prompt,
             messages=[{"role": "user", "content": user_prompt}],
         )

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/src/runtime_memory/hermes/provider.py

@@ -1,4 +1,4 @@
-"""memory-layer as a Hermes Agent memory provider.
+"""runtime-memory as a Hermes Agent memory provider.
 
 Hermes discovers this through the ``hermes_agent.memory_providers`` entry point
 and activates it with ``memory.provider: runtimememory``. Once active it replaces
@@ -37,6 +37,8 @@ from runtime_memory.core.models import (
     MemorySource,
     Outcome,
 )
+from runtime_memory.core.paths import default_db_path
+from runtime_memory.core.retrieval import RetrievalConfig
 from runtime_memory.hermes._base import (
     INDICATOR_GLYPH,
     MemoryProvider,
@@ -55,9 +57,10 @@ logger = get_logger(__name__)
 PROVIDER_NAME = "runtimememory"
 PROVIDER_LABEL = "Runtime Memory"
 
-DEFAULT_DB_PATH = "~/.memory-layer/memories.db"
 DEFAULT_RECALL_LIMIT = 8
 DEFAULT_MIN_SCORE = 0.0
+EXTRACTION_TIMEOUT = 180.0
+"""Seconds to wait for session-end extraction. It is one LLM round trip."""
 
 _WRITE_CONTEXTS = frozenset({"primary", ""})
 """Agent contexts allowed to write. Subagents, cron and flush runs read only."""
@@ -66,7 +69,7 @@ _MIRROR_CATEGORY = {
     "memory": MemoryCategory.CONTEXT,
     "user": MemoryCategory.PREFERENCE,
 }
-"""Hermes built-in write targets mapped onto memory-layer categories."""
+"""Hermes built-in write targets mapped onto Runtime Memory categories."""
 
 
 def _env_flag(name: str, default: bool = False) -> bool:
@@ -77,6 +80,48 @@ def _env_flag(name: str, default: bool = False) -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _extraction_unavailable_reason() -> str | None:
+    """Why session-end extraction cannot run, or None when it can.
+
+    Extraction needs a package and a credential, and the failure without either
+    is invisible: it happens on a background task at session end, where the
+    exception is swallowed so a lost extraction never takes a session with it.
+    A provider that reports extraction as on while nothing is ever extracted is
+    worse than one that refuses, so the check happens once at startup where it
+    can still be said out loud.
+
+    An unset ``ANTHROPIC_API_KEY`` does not mean there is no credential. The SDK
+    also accepts an auth token, a signed-in profile on disk, and workload
+    identity federation, so each documented source is checked before refusing.
+
+    Returns:
+        A reason to show the operator, or None when extraction is usable.
+    """
+    try:
+        import anthropic  # noqa: PLC0415
+    except ImportError:
+        return "the anthropic package is not installed (pip install 'runtime-memory[extraction]')"
+
+    # Let the SDK apply its own precedence to the environment rather than
+    # reimplementing it. Construction does not raise when nothing resolves.
+    try:
+        client = anthropic.AsyncAnthropic()
+        if getattr(client, "api_key", None) or getattr(client, "auth_token", None):
+            return None
+    except Exception:  # noqa: BLE001 - an unconstructable client is also a refusal
+        pass
+
+    if os.environ.get("ANTHROPIC_FEDERATION_RULE_ID"):
+        return None
+    if (Path.home() / ".config" / "anthropic").exists():
+        return None
+
+    return (
+        "no Anthropic credentials are configured (set ANTHROPIC_API_KEY, or sign "
+        "in with `ant auth login`)"
+    )
+
+
 def _embedding_provider_name() -> str:
     """Name the embedding backend for the engine to build.
 
@@ -90,7 +135,7 @@ def _embedding_provider_name() -> str:
 
 
 class RuntimeMemoryProvider(MemoryProvider):
-    """Hermes memory provider backed by a local memory-layer engine."""
+    """Hermes memory provider backed by a local Runtime Memory engine."""
 
     pre_compress_checkpoint_api_version = 1
 
@@ -101,7 +146,9 @@ class RuntimeMemoryProvider(MemoryProvider):
         self._project: str | None = None
         self._writes_allowed: bool = True
 
-        self._db_path: Path = Path(os.environ.get("RUNTIME_MEMORY_DB", DEFAULT_DB_PATH)).expanduser()
+        self._db_path: Path = Path(
+            os.environ.get("RUNTIME_MEMORY_DB") or default_db_path()
+        ).expanduser()
         self._recall_limit: int = int(
             os.environ.get("RUNTIME_MEMORY_RECALL_LIMIT", DEFAULT_RECALL_LIMIT)
         )
@@ -132,7 +179,7 @@ class RuntimeMemoryProvider(MemoryProvider):
             self._db_path.parent.mkdir(parents=True, exist_ok=True)
             return os.access(self._db_path.parent, os.W_OK)
         except OSError as exc:
-            logger.debug(f"memory-layer unavailable: {exc}")
+            logger.debug(f"Runtime Memory unavailable: {exc}")
             return False
 
     def unavailable_reason(self) -> str:
@@ -158,6 +205,14 @@ class RuntimeMemoryProvider(MemoryProvider):
         if not self._writes_allowed:
             logger.info(f"Read-only in '{agent_context}' context")
 
+        if self._extract_on_end:
+            reason = _extraction_unavailable_reason()
+            if reason:
+                logger.warning(
+                    f"Extraction at session end was requested but is off: {reason}"
+                )
+                self._extract_on_end = False
+
         workspace = kwargs.get("agent_workspace")
         self._project = os.environ.get("RUNTIME_MEMORY_PROJECT") or (
             Path(workspace).name if workspace else None
@@ -168,6 +223,10 @@ class RuntimeMemoryProvider(MemoryProvider):
             db_path=str(self._db_path),
             embedding_provider=_embedding_provider_name(),
             track_last_search=True,
+            # Signal weights come from the environment so an evaluation arm can
+            # ablate one, such as running with outcome weight 0 to separate a
+            # shared store from the learning on top of it.
+            retrieval_config=RetrievalConfig.from_env(),
         )
 
         engine = MemoryEngine(config=config)
@@ -180,7 +239,7 @@ class RuntimeMemoryProvider(MemoryProvider):
         spawn(self._warm(), label="warmup")
 
         logger.info(
-            f"memory-layer ready (db={self._db_path}, project={self._project}, "
+            f"Runtime Memory ready (db={self._db_path}, project={self._project}, "
             f"writes={'on' if self._writes_allowed else 'off'})"
         )
 
@@ -257,12 +316,12 @@ class RuntimeMemoryProvider(MemoryProvider):
             logger.warning(f"Recall failed: {exc}")
             return ""
 
-        if not results:
-            return ""
-
         self._last_ids = [r.memory.id for r in results]
         self._last_count = len(results)
 
+        # Traced even when nothing came back. A recall that found nothing and a
+        # recall that never happened look identical in an untraced run, and the
+        # difference is the whole question when a store is still filling up.
         self._trace.recall(
             turn_id=self._turn_id,
             session_id=session_id or self._session_id,
@@ -271,6 +330,9 @@ class RuntimeMemoryProvider(MemoryProvider):
             project=self._project,
             latency_ms=(time.perf_counter() - started) * 1000,
         )
+
+        if not results:
+            return ""
         return self._format(results)
 
     def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
@@ -361,7 +423,16 @@ class RuntimeMemoryProvider(MemoryProvider):
         if self._engine is None or not messages:
             return
         logger.info(f"Session end: extraction over {len(messages)} messages")
-        spawn(self._extract(messages), label="extraction")
+        # Blocking, not spawned. Hermes calls this hook and then immediately
+        # tears the provider down; in one-shot mode the process exits straight
+        # after. Fired and forgotten, the extraction never survived long enough
+        # to write anything, which looked exactly like extraction being off.
+        # Hermes documents this hook as LLM-bound and runs it on a background
+        # worker, so waiting here is what the contract expects.
+        try:
+            run_sync(self._extract(messages), timeout=EXTRACTION_TIMEOUT)
+        except Exception as exc:  # a lost extraction must not take the session with it
+            logger.warning(f"Extraction failed: {exc}")
 
     async def _extract(self, messages: list[dict[str, Any]]) -> None:
         """Run LLM extraction over a finished session.
@@ -499,7 +570,7 @@ class RuntimeMemoryProvider(MemoryProvider):
             {
                 "key": "db_path",
                 "description": "SQLite store shared with Claude Code and MCP clients",
-                "default": DEFAULT_DB_PATH,
+                "default": str(default_db_path()),
                 "env_var": "RUNTIME_MEMORY_DB",
                 "type": "text",
             },

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/tests/unit/test_config.py

@@ -12,7 +12,7 @@ from runtime_memory.core.config import (
     Environment,
     ExtractionConfig,
     LoggingConfig,
-    RetrievalConfig,
+    RetrievalSettings,
     ServerConfig,
     Settings,
     clear_settings_cache,
@@ -102,12 +102,12 @@ class TestEmbeddingConfig:
             EmbeddingConfig(cache_size=200000)
 
 
-class TestRetrievalConfig:
-    """Tests for RetrievalConfig."""
+class TestRetrievalSettings:
+    """Tests for RetrievalSettings."""
 
     def test_default_weights(self):
         """Test default retrieval weights sum to 1."""
-        config = RetrievalConfig()
+        config = RetrievalSettings()
         total = (
             config.semantic_weight
             + config.outcome_weight
@@ -120,16 +120,16 @@ class TestRetrievalConfig:
     def test_weight_validation(self):
         """Test weight validation."""
         with pytest.raises(ValueError):
-            RetrievalConfig(semantic_weight=-0.1)
+            RetrievalSettings(semantic_weight=-0.1)
         with pytest.raises(ValueError):
-            RetrievalConfig(semantic_weight=1.5)
+            RetrievalSettings(semantic_weight=1.5)
 
     def test_half_life_validation(self):
         """Test half life days validation."""
         with pytest.raises(ValueError):
-            RetrievalConfig(recency_half_life_days=0)
+            RetrievalSettings(recency_half_life_days=0)
         with pytest.raises(ValueError):
-            RetrievalConfig(recency_half_life_days=400)
+            RetrievalSettings(recency_half_life_days=400)
 
 
 class TestServerConfig:
@@ -206,7 +206,7 @@ class TestSettings:
         assert settings.env == Environment.DEVELOPMENT
         assert isinstance(settings.database, DatabaseConfig)
         assert isinstance(settings.embedding, EmbeddingConfig)
-        assert isinstance(settings.retrieval, RetrievalConfig)
+        assert isinstance(settings.retrieval, RetrievalSettings)
         assert isinstance(settings.server, ServerConfig)
 
     def test_for_testing(self):

{runtime_memory-3.0.0 → runtime_memory-3.1.0}/tests/unit/test_extractor.py

@@ -30,7 +30,7 @@ class TestExtractionConfig:
     def test_default_config(self) -> None:
         """Test default configuration values."""
         config = ExtractionConfig()
-        assert config.model == "claude-sonnet-4-20250514"
+        assert config.model == "claude-sonnet-5"
         assert config.max_tokens == 4096
         assert config.temperature == 0.1
         assert config.rate_limit_rpm == 50