dsh-biocore 0.1.0 → 0.1.2

package/python/biocore_memory/event/notes_link.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""Notes bridge: attach an A-MEM style note to one memory entry.
+
+Calls event.notes.make_note(text, tags, links) and stores the bounded result
+as metadata["note"] = {title, summary, tags, links}. Only metadata is written:
+text / id / role / ts / vector are never modified.
+
+Interface:
+  enrich_entry(entry, enabled=None, tags=None, links=None) -> entry
+
+The module is disabled by default (NOTES_LINK_ENABLED=False): callers gate on
+'enabled' before writing. Passing enabled=False forces a no-op.
+No IO, no LLM, no host imports.
+"""
+from __future__ import annotations
+
+from .notes import make_note
+
+enabled = False
+NOTES_LINK_ENABLED = enabled
+
+NOTE_KEY = "note"
+MAX_LINKS = 8
+MAX_SOURCE_ITEMS = 32
+
+
+def _as_list(value):
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, dict):
+        return list(value.keys())
+    try:
+        return list(value)
+    except TypeError:
+        return [value]
+
+
+def _entry_tags(entry):
+    tags = []
+    for key in ("tags", "labels", "topics"):
+        tags.extend(_as_list(entry.get(key)))
+    cue = entry.get("cue_index")
+    if isinstance(cue, dict):
+        tags.extend(_as_list(cue.get("entities")))
+        tags.extend(_as_list(cue.get("place")))
+        tags.append(cue.get("event_name"))
+    metadata = entry.get("metadata")
+    if isinstance(metadata, dict):
+        tags.extend(_as_list(metadata.get("tags")))
+    return tags[:MAX_SOURCE_ITEMS]
+
+
+def _entry_links(entry):
+    links = []
+    for key in ("related_ids", "links"):
+        links.extend(_as_list(entry.get(key)))
+    cue = entry.get("cue_index")
+    if isinstance(cue, dict):
+        links.extend(_as_list(cue.get("related_ids")))
+    metadata = entry.get("metadata")
+    if isinstance(metadata, dict):
+        links.extend(_as_list(metadata.get("links")))
+    return links[:MAX_SOURCE_ITEMS]
+
+
+def enrich_entry(entry, enabled=None, tags=None, links=None):
+    """Attach metadata["note"] and return the entry (unchanged if disabled)."""
+    if enabled is False or not isinstance(entry, dict):
+        return entry
+    text = entry.get("text") or entry.get("content") or ""
+    if not str(text or "").strip():
+        return entry
+    note_tags = tags if tags is not None else _entry_tags(entry)
+    note_links = links if links is not None else _entry_links(entry)
+    note = make_note(text, tags=note_tags, links=note_links)
+    metadata = entry.get("metadata")
+    if not isinstance(metadata, dict):
+        metadata = {}
+        entry["metadata"] = metadata
+    metadata[NOTE_KEY] = note
+    return entry
+
+
+__all__ = ["enabled", "NOTES_LINK_ENABLED", "enrich_entry", "NOTE_KEY",
+           "MAX_LINKS"]

package/python/biocore_memory/event/vector.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""Seven-dimension event vector (host-neutral; no I/O, no prompt)."""
+from __future__ import annotations
+from ..core.types import EventVector
+from ..core.util import clamp01
+
+DIMENSIONS = ("intensity", "self_relevance", "schema_conflict",
+              "relation_weight", "novelty", "unresolved", "repetition")
+
+
+def extract_vector(meta=None, affect=None) -> EventVector:
+    """Build the seven-dim event vector from metadata and an L1 affect snapshot.
+
+    Missing values default to neutral (0.0); all dims are clamped to [0, 1].
+    Deterministic and pure: no host access, no LLM, no writes.
+    """
+    m = meta if isinstance(meta, dict) else {}
+    a = affect if isinstance(affect, dict) else {}
+    return EventVector(
+        intensity=clamp01(m.get("intensity", a.get("intensity", 0.0))),
+        self_relevance=clamp01(m.get("self_relevance",
+                                   m.get("self_defining", a.get("self_relevance", 0.0)))),
+        schema_conflict=clamp01(m.get("schema_conflict",
+                                     m.get("conflict", a.get("schema_conflict", 0.0)))),
+        relation_weight=clamp01(m.get("relation_weight",
+                                     a.get("relation_weight", a.get("trust", 0.0)))),
+        novelty=clamp01(m.get("novelty", a.get("novelty", 0.0))),
+        unresolved=clamp01(m.get("unresolved", a.get("unresolved", 0.0))),
+        repetition=clamp01(m.get("repetition", a.get("repetition", 0.0))),
+    )
+
+
+def vector_dict(meta=None, affect=None) -> dict:
+    """Return extract_vector() as a plain dict (JSON-friendly)."""
+    return extract_vector(meta, affect).as_dict()
+
+def value_score(meta=None, affect=None) -> float:
+    """Deterministic memory-value score (trust is deliberately excluded).
+
+    value = BASE + W_I*intensity + W_V*|valence| + W_S*self_relevance
+            + W_M*mainline - W_R*routine
+    Missing fields default to neutral; result clamped to [0, 1].
+    """
+    from ..core.config import (VALUE_BASE, VALUE_W_INTENSITY, VALUE_W_VALENCE,
+                               VALUE_W_SELF, VALUE_W_MAINLINE, VALUE_W_ROUTINE)
+    m = meta if isinstance(meta, dict) else {}
+    a = affect if isinstance(affect, dict) else {}
+    vec = extract_vector(m, a)
+    try:
+        valence = abs(float(m.get("valence", a.get("valence", 0.0)) or 0.0))
+    except Exception:
+        valence = 0.0
+    mainline = m.get("mainline", a.get("goals") and 0.5 or 0.0)
+    try:
+        mainline = float(mainline or 0.0)
+    except Exception:
+        mainline = 0.0
+    routine = m.get("routine", 0.0)
+    try:
+        routine = float(routine or 0.0)
+    except Exception:
+        routine = 0.0
+    value = (VALUE_BASE
+             + VALUE_W_INTENSITY * vec.intensity
+             + VALUE_W_VALENCE * clamp01(valence)
+             + VALUE_W_SELF * vec.self_relevance
+             + VALUE_W_MAINLINE * clamp01(mainline)
+             - VALUE_W_ROUTINE * clamp01(routine))
+    return round(clamp01(value), 6)

