runtime-memory 3.0.0__py3-none-any.whl

runtime_memory/hermes/tools.py

@@ -0,0 +1,230 @@
+"""Tool schemas exposed to Hermes, and their dispatch.
+
+Hermes wants OpenAI function-calling schemas (``name``/``description``/
+``parameters``), which is a different shape from memory-layer's MCP schemas, so
+these are declared here rather than converted. The set is deliberately small: the
+lifecycle hooks already handle recall and persistence, so the tools cover what the
+model must ask for explicitly - deliberate saves, targeted lookups, outcome
+feedback and a health check.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from runtime_memory.core.models import MemoryCategory, Outcome
+
+if TYPE_CHECKING:
+    from runtime_memory.hermes.provider import RuntimeMemoryProvider
+
+CATEGORIES = [category.value for category in MemoryCategory]
+OUTCOMES = [outcome.value for outcome in Outcome]
+
+REMEMBER = {
+    "name": "runtimememory_remember",
+    "description": (
+        "Save a durable fact to long-term memory: a convention, decision, "
+        "gotcha, command or preference worth recalling in a later session. "
+        "Do not use it for transient conversation detail."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "content": {
+                "type": "string",
+                "description": "The fact to store, written to stand alone.",
+            },
+            "category": {
+                "type": "string",
+                "enum": CATEGORIES,
+                "description": "Classification for the memory.",
+            },
+            "tags": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional tags for later filtering.",
+            },
+        },
+        "required": ["content", "category"],
+    },
+}
+
+RECALL = {
+    "name": "runtimememory_recall",
+    "description": (
+        "Search long-term memory for facts relevant to a query. Results are "
+        "ranked by relevance and by how well each memory has worked before."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to search for."},
+            "limit": {
+                "type": "integer",
+                "description": "Maximum memories to return (default 10).",
+                "minimum": 1,
+                "maximum": 50,
+            },
+            "category": {
+                "type": "string",
+                "enum": CATEGORIES,
+                "description": "Restrict results to one category.",
+            },
+        },
+        "required": ["query"],
+    },
+}
+
+OUTCOME = {
+    "name": "runtimememory_outcome",
+    "description": (
+        "Report whether recalled memories actually helped. Call it once you "
+        "know: 'worked' when the advice solved the problem, 'failed' when it "
+        "was wrong or misleading, 'partial' when it helped a little. This is "
+        "what teaches the store which memories to surface next time. With no "
+        "memory_ids, it applies to the memories recalled for this turn."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "outcome": {
+                "type": "string",
+                "enum": OUTCOMES,
+                "description": "How the recalled memories performed.",
+            },
+            "memory_ids": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Specific memories to score. Defaults to this turn's recall.",
+            },
+        },
+        "required": ["outcome"],
+    },
+}
+
+STATS = {
+    "name": "runtimememory_stats",
+    "description": "Report how many memories are stored and how they break down by category.",
+    "parameters": {"type": "object", "properties": {}},
+}
+
+TOOL_SCHEMAS: list[dict[str, Any]] = [REMEMBER, RECALL, OUTCOME, STATS]
+
+TOOL_NAMES = frozenset(schema["name"] for schema in TOOL_SCHEMAS)
+
+
+def dispatch(provider: RuntimeMemoryProvider, tool_name: str, args: dict[str, Any]) -> str:
+    """Route one tool call to the provider and serialize the result.
+
+    Args:
+        provider: The provider handling the call.
+        tool_name: Which tool the model invoked.
+        args: The model's arguments.
+
+    Returns:
+        A JSON string, per the Hermes tool contract. Errors are returned as
+        ``{"error": ...}`` rather than raised, so a bad call costs a turn instead
+        of the session.
+    """
+    handlers = {
+        REMEMBER["name"]: _remember,
+        RECALL["name"]: _recall,
+        OUTCOME["name"]: _outcome,
+        STATS["name"]: _stats,
+    }
+    handler = handlers.get(tool_name)
+    if handler is None:
+        return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    try:
+        return json.dumps(handler(provider, args), ensure_ascii=False, default=str)
+    except Exception as exc:  # surface the failure to the model, not the user
+        return json.dumps({"error": str(exc)})
+
+
+def _remember(provider: RuntimeMemoryProvider, args: dict[str, Any]) -> dict[str, Any]:
+    content = (args.get("content") or "").strip()
+    if not content:
+        return {"error": "content is required"}
+
+    raw_category = args.get("category") or MemoryCategory.GENERAL.value
+    try:
+        category = MemoryCategory(raw_category)
+    except ValueError:
+        return {"error": f"Unknown category '{raw_category}'. Valid: {CATEGORIES}"}
+
+    memory = provider.remember(content=content, category=category, tags=args.get("tags") or [])
+    return {
+        "stored": True,
+        "memory_id": memory.id,
+        "category": memory.category.value,
+        "project": memory.project,
+    }
+
+
+def _recall(provider: RuntimeMemoryProvider, args: dict[str, Any]) -> dict[str, Any]:
+    query = (args.get("query") or "").strip()
+    if not query:
+        return {"error": "query is required"}
+
+    raw_category = args.get("category")
+    category = None
+    if raw_category:
+        try:
+            category = MemoryCategory(raw_category)
+        except ValueError:
+            return {"error": f"Unknown category '{raw_category}'. Valid: {CATEGORIES}"}
+
+    limit = args.get("limit") or 10
+    results = provider.recall(query=query, limit=int(limit), category=category)
+    return {
+        "count": len(results),
+        "memories": [
+            {
+                "id": r.memory.id,
+                "content": r.memory.content,
+                "category": r.memory.category.value,
+                "score": round(r.score, 3),
+                "outcome_score": round(r.memory.outcome_score, 3),
+            }
+            for r in results
+        ],
+    }
+
+
+def _outcome(provider: RuntimeMemoryProvider, args: dict[str, Any]) -> dict[str, Any]:
+    raw_outcome = args.get("outcome")
+    try:
+        outcome = Outcome(raw_outcome)
+    except ValueError:
+        return {"error": f"Unknown outcome '{raw_outcome}'. Valid: {OUTCOMES}"}
+
+    memory_ids = args.get("memory_ids")
+    updated = provider.record_outcome(outcome=outcome, memory_ids=memory_ids)
+    if not updated:
+        return {
+            "recorded": False,
+            "reason": "No memories to score - none were recalled this turn.",
+        }
+    return {
+        "recorded": True,
+        "outcome": outcome.value,
+        "updated": [
+            {"id": memory.id, "outcome_score": round(memory.outcome_score, 3)} for memory in updated
+        ],
+    }
+
+
+def _stats(provider: RuntimeMemoryProvider, args: dict[str, Any]) -> dict[str, Any]:
+    storage = provider.stats().storage_stats
+    return {
+        "total_memories": storage.total_memories,
+        "active_memories": storage.active_memories,
+        "avg_outcome_score": round(storage.avg_outcome_score, 3),
+        "total_uses": storage.total_uses,
+        "by_category": {
+            key.value if hasattr(key, "value") else str(key): count
+            for key, count in storage.by_category.items()
+        },
+    }

runtime_memory/hermes/trace.py

@@ -0,0 +1,177 @@
+"""Retrieval and outcome tracing for the Hermes provider.
+
+This is the instrumentation the Tier 3 evaluation runs on. Every recall writes
+one JSONL record naming the memories it injected and their scores; every recorded
+outcome writes another naming the memories it credited or blamed. Joining the two
+on ``turn_id`` reconstructs, per turn, what was retrieved and whether it helped -
+which is the measurement the outcome-learning claim needs.
+
+Tracing is off unless a path is configured, and a broken trace never breaks a
+turn: writes are best-effort and failures are logged once.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from runtime_memory.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+TRACE_ENV_VAR = "RUNTIME_MEMORY_HERMES_TRACE"
+"""Environment variable holding the trace file path. Unset disables tracing."""
+
+
+class TraceWriter:
+    """Append-only JSONL writer for retrieval and outcome events."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        """Initialize the writer.
+
+        Args:
+            path: Trace file path. Falls back to ``RUNTIME_MEMORY_HERMES_TRACE``;
+                tracing is disabled when neither is set.
+        """
+        raw = path or os.environ.get(TRACE_ENV_VAR)
+        self._path = Path(raw).expanduser() if raw else None
+        self._lock = threading.Lock()
+        self._warned = False
+
+        if self._path is not None:
+            try:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+            except OSError as exc:
+                logger.warning(f"Trace directory unavailable ({exc}); tracing off")
+                self._path = None
+
+    @property
+    def enabled(self) -> bool:
+        """Whether events are being written anywhere."""
+        return self._path is not None
+
+    @property
+    def path(self) -> Path | None:
+        """The trace file path, or None when tracing is off."""
+        return self._path
+
+    def recall(
+        self,
+        *,
+        turn_id: str,
+        session_id: str,
+        query: str,
+        results: list[Any],
+        project: str | None,
+        latency_ms: float,
+    ) -> None:
+        """Record what a recall injected.
+
+        Args:
+            turn_id: Identifier joining this recall to any later outcome.
+            session_id: Hermes session the recall belongs to.
+            query: The query text used for retrieval.
+            results: ``SearchResult`` objects that were injected.
+            project: Project filter in force, if any.
+            latency_ms: Wall-clock retrieval time.
+        """
+        self._write(
+            {
+                "event": "recall",
+                "turn_id": turn_id,
+                "session_id": session_id,
+                "query": query,
+                "project": project,
+                "latency_ms": round(latency_ms, 2),
+                "retrieved": [
+                    {
+                        "memory_id": r.memory.id,
+                        "category": r.memory.category.value,
+                        "score": round(r.score, 4),
+                        "semantic_score": round(r.semantic_score, 4),
+                        "outcome_score": round(r.memory.outcome_score, 4),
+                        "use_count": r.memory.use_count,
+                    }
+                    for r in results
+                ],
+            }
+        )
+
+    def outcome(
+        self,
+        *,
+        turn_id: str,
+        session_id: str,
+        outcome: str,
+        memory_ids: list[str],
+        origin: str,
+    ) -> None:
+        """Record an outcome applied to memories.
+
+        Args:
+            turn_id: The turn the outcome is attributed to.
+            session_id: Hermes session the outcome came from.
+            outcome: ``worked``, ``failed`` or ``partial``.
+            memory_ids: Memories the score change was applied to.
+            origin: What produced the outcome, e.g. ``tool`` or ``auto``.
+        """
+        self._write(
+            {
+                "event": "outcome",
+                "turn_id": turn_id,
+                "session_id": session_id,
+                "outcome": outcome,
+                "memory_ids": memory_ids,
+                "origin": origin,
+            }
+        )
+
+    def write_turn(
+        self,
+        *,
+        turn_id: str,
+        session_id: str,
+        memory_ids: list[str],
+        kind: str,
+        count: int | None = None,
+    ) -> None:
+        """Record memories created from a conversation turn.
+
+        Args:
+            turn_id: The turn the write belongs to.
+            session_id: Hermes session that produced it.
+            memory_ids: Ids written, where the caller knows them.
+            kind: What produced the write, e.g. ``tool`` or ``extraction``.
+            count: How many memories were written. Defaults to ``len(memory_ids)``;
+                pass it explicitly when the ids are not available.
+        """
+        self._write(
+            {
+                "event": "write",
+                "turn_id": turn_id,
+                "session_id": session_id,
+                "kind": kind,
+                "memory_ids": memory_ids,
+                "count": len(memory_ids) if count is None else count,
+            }
+        )
+
+    def _write(self, record: dict[str, Any]) -> None:
+        """Append one record, swallowing and logging any failure."""
+        if self._path is None:
+            return
+
+        record["ts"] = datetime.now(UTC).isoformat()
+        line = json.dumps(record, ensure_ascii=False, default=str)
+
+        try:
+            with self._lock, self._path.open("a", encoding="utf-8") as handle:
+                handle.write(line + "\n")
+        except OSError as exc:
+            if not self._warned:
+                logger.warning(f"Trace write failed ({exc}); further errors muted")
+                self._warned = True