Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
refactor(proxy): drop the test-only memory ranker and file-backed native memory ops (#4072)
Tejas Choprafc5ac70b4a1e
diff --git a/headroom/proxy/memory_handler.py b/headroom/proxy/memory_handler.pyindex 9b245c51f..03aeab7a1 100644--- a/headroom/proxy/memory_handler.py+++ b/headroom/proxy/memory_handler.py@@ -718,7 +718,6 @@ class MemoryHandler:messages: list[dict[str, Any]],request_context: RequestContext | None = None,*,- ranker: Any | None = None,query: Any | None = None,budget: Any | None = None,) -> str | None:@@ -736,14 +735,6 @@ class MemoryHandler:omitted, behaves as before this fix — single-bucket searchagainst the legacy backend. Production handlers alwayspass it; tests / mocks can keep the simpler call shape.- ranker: Optional :class:`~headroom.proxy.memory_ranker.MemoryRanker`- — re-ranks the backend's cosine-only candidates by an- additional signal (recency, source, access count, …).- When ``None`` (default), behaviour is pure cosine +- ``budget.min_similarity`` floor. When provided, candidates- are adapted to :class:`MemoryCandidate`, re-ranked, then- re-filtered by ``budget.min_similarity`` on the boosted- score.query: Optional :class:`MemoryQuery` — multi-source, full-fidelity retrieval query. When provided, takes precedenceover the ``messages``-derived query. Constructed at the@@ -754,8 +745,7 @@ class MemoryHandler:returned formatted block by tokens / entries / minsimilarity. When ``None``, defaults are taken from``self.config`` so the existing top_k / min_similarity- contract is preserved. Both the no-ranker and the with-- ranker paths honour the same budget.+ contract is preserved.Returns:Formatted context string, or None if no relevant memories.@@ -848,71 +838,34 @@ class MemoryHandler:)return None- # Optional re-rank: when a MemoryRanker is provided, adapt- # results to MemoryCandidate, re-rank, then filter by- # ``budget.min_similarity`` on the BOOSTED score. The re-rank- # can promote a fresh weak-cosine memory above a stale- # strong-cosine one (RecencyBoostRanker default behaviour).- # Cap by ``budget.max_entries`` after filtering so the budget- # contract is honoured on both branches.+ # Pure cosine + budget min_similarity floor.# Each rendered row carries the memory ID in [brackets] so# the model can address it directly via memory_update /# memory_delete without round-tripping through memory_search.- # Both branches below render the same `i. [id] content` shape- # so the format is stable regardless of whether a ranker is- # in play.selected_memory_ids: list[str] = []- if ranker is not None:- from headroom.proxy.memory_ranker import MemoryCandidate-- candidates = [MemoryCandidate.from_backend_result(r) for r in results]- ranked = ranker.rank(candidates)- # Filter on the post-rank score (the ranker may have- # boosted or attenuated original cosine values).- ranked = [c for c in ranked if c.score >= effective_budget.min_similarity]- if not ranked:- logger.debug(- f"Memory: {len(results)} memories found but none above threshold "- f"{effective_budget.min_similarity} after re-rank"- )- return None- ranked = ranked[: effective_budget.max_entries]- memory_lines = []- for i, candidate in enumerate(ranked, 1):- memory_id = candidate.id or "?"- if candidate.id:- selected_memory_ids.append(candidate.id)- memory_lines.append(f"{i}. [{memory_id}] {candidate.content}")- if candidate.related_entities:- entities_str = ", ".join(candidate.related_entities[:3])- memory_lines.append(f" (Related: {entities_str})")- else:- # No ranker: pure cosine + budget min_similarity floor.- filtered_results = [- r for r in results if r.score >= effective_budget.min_similarity- ]+ filtered_results = [r for r in results if r.score >= effective_budget.min_similarity]- if not filtered_results:- logger.debug(- f"Memory: {len(results)} memories found but none above threshold "- f"{effective_budget.min_similarity}"- )- return None-- # Cap entry count via the budget (defence-in-depth —- # backend already gets top_k=max_entries but this enforces- # it on post-filter results too).- filtered_results = filtered_results[: effective_budget.max_entries]-- memory_lines = []- for i, result in enumerate(filtered_results, 1):- memory_id = getattr(result.memory, "id", None) or "?"- if memory_id != "?":- selected_memory_ids.append(memory_id)- memory_lines.append(f"{i}. [{memory_id}] {result.memory.content}")- if hasattr(result, "related_entities") and result.related_entities:- entities_str = ", ".join(result.related_entities[:3])- memory_lines.append(f" (Related: {entities_str})")+ if not filtered_results:+ logger.debug(+ f"Memory: {len(results)} memories found but none above threshold "+ f"{effective_budget.min_similarity}"+ )+ return None++ # Cap entry count via the budget (defence-in-depth —+ # backend already gets top_k=max_entries but this enforces+ # it on post-filter results too).+ filtered_results = filtered_results[: effective_budget.max_entries]++ memory_lines = []+ for i, result in enumerate(filtered_results, 1):+ memory_id = getattr(result.memory, "id", None) or "?"+ if memory_id != "?":+ selected_memory_ids.append(memory_id)+ memory_lines.append(f"{i}. [{memory_id}] {result.memory.content}")+ if hasattr(result, "related_entities") and result.related_entities:+ entities_str = ", ".join(result.related_entities[:3])+ memory_lines.append(f" (Related: {entities_str})")except Exception as e:logger.warning(f"Memory: Search failed for user {effective_user_id}: {e}")@@ -1617,269 +1570,6 @@ your responses, not to drive new actions."""logger.error(f"Memory: Native tool error: {e}")return f"Error: {e}"- def _resolve_native_path(self, path: str, user_id: str) -> Path:- """Resolve path within user's memory directory safely.-- Prevents path traversal attacks by ensuring path stays within- the user's memory directory.- """- assert self._native_memory_dir is not None-- # User-scoped memory directory- user_dir = self._native_memory_dir / user_id- user_dir.mkdir(parents=True, exist_ok=True)-- # Normalize path (remove /memories prefix if present)- if path.startswith("/memories"):- path = path[len("/memories") :]- if path.startswith("/"):- path = path[1:]-- # Resolve and validate- resolved = (user_dir / path).resolve()-- # Security: ensure path is within user directory- try:- resolved.relative_to(user_dir.resolve())- except ValueError:- raise ValueError(f"Path traversal detected: {path}") from None-- return resolved-- def _native_view(self, input_data: dict[str, Any], user_id: str) -> str:- """View directory contents or file contents."""- path = input_data.get("path", "/memories")- view_range = input_data.get("view_range")-- resolved = self._resolve_native_path(path, user_id)-- if not resolved.exists():- return f"The path {path} does not exist. Please provide a valid path."-- if resolved.is_dir():- # List directory contents- lines = [- f"Here're the files and directories up to 2 levels deep in {path}, "- "excluding hidden items and node_modules:"- ]-- def get_size(p: Path) -> str:- if p.is_file():- size = p.stat().st_size- if size < 1024:- return f"{size}B"- elif size < 1024 * 1024:- return f"{size / 1024:.1f}K"- else:- return f"{size / (1024 * 1024):.1f}M"- return "4.0K" # Default for directories-- def list_recursive(p: Path, rel_path: str, depth: int) -> None:- if depth > 2:- return- if p.name.startswith(".") or p.name == "node_modules":- return-- lines.append(f"{get_size(p)}\t{rel_path}")-- if p.is_dir() and depth < 2:- try:- for child in sorted(p.iterdir()):- child_rel = (- f"{rel_path}/{child.name}"- if rel_path != path- else f"{path}/{child.name}"- )- list_recursive(child, child_rel, depth + 1)- except PermissionError:- pass-- list_recursive(resolved, path, 0)- return "\n".join(lines)-- else:- # Read file contents with line numbers- try:- content = resolved.read_text(encoding="utf-8")- except UnicodeDecodeError:- content = resolved.read_text(encoding="latin-1")-- lines_content = content.split("\n")-- if len(lines_content) > 999999:- return f"File {path} exceeds maximum line limit of 999,999 lines."-- # Apply view_range if specified- start_line = 1- end_line = len(lines_content)- if view_range and len(view_range) >= 2:- start_line = max(1, view_range[0])- end_line = min(len(lines_content), view_range[1])-- result_lines = [f"Here's the content of {path} with line numbers:"]- for i, line in enumerate(lines_content[start_line - 1 : end_line], start=start_line):- result_lines.append(f"{i:6d}\t{line}")-- return "\n".join(result_lines)-- def _native_create(self, input_data: dict[str, Any], user_id: str) -> str:- """Create a new file."""- path = input_data.get("path", "")- file_text = input_data.get("file_text", "")-- if not path:- return "Error: path is required"-- resolved = self._resolve_native_path(path, user_id)-- if resolved.exists():- return f"Error: File {path} already exists"-- # Create parent directories if needed- resolved.parent.mkdir(parents=True, exist_ok=True)-- resolved.write_text(file_text, encoding="utf-8")- logger.info(f"Memory: Native create: {path} for user {user_id}")-- return f"File created successfully at: {path}"-- def _native_str_replace(self, input_data: dict[str, Any], user_id: str) -> str:- """Replace text in a file."""- path = input_data.get("path", "")- old_str = input_data.get("old_str", "")- new_str = input_data.get("new_str", "")-- if not path:- return "Error: path is required"- if not old_str:- return "Error: old_str is required"-- resolved = self._resolve_native_path(path, user_id)-- if not resolved.exists():- return f"Error: The path {path} does not exist. Please provide a valid path."-- if resolved.is_dir():- return f"Error: The path {path} does not exist. Please provide a valid path."-- content = resolved.read_text(encoding="utf-8")-- # Check for occurrences- occurrences = content.count(old_str)- if occurrences == 0:- return f"No replacement was performed, old_str `{old_str}` did not appear verbatim in {path}."- if occurrences > 1:- # Find line numbers- lines = content.split("\n")- found_lines = []- for i, line in enumerate(lines, 1):- if old_str in line:- found_lines.append(str(i))- return (- f"No replacement was performed. Multiple occurrences of old_str `{old_str}` "- f"in lines: {', '.join(found_lines)}. Please ensure it is unique"- )-- # Perform replacement- new_content = content.replace(old_str, new_str, 1)- resolved.write_text(new_content, encoding="utf-8")-- # Show snippet around the change- lines = new_content.split("\n")- for i, line in enumerate(lines):- if new_str in line:- start = max(0, i - 2)- end = min(len(lines), i + 3)- snippet_lines = ["The memory file has been edited."]- for j in range(start, end):- snippet_lines.append(f"{j + 1:6d}\t{lines[j]}")- return "\n".join(snippet_lines)-- return "The memory file has been edited."-- def _native_insert(self, input_data: dict[str, Any], user_id: str) -> str:- """Insert text at a specific line."""- path = input_data.get("path", "")- insert_line = input_data.get("insert_line", 0)- insert_text = input_data.get("insert_text", "")-- if not path:- return "Error: path is required"-- resolved = self._resolve_native_path(path, user_id)-- if not resolved.exists():- return f"Error: The path {path} does not exist"-- if resolved.is_dir():- return f"Error: The path {path} does not exist"-- content = resolved.read_text(encoding="utf-8")- lines = content.split("\n")- n_lines = len(lines)-- if insert_line < 0 or insert_line > n_lines:- return (- f"Error: Invalid `insert_line` parameter: {insert_line}. "- f"It should be within the range of lines of the file: [0, {n_lines}]"- )-- # Insert at specified line- lines.insert(insert_line, insert_text.rstrip("\n"))-- resolved.write_text("\n".join(lines), encoding="utf-8")-- return f"The file {path} has been edited."-- def _native_delete_file(self, input_data: dict[str, Any], user_id: str) -> str:- """Delete a file or directory."""- path = input_data.get("path", "")-- if not path:- return "Error: path is required"-- resolved = self._resolve_native_path(path, user_id)-- if not resolved.exists():- return f"Error: The path {path} does not exist"-- import shutil-- if resolved.is_dir():- shutil.rmtree(resolved)- else:- resolved.unlink()-- logger.info(f"Memory: Native delete: {path} for user {user_id}")- return f"Successfully deleted {path}"-- def _native_rename(self, input_data: dict[str, Any], user_id: str) -> str:- """Rename or move a file/directory."""- old_path = input_data.get("old_path", "")- new_path = input_data.get("new_path", "")-- if not old_path:- return "Error: old_path is required"- if not new_path:- return "Error: new_path is required"-- resolved_old = self._resolve_native_path(old_path, user_id)- resolved_new = self._resolve_native_path(new_path, user_id)-- if not resolved_old.exists():- return f"Error: The path {old_path} does not exist"-- if resolved_new.exists():- return f"Error: The destination {new_path} already exists"-- # Create parent directory if needed- resolved_new.parent.mkdir(parents=True, exist_ok=True)-- resolved_old.rename(resolved_new)-- logger.info(f"Memory: Native rename: {old_path} -> {new_path} for user {user_id}")- return f"Successfully renamed {old_path} to {new_path}"-# =========================================================================# Semantic Translation Methods (Native Tool → Vector Store)# =========================================================================diff --git a/headroom/proxy/memory_ranker.py b/headroom/proxy/memory_ranker.pydeleted file mode 100644index 7ee3798fb..000000000--- a/headroom/proxy/memory_ranker.py+++ /dev/null@@ -1,202 +0,0 @@-"""``MemoryRanker``: pluggable re-ranker for memory candidates.--Pre-this-PR Headroom ranked memory candidates by pure cosine-similarity. Every other memory system we surveyed-(Letta / Mem0 / Cognee / Supermemory) re-ranks beyond cosine — recency,-source weight, access count, and decay are table-stakes for not-returning 6-month-old "winners" when fresh signal exists.--This module ships the first ranker — :class:`RecencyBoostRanker` —-plus the :class:`MemoryRanker` protocol that future rankers-(source-weight, access-count) plug into.--The ranker is **pure**: ``rank(candidates) -> ranked_candidates``,-no I/O, no state, no mutation of inputs. Same Rust-port shape as-``CompressionDecision`` and ``MemoryDecision``.--Performance: O(N) over candidates where N = top_k. One ``math.exp()``-per candidate. Sub-microsecond per request — no embedding compute,-no network, no disk.-"""--from __future__ import annotations--from dataclasses import dataclass, field-from datetime import datetime, timezone-from typing import Protocol--from headroom.proxy.memory_rank_policy import (- boost_memory_score,- memory_recency_factor,- parse_memory_created_at,-)--# Use ``timezone.utc`` (always available) instead of ``datetime.UTC``-# (Python 3.11+) so this module imports cleanly on older interpreters.-_UTC = timezone.utc---@dataclass(frozen=True)-class MemoryCandidate:- """Immutable retrieval candidate as it flows through the ranker.-- The shape is the **proxy-side internal contract** — the backend's- return type (typically ``MemoryResult`` with nested- ``MemoryResult.memory.created_at``) is adapted into this flatter- shape at the ranker boundary so the ranker stays backend-agnostic.-- ``score`` is the cosine similarity as returned by the backend.- Rankers MAY mutate ``score`` by returning a new candidate with an- updated score (frozen dataclass means they cannot mutate in place).- """-- content: str- score: float- created_at: datetime | None = None- source: str | None = None # e.g. "memory_save" | "traffic_learner" | "inline"- related_entities: tuple[str, ...] = field(default_factory=tuple)- # Backend memory ID. Empty string when not preserved (test fixtures,- # legacy callers). Rendered as ``[id]`` in the auto-tail block so the- # model can pass it to memory_update / memory_delete directly.- id: str = ""-- @classmethod- def from_backend_result(cls, result: object) -> MemoryCandidate:- """Adapter from backend ``MemoryResult`` shape to ``MemoryCandidate``.-- The backend returns objects with ``.score``, ``.memory.content``,- ``.memory.id``, and (optionally) ``.memory.created_at`` (str ISO- timestamp) + ``.related_entities``. This adapter flattens that to- the ranker's expected shape and parses the timestamp to- ``datetime``.-- Missing / unparseable timestamps → ``None`` (recency-neutral).- Missing IDs → ``""`` (rendered as ``[?]`` in the auto-tail block).- """- score = float(getattr(result, "score", 0.0))- memory = getattr(result, "memory", None)- content = str(getattr(memory, "content", "")) if memory is not None else ""- memory_id = str(getattr(memory, "id", "") or "") if memory is not None else ""- raw_dt = getattr(memory, "created_at", None) if memory is not None else None- created_at = parse_memory_created_at(raw_dt)- raw_related = getattr(result, "related_entities", None) or ()- related = tuple(str(x) for x in raw_related)- source_meta = getattr(memory, "metadata", None) or {}- source = source_meta.get("source") if isinstance(source_meta, dict) else None- return cls(- content=content,- score=score,- created_at=created_at,- source=source,- related_entities=related,- id=memory_id,- )---def _parse_created_at(value: object) -> datetime | None:- """Best-effort parse of a timestamp into a UTC-aware datetime.-- Accepts ``datetime`` (returned as-is, UTC-normalized) or ISO-8601- string (with or without trailing ``Z``). Anything else → ``None``- so the ranker treats the candidate as recency-neutral.- """- return parse_memory_created_at(value)---class MemoryRanker(Protocol):- """Re-ranks retrieval candidates. Pure function.-- Implementations MUST:- * Not mutate the input list or its elements- * Be deterministic (same input → same output) for prefix-cache- stability across consecutive turns- * Be backend-agnostic — work with any- :class:`MemoryCandidate`, regardless of which backend produced it- """-- def rank(self, candidates: list[MemoryCandidate]) -> list[MemoryCandidate]: ...---@dataclass(frozen=True)-class RecencyBoostRanker:- """Re-ranker applying an exponential recency decay to cosine scores.-- Final score: ``cosine × exp(-age_days / decay_days)``.-- At ``decay_days=30``:- * age = 0 days → factor 1.000- * age = 15 days → factor 0.607- * age = 30 days → factor 0.368- * age = 60 days → factor 0.135- * age = 90 days → factor 0.050-- Tuned so a fresh memory with weak cosine doesn't dominate (factor- decays gradually), but a 6-month-old strong-cosine can't dominate- either (factor approaches zero). Operators tune ``decay_days`` for- their codebase's rate of change — 7 days for rapidly-evolving- repos, 90 days for stable archival.-- Backwards-compat: candidates with ``created_at=None`` get factor- 1.0 — treated as recency-neutral. Lets a backend during a- migration return some rows with timestamps and some without- without breaking the ranker.-- Defensive: negative ages (clock skew on future-timestamped rows)- are clamped to factor 1.0 — a clock-skewed candidate cannot- outrank a real fresh one with the same cosine.- """-- decay_days: float = 30.0-- def rank(self, candidates: list[MemoryCandidate]) -> list[MemoryCandidate]:- """Re-rank by ``score × recency_factor``. Pure; input unchanged.-- Sorts descending by boosted score. Ties broken by input order- (Python's sort is stable) — deterministic output for prefix-- cache stability across turns.- """- if not candidates:- return []-- now = datetime.now(_UTC)- boosted: list[tuple[int, MemoryCandidate, float]] = []- for idx, c in enumerate(candidates):- new_score = boost_memory_score(- score=c.score,- now=now,- created_at=c.created_at,- decay_days=self.decay_days,- )- boosted.append((idx, c, new_score))-- # Sort descending by boosted score; stable on ties via the- # captured idx — same input order preserved on ties for- # deterministic output across turns.- boosted.sort(key=lambda triple: (-triple[2], triple[0]))-- # Return new candidates with the boosted score so downstream- # consumers (logging, budget filter) see the post-boost number.- return [- MemoryCandidate(- content=c.content,- score=new_score,- created_at=c.created_at,- source=c.source,- related_entities=c.related_entities,- id=c.id,- )- for _, c, new_score in boosted- ]-- def _recency_factor(self, now: datetime, created_at: datetime | None) -> float:- """Compute the recency multiplier for a single candidate.-- ``None`` timestamp → 1.0 (recency-neutral, backwards-compat).- Future timestamps → 1.0 (clock-skew defence).- Otherwise: ``exp(-age_days / decay_days)``.- """- return memory_recency_factor(- now=now,- created_at=created_at,- decay_days=self.decay_days,- )diff --git a/tests/test_memory_handler_native_ops.py b/tests/test_memory_handler_native_ops.pyindex f24cebd7e..570752b08 100644--- a/tests/test_memory_handler_native_ops.py+++ b/tests/test_memory_handler_native_ops.py@@ -86,155 +86,6 @@ def make_result()-def test_resolve_native_path_blocks_traversal(handler: MemoryHandler) -> None:- resolved = handler._resolve_native_path("/memories/topic.txt", "u1")- assert resolved.name == "topic.txt"- assert "u1" in str(resolved)-- with pytest.raises(ValueError, match="Path traversal detected"):- handler._resolve_native_path("/memories/../escape.txt", "u1")---def test_native_view_lists_directory_and_reads_files(handler: MemoryHandler) -> None:- root = handler._resolve_native_path("/memories", "u1")- (root / "alpha.txt").write_text("line1\nline2\nline3", encoding="utf-8")- (root / "nested").mkdir()- (root / "nested" / "beta.txt").write_text("nested", encoding="utf-8")- (root / ".hidden").write_text("skip", encoding="utf-8")- (root / "node_modules").mkdir()-- listing = handler._native_view({"path": "/memories"}, "u1")- assert "/memories/alpha.txt" in listing- assert "/memories/nested/beta.txt" in listing- assert ".hidden" not in listing- assert "/memories/node_modules" not in listing-- file_view = handler._native_view({"path": "/memories/alpha.txt", "view_range": [2, 3]}, "u1")- assert "2\tline2" in file_view- assert "3\tline3" in file_view---def test_native_view_handles_missing_paths_and_latin1(handler: MemoryHandler) -> None:- missing = handler._native_view({"path": "/memories/missing.txt"}, "u1")- assert "does not exist" in missing-- latin_path = handler._resolve_native_path("/memories/latin.txt", "u1")- latin_path.write_bytes("caf\xe9".encode("latin-1"))- viewed = handler._native_view({"path": "/memories/latin.txt"}, "u1")- assert "cafe" not in viewed- assert "café" in viewed---def test_native_create_insert_delete_and_rename(handler: MemoryHandler) -> None:- assert handler._native_create(- {"path": "/memories/note.txt", "file_text": "a\nb"}, "u1"- ).startswith("File created successfully")- assert handler._native_create(- {"path": "/memories/note.txt", "file_text": "dup"}, "u1"- ).startswith("Error: File /memories/note.txt already exists")-- inserted = handler._native_insert(- {"path": "/memories/note.txt", "insert_line": 1, "insert_text": "middle"},- "u1",- )- assert inserted == "The file /memories/note.txt has been edited."- assert "middle" in handler._resolve_native_path("/memories/note.txt", "u1").read_text(- encoding="utf-8"- )-- renamed = handler._native_rename(- {"old_path": "/memories/note.txt", "new_path": "/memories/archive/renamed.txt"},- "u1",- )- assert renamed == "Successfully renamed /memories/note.txt to /memories/archive/renamed.txt"-- deleted = handler._native_delete_file({"path": "/memories/archive"}, "u1")- assert deleted == "Successfully deleted /memories/archive"---def test_native_insert_validates_range_and_path(handler: MemoryHandler) -> None:- assert (- handler._native_insert({"insert_line": 0, "insert_text": "x"}, "u1")- == "Error: path is required"- )- assert "does not exist" in handler._native_insert(- {"path": "/memories/missing.txt", "insert_line": 0, "insert_text": "x"},- "u1",- )-- note = handler._resolve_native_path("/memories/note.txt", "u1")- note.write_text("a\nb", encoding="utf-8")- invalid = handler._native_insert(- {"path": "/memories/note.txt", "insert_line": 4, "insert_text": "x"},- "u1",- )- assert "Invalid `insert_line` parameter: 4" in invalid---def test_native_str_replace_covers_missing_multiple_and_success(handler: MemoryHandler) -> None:- note = handler._resolve_native_path("/memories/note.txt", "u1")- note.write_text("hello\nhello\nworld", encoding="utf-8")-- assert (- handler._native_str_replace({"old_str": "hello", "new_str": "bye"}, "u1")- == "Error: path is required"- )- assert (- handler._native_str_replace({"path": "/memories/note.txt", "new_str": "bye"}, "u1")- == "Error: old_str is required"- )-- multiple = handler._native_str_replace(- {"path": "/memories/note.txt", "old_str": "hello", "new_str": "bye"},- "u1",- )- assert "Multiple occurrences of old_str `hello` in lines: 1, 2" in multiple-- note.write_text("hello\nworld", encoding="utf-8")- missing = handler._native_str_replace(- {"path": "/memories/note.txt", "old_str": "nope", "new_str": "bye"},- "u1",- )- assert "did not appear verbatim" in missing-- success = handler._native_str_replace(- {"path": "/memories/note.txt", "old_str": "hello", "new_str": "bye"},- "u1",- )- assert "The memory file has been edited." in success- assert "bye" in note.read_text(encoding="utf-8")---def test_native_delete_and_rename_validate_inputs(handler: MemoryHandler) -> None:- assert handler._native_delete_file({}, "u1") == "Error: path is required"- assert "does not exist" in handler._native_delete_file({"path": "/memories/missing.txt"}, "u1")-- assert (- handler._native_rename({"new_path": "/memories/new.txt"}, "u1")- == "Error: old_path is required"- )- assert (- handler._native_rename({"old_path": "/memories/old.txt"}, "u1")- == "Error: new_path is required"- )- assert "does not exist" in handler._native_rename(- {"old_path": "/memories/old.txt", "new_path": "/memories/new.txt"},- "u1",- )-- old = handler._resolve_native_path("/memories/old.txt", "u1")- new = handler._resolve_native_path("/memories/new.txt", "u1")- old.write_text("x", encoding="utf-8")- new.write_text("y", encoding="utf-8")- assert (- handler._native_rename(- {"old_path": "/memories/old.txt", "new_path": "/memories/new.txt"},- "u1",- )- == "Error: The destination /memories/new.txt already exists"- )--@pytest.mark.asyncioasync def test_execute_native_memory_tool_dispatches_and_wraps_errors(handler: MemoryHandler, monkeypatch: pytest.MonkeyPatchdiff --git a/tests/test_memory_ranker.py b/tests/test_memory_ranker.pydeleted file mode 100644index 1a14eb8b5..000000000--- a/tests/test_memory_ranker.py+++ /dev/null@@ -1,293 +0,0 @@-"""Tests for :class:`headroom.proxy.memory_ranker.MemoryRanker` +-:class:`RecencyBoostRanker`.--Pre-this-PR Headroom ranked memory candidates by pure cosine-similarity. Every other memory system we surveyed (Letta, Mem0,-Cognee, Supermemory) re-ranks beyond cosine — recency / source /-access-count / decay are table-stakes. The pure-cosine baseline-returns 6-month-old memories with 0.9 similarity ahead of fresh-memories with 0.5 — wrong for most use cases.--``RecencyBoostRanker`` is the first ranker we ship: a pure-function-``score = cosine × exp(-age_days / decay_days)`` re-ranker. Default-``decay_days=30`` (half-life ~21 days). Other rankers (source-weight,-access-count) plug into the same :class:`MemoryRanker` protocol in-follow-on PRs.--Performance: O(N) over candidates where N = top_k = ~10. One ``exp()``-per candidate. Sub-microsecond per request — no embedding compute, no-I/O. The ranker is pure and Rust-portable.-"""--from __future__ import annotations--from dataclasses import FrozenInstanceError-from datetime import datetime, timedelta, timezone--from headroom.proxy.memory_ranker import (- MemoryCandidate,- RecencyBoostRanker,-)--_UTC = timezone.utc--# ── Helpers ───────────────────────────────────────────────────────────---def _candidate(content: str, score: float, age_days: float = 0.0) -> MemoryCandidate:- """Build a MemoryCandidate at the given cosine score and age."""- created = datetime.now(_UTC) - timedelta(days=age_days)- return MemoryCandidate(content=content, score=score, created_at=created)---def _candidate_no_timestamp(content: str, score: float) -> MemoryCandidate:- """Build a MemoryCandidate without a created_at (back-compat shape)."""- return MemoryCandidate(content=content, score=score, created_at=None)---# ── MemoryCandidate value-type contract ──────────────────────────────---def test_candidate_is_frozen() -> None:- """Frozen so a ranker can't mutate a candidate's score and lie about- which candidates it returned."""- c = _candidate("x", 0.9, age_days=0)- try:- c.score = 0.1 # type: ignore[misc]- except FrozenInstanceError:- pass- else:- raise AssertionError("MemoryCandidate must be frozen")---def test_from_backend_result_preserves_memory_id() -> None:- """The adapter must carry ``memory.id`` through to MemoryCandidate.id- so the auto-tail block can render it as the bracketed handle the- model uses for memory_update / memory_delete. Pre-this-fix the- adapter dropped the ID, which silently regressed the [id] auto-tail- format on the ranker path."""-- class _Mem:- id = "mem_abc_123"- content = "User prefers Python."- created_at = None- metadata = {"source": "memory_save"}-- class _Result:- memory = _Mem()- score = 0.91- related_entities = ("python",)-- cand = MemoryCandidate.from_backend_result(_Result())- assert cand.id == "mem_abc_123"- assert cand.content == "User prefers Python."- assert cand.score == 0.91---def test_rank_preserves_memory_id() -> None:- """The ranker must not drop the backend ID when rebuilding candidates."""- cand = MemoryCandidate(content="User prefers Python.", score=0.91, id="mem_abc_123")- out = RecencyBoostRanker().rank([cand])- assert out[0].id == "mem_abc_123"---def test_from_backend_result_handles_missing_id() -> None:- """Defensive: legacy backend rows without an ID become ``id=""``;- the auto-tail formatter renders ``[?]`` for those rows, no crash."""-- class _Mem:- # no .id attribute- content = "legacy row"- created_at = None- metadata = {}-- class _Result:- memory = _Mem()- score = 0.5- related_entities = ()-- cand = MemoryCandidate.from_backend_result(_Result())- assert cand.id == ""---# ── RecencyBoostRanker contract ──────────────────────────────────────---def test_ranker_is_frozen() -> None:- """The ranker config is itself immutable — operators set- ``decay_days`` at construction; runtime cannot edit it."""- r = RecencyBoostRanker()- try:- r.decay_days = 99 # type: ignore[misc]- except FrozenInstanceError:- pass- else:- raise AssertionError("RecencyBoostRanker must be frozen")---def test_ranker_default_decay_is_thirty_days() -> None:- """30-day decay is the conservative default. At 30 days, factor is- ~0.37 (e^{-1}); at 90 days, ~0.05. Tuned so a fresh memory with- weak cosine doesn't dominate, but a 6-month-old strong-cosine- can't dominate either."""- assert RecencyBoostRanker().decay_days == 30.0---def test_ranker_default_decay_is_configurable() -> None:- """Operators can tune decay; e.g., 7 days for an aggressive- recency bias on rapidly-evolving codebases."""- r = RecencyBoostRanker(decay_days=7.0)- assert r.decay_days == 7.0---def test_ranker_returns_list_preserving_shape() -> None:- """Output is a list of candidates (re-ranked). Length matches- input length — the ranker does NOT filter, only re-orders. The- budget filters; the ranker ranks."""- candidates = [_candidate("a", 0.9), _candidate("b", 0.5)]- out = RecencyBoostRanker().rank(candidates)- assert len(out) == 2- assert {c.content for c in out} == {"a", "b"}---# ── Recency boost behaviour ──────────────────────────────────────────---def test_equal_cosine_younger_wins() -> None:- """Two candidates with identical cosine score — the younger one- wins because its recency factor is closer to 1.0."""- fresh = _candidate("fresh", 0.5, age_days=0)- old = _candidate("old", 0.5, age_days=60)- out = RecencyBoostRanker().rank([old, fresh])- assert out[0].content == "fresh"- assert out[1].content == "old"---def test_old_strong_cosine_can_still_beat_young_weak_cosine() -> None:- """The boost is multiplicative, not absolute — a 60-day-old memory- with 0.9 cosine (0.9 × 0.135 ≈ 0.12) still loses to a 0-day-old- memory with 0.5 cosine (0.5 × 1.0 = 0.5). But a 5-day-old memory- with 0.9 (0.9 × 0.847 ≈ 0.76) beats a 0-day-old with 0.5."""- very_old_strong = _candidate("old_strong", 0.9, age_days=60)- fresh_weak = _candidate("fresh_weak", 0.5, age_days=0)- out = RecencyBoostRanker().rank([very_old_strong, fresh_weak])- # fresh_weak should win because 60-day decay flattens the strong cosine- assert out[0].content == "fresh_weak"-- # Versus: slightly-old strong beats fresh weak- slightly_old_strong = _candidate("slightly_old_strong", 0.9, age_days=5)- fresh_weak2 = _candidate("fresh_weak2", 0.5, age_days=0)- out2 = RecencyBoostRanker().rank([fresh_weak2, slightly_old_strong])- assert out2[0].content == "slightly_old_strong"---def test_decay_rate_changes_winner() -> None:- """An aggressive decay_days=7 makes a 30-day-old memory much- weaker than a default decay_days=30. Locks the configurability- contract."""- old_strong = _candidate("old_strong", 0.9, age_days=30)- fresh_weak = _candidate("fresh_weak", 0.6, age_days=0)-- # decay_days=30: old × e^{-1} ≈ 0.331; fresh = 0.6 → fresh wins- r_default = RecencyBoostRanker(decay_days=30.0)- out_default = r_default.rank([old_strong, fresh_weak])- assert out_default[0].content == "fresh_weak"-- # decay_days=120 (loose): old × e^{-0.25} ≈ 0.701; fresh = 0.6 → old wins- r_loose = RecencyBoostRanker(decay_days=120.0)- out_loose = r_loose.rank([old_strong, fresh_weak])- assert out_loose[0].content == "old_strong"---def test_zero_age_memory_keeps_full_cosine() -> None:- """At age=0 days, the recency factor is e^0 = 1.0 — the boosted- score equals the original cosine. Fresh memories see no penalty."""- fresh = _candidate("fresh", 0.7, age_days=0)- out = RecencyBoostRanker().rank([fresh])- # Compare with tolerance — datetime.now() drift between- # _candidate() and rank() is microseconds, so factor ~ 1.0.- assert out[0].score == 0.7 or abs(out[0].score - 0.7) < 1e-3---def test_candidate_without_timestamp_keeps_pure_cosine() -> None:- """Backwards-compat: pre-this-PR candidates may not have a- ``created_at`` (older rows / older backends). NULL timestamp- means "treat as recency-neutral" — factor 1.0. Pure cosine."""- no_ts = _candidate_no_timestamp("legacy", 0.8)- out = RecencyBoostRanker().rank([no_ts])- assert out[0].score == 0.8---def test_mixed_with_and_without_timestamps() -> None:- """A backend that returns SOME candidates with timestamps and- SOME without (e.g., during a migration) must still produce a- sensible ranking. NULL-timestamp candidates get factor 1.0,- timestamped ones get their decay."""- fresh_ts = _candidate("fresh_ts", 0.6, age_days=0)- old_ts = _candidate("old_ts", 0.6, age_days=60)- no_ts_neutral = _candidate_no_timestamp("no_ts", 0.6)- out = RecencyBoostRanker().rank([old_ts, no_ts_neutral, fresh_ts])- # fresh_ts (~0.6) and no_ts (=0.6) tied at top — old_ts decayed.- assert out[-1].content == "old_ts"- assert {out[0].content, out[1].content} == {"fresh_ts", "no_ts"}---# ── Stability + edge cases ───────────────────────────────────────────---def test_empty_input_returns_empty_output() -> None:- """No candidates → no candidates. Boundary case."""- assert RecencyBoostRanker().rank([]) == []---def test_ranking_is_stable_for_identical_candidates() -> None:- """Two candidates with identical content + score + age → stable- order (no spurious reshuffling). Important for prefix-cache- stability: a deterministic ranker means consecutive turns inject- the same memory in the same order, preserving byte-stable- output."""- a = _candidate("same", 0.5, age_days=10)- b = _candidate("same", 0.5, age_days=10)- out = RecencyBoostRanker().rank([a, b])- assert len(out) == 2---def test_negative_age_treated_as_zero() -> None:- """Defensive: a candidate with a future ``created_at`` (clock- skew) shouldn't crash or give a > 1.0 factor. ``exp(-age/decay)``- with negative age gives > 1; we clamp to 1.0 so a clock-skewed- candidate can't outrank a real fresh one with score=1.0- artifically."""- future = _candidate("future", 0.5, age_days=-10) # 10 days in future- fresh = _candidate("fresh", 0.5, age_days=0)- out = RecencyBoostRanker().rank([future, fresh])- # Both should have factor 1.0 (clamped) — score equal → stable order- assert {out[0].content, out[1].content} == {"future", "fresh"}- assert out[0].score == 0.5 or abs(out[0].score - 0.5) < 1e-3---# ── Rust-port shape ─────────────────────────────────────────────────---def test_ranker_is_pure_no_side_effects() -> None:- """Calling rank() twice with the same input gives the same- output. No state on the ranker; no I/O. Rust-portable."""- candidates = [_candidate("a", 0.7, age_days=5), _candidate("b", 0.5, age_days=20)]- r = RecencyBoostRanker()- out1 = r.rank(candidates)- out2 = r.rank(candidates)- assert [c.content for c in out1] == [c.content for c in out2]- # Inputs preserved — ranker did not mutate- assert candidates[0].content == "a"- assert candidates[1].content == "b"---def test_ranker_does_not_mutate_input_list() -> None:- """Defence-in-depth: the input list and its elements must be- unchanged after ranking. Frozen candidates make element mutation- impossible; the list order itself must also be preserved."""- a = _candidate("a", 0.5, age_days=20)- b = _candidate("b", 0.5, age_days=5)- candidates = [a, b]- RecencyBoostRanker().rank(candidates)- assert candidates == [a, b] # original list order preserved