package/python/biocore_memory/evict/__init__.py

@@ -0,0 +1,3 @@
+# OWNER: engine-core
+from .score import eviction_score  # noqa
+from .policy import eviction_order  # noqa

package/python/biocore_memory/evict/adaptive.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""Adaptive forgetting rate (default OFF; pure function, no IO).
+
+adaptive_score(base, load, importance) = base * (1 + 0.5*load) * (1 - 0.3*importance)
+clamped to 0..1. load and importance are normalized to 0..1.
+"""
+from __future__ import annotations
+
+ADAPTIVE_ENABLED = False
+
+
+def _clamp(value):
+    try:
+        return max(0.0, min(1.0, float(value)))
+    except Exception:
+        return 0.0
+
+
+def adaptive_score(base, load=0.0, importance=0.0):
+    """Return the bounded adaptive eviction score (higher = evict earlier)."""
+    b = _clamp(base)
+    l = _clamp(load)
+    i = _clamp(importance)
+    return round(_clamp(b * (1.0 + 0.5 * l) * (1.0 - 0.3 * i)), 6)
+
+
+def _base_of(entry, base_scores):
+    if isinstance(base_scores, dict):
+        try:
+            return float(base_scores.get(str(entry.get("id") or "")) or 0.0)
+        except Exception:
+            return 0.0
+    for key in ("evict_score", "score", "base_score"):
+        if key in entry:
+            try:
+                return float(entry.get(key) or 0.0)
+            except Exception:
+                return 0.0
+    return 0.0
+
+
+def _load_of(entry, load):
+    if load is not None:
+        return _clamp(load)
+    for key in ("load", "pressure", "allostatic_load"):
+        if key in entry:
+            return _clamp(entry.get(key))
+    return 0.0
+
+
+def rank(entries, base_scores=None, load=None):
+    """Return [(id, score)] ordered by adaptive score descending (evict-first)."""
+    rows = [e for e in (entries or []) if isinstance(e, dict)]
+    if not ADAPTIVE_ENABLED:
+        out = [(str(e.get("id") or ""), _clamp(_base_of(e, base_scores))) for e in rows]
+        out.sort(key=lambda x: (-x[1], x[0]))
+        return out
+    scored = []
+    for entry in rows:
+        score = adaptive_score(_base_of(entry, base_scores),
+                               _load_of(entry, load), entry.get("importance", 0.0))
+        scored.append((str(entry.get("id") or ""), score))
+    scored.sort(key=lambda x: (-x[1], x[0]))
+    return scored
+
+
+def select(entries, budget, base_scores=None, load=None):
+    """Return ids of the top-budget entries by adaptive eviction score."""
+    try:
+        limit = max(0, int(budget or 0))
+    except Exception:
+        limit = 0
+    return [eid for eid, _score in rank(entries, base_scores, load)[:limit]]

package/python/biocore_memory/evict/consequence.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""Consequence-aware eviction (pure; default OFF)."""
+from __future__ import annotations
+
+from ..core.util import clamp01
+
+CONSEQUENCE_ENABLED = False
+PROMISE_WORDS = ("答应", "承诺", "保证", "约定", "说好", "一定会", "不再", "永远")
+DEADLINE_WORDS = ("明天", "后天", "截止", "ddl", "deadline", "之前", "周", "月", "日", "点")
+RISK_WORDS = ("危险", "风险", "生病", "医院", "药", "分手", "绝交", "吵架", "难过", "崩溃",
+              "secret", "密码", "隐私", "重要")
+
+
+def _matches(text, words):
+    value = str(text or "").lower()
+    return any(str(word).lower() in value for word in words)
+
+
+def _score(entry):
+    e = entry if isinstance(entry, dict) else {}
+    text = " ".join(str(e.get(k) or "") for k in ("text", "title", "event", "big_summary"))
+    importance = clamp01(e.get("importance"), 0.5)
+    promise = 0.30 if _matches(text, PROMISE_WORDS) or e.get("promise") else 0.0
+    deadline = 0.25 if _matches(text, DEADLINE_WORDS) or e.get("deadline") else 0.0
+    risk = 0.20 if _matches(text, RISK_WORDS) or e.get("risk") else 0.0
+    explicit = 0.25 * clamp01(e.get("consequence"), 0.0) if "consequence" in e else 0.0
+    return clamp01(0.35 * importance + promise + deadline + risk + explicit, 0.0)
+
+
+def consequence(entry):
+    """0..1 consequence of forgetting an entry (higher = should keep)."""
+    if not CONSEQUENCE_ENABLED or not isinstance(entry, dict):
+        return 0.0
+    try:
+        return round(_score(entry), 4)
+    except Exception:
+        return 0.0
+
+
+def select_by_consequence(entries, budget):
+    """Return ids to evict first: lowest consequence, protected entries skipped."""
+    if not CONSEQUENCE_ENABLED:
+        return []
+    try:
+        limit = max(0, int(budget or 0))
+    except Exception:
+        limit = 0
+    if not limit:
+        return []
+    rows = []
+    for entry in entries or []:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("pin") or entry.get("pinned") or entry.get("self_defining") or entry.get("identity"):
+            continue
+        rows.append((_score(entry), str(entry.get("id") or entry.get("memory_id") or "")))
+    rows.sort(key=lambda row: (row[0], row[1]))
+    return [eid for _score_value, eid in rows if eid][:limit]

package/python/biocore_memory/evict/heat.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+"""MemoryOS-style heat score (pure; default OFF)."""
+from __future__ import annotations
+
+import math
+import time
+
+from ..core.util import clamp01
+
+HEAT_ENABLED = False
+ALPHA = 1.0
+BETA = 1.0
+GAMMA = 1.0
+TAU_HOURS = 24.0
+
+
+def _num(entry, keys):
+    for key in keys:
+        try:
+            value = float(entry.get(key) or 0.0)
+            return max(0.0, value)
+        except Exception:
+            continue
+    return 0.0
+
+
+def _last_ts(entry):
+    for key in ("last_recall", "last_access", "last_visit_time", "ts", "created_ts"):
+        try:
+            value = float(entry.get(key) or 0.0)
+            if value > 0:
+                return value
+        except Exception:
+            continue
+    return 0.0
+
+
+def heat(entry, now=None):
+    """heat = alpha*visits + beta*interactions + gamma*recency, normalized 0..1."""
+    if not HEAT_ENABLED or not isinstance(entry, dict):
+        return 0.0
+    try:
+        stamp = float(now if now is not None else time.time())
+        visits = _num(entry, ("visits", "visit_count", "N_visit", "hits"))
+        interactions = _num(entry, ("interactions", "interaction_count", "L_interaction"))
+        last = _last_ts(entry)
+        age_hours = max(0.0, stamp - last) / 3600.0 if last else 0.0
+        recency = 0.5 ** (age_hours / TAU_HOURS)
+        v = visits / (1.0 + visits)
+        i = interactions / (1.0 + interactions)
+        total = ALPHA + BETA + GAMMA
+        return clamp01((ALPHA * v + BETA * i + GAMMA * recency) / total, 0.0)
+    except Exception:
+        return 0.0

package/python/biocore_memory/evict/inhibition.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*-
+"""Retrieval-induced forgetting (RIF) inhibition (pure; default OFF).
+
+Retrieving a target suppresses competing memories (Anderson, Bjork & Bjork
+1994). Entries that lost the retrieval competition get a bounded inhibition
+budget that decays with a 7-day half-life.
+
+Interface:
+  mark_inhibited(entries, selected_ids, increment=0.2, cap=1.0) -> [ids]
+      Adds 'increment' to every entry whose id is not in selected_ids
+      (in place, bounded by cap) and returns the touched ids in input order.
+  decay(entry, days=7.0) -> float
+      Inhibition value after 'days' of exponential decay (7-day half-life).
+  filter_inhibited(entries, threshold=0.5, days=None) -> list
+      Entries whose (optionally decayed) inhibition is below the threshold.
+
+The module is disabled by default: callers gate on 'enabled' before applying
+mutations. Helpers are deterministic and never touch the file system.
+"""
+from __future__ import annotations
+
+import math
+
+enabled = False
+INHIBITION_ENABLED = enabled
+
+INCREMENT = 0.2
+MAX_INHIBITION = 1.0
+HALF_LIFE_DAYS = 7.0
+THRESHOLD = 0.5
+
+
+def _num(value, default=0.0):
+    try:
+        value = float(value)
+    except (TypeError, ValueError):
+        return default
+    return value if math.isfinite(value) else default
+
+
+def _clamp(value, low, high):
+    return max(low, min(high, value))
+
+
+def _entry_id(entry):
+    if not isinstance(entry, dict):
+        return ""
+    return str(entry.get("id") or entry.get("memory_id") or "")
+
+
+def _value(entry):
+    if not isinstance(entry, dict):
+        return 0.0
+    return _clamp(_num(entry.get("inhibition", 0.0), 0.0), 0.0, MAX_INHIBITION)
+
+
+def _rows(entries):
+    try:
+        return list(entries or [])
+    except TypeError:
+        return []
+
+
+def mark_inhibited(entries, selected_ids, increment=INCREMENT,
+                   cap=MAX_INHIBITION):
+    """Inhibit every unselected entry by 'increment' (bounded); return ids."""
+    selected = {str(value) for value in (selected_ids or []) if str(value)}
+    step = _clamp(_num(increment, INCREMENT), 0.0, MAX_INHIBITION)
+    ceiling = _clamp(_num(cap, MAX_INHIBITION), 0.0, MAX_INHIBITION)
+    touched = []
+    for entry in _rows(entries):
+        entry_id = _entry_id(entry)
+        if not entry_id or entry_id in selected:
+            continue
+        old = _value(entry)
+        new = min(ceiling, old + step)
+        if new <= old:
+            continue
+        entry["inhibition"] = round(new, 4)
+        touched.append(entry_id)
+    return touched
+
+
+def decay(entry, days=HALF_LIFE_DAYS):
+    """Return the inhibition after 'days' of decay (7-day half-life)."""
+    age = max(0.0, _num(days, HALF_LIFE_DAYS))
+    return round(_value(entry) * math.pow(0.5, age / HALF_LIFE_DAYS), 4)
+
+
+def filter_inhibited(entries, threshold=THRESHOLD, days=None):
+    """Return entries with inhibition below 'threshold' (not suppressed)."""
+    limit = _clamp(_num(threshold, THRESHOLD), 0.0, MAX_INHIBITION)
+    kept = []
+    for entry in _rows(entries):
+        if not isinstance(entry, dict):
+            continue
+        value = _value(entry) if days is None else decay(entry, days)
+        if value < limit:
+            kept.append(entry)
+    return kept
+
+
+__all__ = ["enabled", "INHIBITION_ENABLED", "mark_inhibited", "decay",
+           "filter_inhibited", "INCREMENT", "MAX_INHIBITION",
+           "HALF_LIFE_DAYS", "THRESHOLD"]

package/python/biocore_memory/evict/policy.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""Read-only eviction decisions (never deletes, never writes).
+
+eviction_order() keeps the legacy candidate ordering used by the engine.
+tick(entries, now) is the M2 read-only decision pass: it partitions entries
+into archive / flag / keep for the caller to act on later.
+
+Protection rules (never archived):
+- pinned / desktop-anchor style pin;
+- self-defining / identity entries;
+- explicit promises / open loops / commitments;
+- P0/P1 priority entries.
+
+Archive-first signals (deterministic, bounded):
+- low salience (importance and event intensity both low);
+- redundancy (duplicate text, later copies first);
+- old versions (version chain at/over the configured max, or superseded);
+- long unused (no access for >= 30 days, when now is supplied);
+- otherwise a low eviction score (< ARCHIVE_SCORE).
+Between ARCHIVE_SCORE and FLAG_SCORE the entry is only flagged.
+"""
+from __future__ import annotations
+
+from ..core.config import MAX_VERSIONS
+from ..core.util import clamp01
+from .score import eviction_score
+
+ARCHIVE_SCORE = 0.30
+FLAG_SCORE = 0.50
+STALE_SECONDS = 30 * 86400.0
+LOW_SALIENCE = 0.35
+REDUNDANCY_ARCHIVE = 0.60
+# L5 schema-based eviction (default OFF: tick behaves exactly as before).
+SCHEMA_EVICTION_ENABLED = False
+SCHEMA_ARCHIVE = 0.35
+CONSEQUENCE_ARCHIVE = 0.40
+
+
+def _entry_id(entry):
+    return str(entry.get("id") or entry.get("memory_id") or "")
+
+
+def _event_intensity(entry):
+    vector = entry.get("event_vector")
+    if hasattr(vector, "as_dict"):
+        try:
+            vector = vector.as_dict()
+        except Exception:
+            vector = None
+    if isinstance(vector, dict):
+        return clamp01(vector.get("intensity"), 0.0)
+    return clamp01(entry.get("event_intensity"), 0.0)
+
+
+def _salience(entry):
+    return clamp01(0.6 * clamp01(entry.get("importance"), 0.5)
+                   + 0.4 * _event_intensity(entry), 0.5)
+
+
+def _is_protected(entry):
+    if entry.get("pin") or entry.get("pinned"):
+        return True
+    if entry.get("self_defining") or entry.get("identity"):
+        return True
+    for key in ("promise", "promises", "commitment", "open_loop", "open_loops"):
+        if entry.get(key):
+            return True
+    priority = str(entry.get("priority") or "").upper()
+    if entry.get("p0") or entry.get("p1") or priority in ("P0", "P1"):
+        return True
+    metadata = entry.get("metadata") if isinstance(entry.get("metadata"), dict) else {}
+    return bool(metadata.get("pin") or metadata.get("pinned")
+                or metadata.get("self_defining") or metadata.get("promise"))
+
+
+def _schema_congruence(entry):
+    """Read schema congruence from entry or its event_vector (0..1)."""
+    vector = entry.get("event_vector")
+    if hasattr(vector, "as_dict"):
+        try:
+            vector = vector.as_dict()
+        except Exception:
+            vector = None
+    if isinstance(vector, dict) and vector.get("schema_conflict") is not None:
+        return clamp01(1.0 - clamp01(vector.get("schema_conflict"), 0.0))
+    return clamp01(entry.get("schema_congruence"), 1.0)
+
+
+def _consequence(entry):
+    """0..1 consequence of forgetting; missing means neutral/low."""
+    return clamp01(entry.get("consequence"), 0.5)
+
+
+def _is_old_version(entry):
+    if entry.get("superseded") or entry.get("old_version"):
+        return True
+    versions = entry.get("previous_versions")
+    if isinstance(versions, (list, tuple)) and len(versions) >= max(1, int(MAX_VERSIONS)):
+        return True
+    metadata = entry.get("metadata") if isinstance(entry.get("metadata"), dict) else {}
+    return bool(metadata.get("superseded") or metadata.get("old_version"))
+
+
+def _age_seconds(entry, now):
+    if not now:
+        return 0.0
+    last = 0.0
+    for key in ("last_recall", "last_access", "ts", "created_ts"):
+        try:
+            last = max(last, float(entry.get(key) or 0.0))
+        except Exception:
+            continue
+    if last <= 0:
+        # No access timestamp at all: unknown age counts as long-unused.
+        return float(now)
+    try:
+        return max(0.0, float(now) - last)
+    except Exception:
+        return 0.0
+
+
+def eviction_order(rows):
+    """Legacy candidate order: protected/desktop/index-retained first."""
+    out = []
+    for row in rows or []:
+        if not isinstance(row, dict):
+            continue
+        entry = row.get("entry") if isinstance(row.get("entry"), dict) else row
+        key = {"id": str(entry.get("id") or ""),
+               "score": float(row.get("score", 0.0) or 0.0),
+               "pinned": bool(entry.get("pin")),
+               "desktop": bool(entry.get("desktop")),
+               "index_retained": bool(entry.get("index_retained"))}
+        out.append(key)
+    out.sort(key=lambda r: (not r["pinned"], not r["desktop"],
+                            not r["index_retained"], -r["score"]))
+    return out
+
+
+def tick(entries, now=0.0):
+    """Partition entries into {"archive": [ids], "flag": [ids], "keep": [ids]}.
+
+    Read-only: no entry is mutated or removed. Ordering is deterministic:
+    archive/flag by (score ascending, id); keep keeps input order.
+    """
+    items = [e for e in (entries or []) if isinstance(e, dict)]
+    total = max(1, len(items))
+    seen_text = set()
+    scored = []
+    for position, entry in enumerate(items):
+        entry_id = _entry_id(entry)
+        if not entry_id:
+            continue
+        text = " ".join(str(entry.get("text") or "").split()).lower()
+        duplicate = bool(text) and text in seen_text
+        if text:
+            seen_text.add(text)
+        if _is_protected(entry):
+            scored.append((entry_id, 1.0, "keep", entry))
+            continue
+        redundancy = 1.0 if duplicate else (
+            1.0 if clamp01(entry.get("redundancy"), 0.0) >= REDUNDANCY_ARCHIVE else 0.0)
+        score = eviction_score(entry, now=now,
+                               position=position / float(total),
+                               redundancy=redundancy)
+        stale = _age_seconds(entry, now) >= STALE_SECONDS
+        low_salience = _salience(entry) < LOW_SALIENCE
+        schema_archive = (SCHEMA_EVICTION_ENABLED
+                          and _schema_congruence(entry) < SCHEMA_ARCHIVE
+                          and _consequence(entry) < CONSEQUENCE_ARCHIVE)
+        must_archive = (duplicate or redundancy >= REDUNDANCY_ARCHIVE
+                        or _is_old_version(entry) or stale or low_salience
+                        or schema_archive)
+        if must_archive or score < ARCHIVE_SCORE:
+            decision = "archive"
+        elif score < FLAG_SCORE:
+            decision = "flag"
+        else:
+            decision = "keep"
+        scored.append((entry_id, score, decision, entry))
+    archive = [item for item in scored if item[2] == "archive"]
+    flagged = [item for item in scored if item[2] == "flag"]
+    keep = [item[0] for item in scored if item[2] == "keep"]
+    archive.sort(key=lambda item: (item[1], item[0]))
+    flagged.sort(key=lambda item: (item[1], item[0]))
+    return {"archive": [item[0] for item in archive],
+            "flag": [item[0] for item in flagged],
+            "keep": keep}

package/python/biocore_memory/evict/score.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+"""Read-only eviction score (never deletes by itself)."""
+from __future__ import annotations
+from ..core.config import (EVICT_W_CONFIDENCE, EVICT_W_POSITION,
+                           EVICT_W_REDUNDANCY, EVICT_W_SALIENCE,
+                           EVICT_W_STALENESS)
+from ..core.util import clamp01
+
+
+def eviction_score(entry, now=0.0, position=0.5, redundancy=0.0):
+    e = entry if isinstance(entry, dict) else {}
+    salience = clamp01(e.get("importance"), 0.5)
+    pos = clamp01(position, 0.5)
+    red = clamp01(redundancy, 0.0)
+    conf = clamp01(e.get("memory_confidence"), 0.5)
+    try:
+        age = max(0.0, float(now or 0.0) - float(e.get("last_recall", e.get("ts", 0.0)) or 0.0))
+    except Exception:
+        age = 0.0
+    stale = min(1.0, age / 86400.0 / 30.0) if now else 0.0
+    return round(EVICT_W_SALIENCE * salience + EVICT_W_POSITION * pos
+                 + EVICT_W_REDUNDANCY * red
+                 + EVICT_W_CONFIDENCE * conf + EVICT_W_STALENESS * stale, 4)

package/python/biocore_memory/identity/__init__.py

@@ -0,0 +1,6 @@
+# OWNER: engine-core
+from .writeback import (IDENTITY_FIELDS, MAX_STEP, SAME_DIRECTION_MIN,  # noqa
+                        evidence_count, is_identity, is_major_trigger,
+                        writeback_decision, writeback_gate)
+from .history import history_rows  # noqa
+from .snapshot import identity_snapshot  # noqa