apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/graph/client.py

@@ -0,0 +1,2483 @@
+"""Colony Graph Memory System — Neo4j async client.
+
+Replaces Hermes MEMORY.md with a persistent graph database that models
+relationships, events, and behavioral patterns.
+"""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import hashlib
+import json
+import logging
+import math
+import os
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Coroutine, Dict, List, Optional, TYPE_CHECKING
+
+try:
+    from neo4j import AsyncGraphDatabase, AsyncDriver
+except ImportError:
+    pass
+from pydantic import SecretStr
+
+if TYPE_CHECKING:
+    from apsimo.vector.store import VectorStore
+
+logger = logging.getLogger(__name__)
+
+
+def _recency_factor(days_old: float) -> float:
+    """Recency weight for retrieval ranking (v0.21.0).
+
+    Configurable exponential half-life with a floor, so recent memories surface
+    over stale ones without fully suppressing older context. Defaults:
+    half-life 90d, floor 0.5 (a year-old memory keeps ~0.53 weight; fresh = 1.0).
+    Set COLONY_RECENCY_HALF_LIFE_DAYS<=0 to disable. The previous behaviour was a
+    near-flat ~10%/year discount that barely affected ranking.
+    """
+    import os
+    try:
+        half_life = float(os.environ.get("COLONY_RECENCY_HALF_LIFE_DAYS", "90"))
+    except (ValueError, TypeError):
+        half_life = 90.0
+    if half_life <= 0:
+        return 1.0
+    try:
+        floor = float(os.environ.get("COLONY_RECENCY_FLOOR", "0.5"))
+    except (ValueError, TypeError):
+        floor = 0.5
+    floor = min(max(floor, 0.0), 1.0)
+    return floor + (1.0 - floor) * (0.5 ** (max(days_old, 0.0) / half_life))
+
+
+def distill_turn_summary(summary: str) -> str:
+    """The distilled form of a turn summary (what COLONY_DISTILL_TURNS=1 stores).
+
+    PRESERVES BOTH speaker labels ("User:" and "Agent:", with "assistant"
+    normalized to "Agent:"). Attribution matters in both directions:
+    "User: my X is Y" says whose preference it is, and "Agent: ..." marks
+    the agent's own prose so downstream consumers (e.g. the belief claim
+    extractor) never mistake something the agent SAID for a fact a contact
+    ASSERTED. Lines are joined with "; " — this text is injected into
+    prompts, so it must never introduce an em dash.
+    """
+    _lines = []
+    for ln in (summary or "").splitlines():
+        if ":" in ln:
+            _speaker, _rest = ln.split(":", 1)
+            _rest = _rest.strip()
+            sp = _speaker.strip().lower()
+            if sp == "user" and _rest:
+                _lines.append(f"User: {_rest}")
+            elif sp in ("agent", "assistant") and _rest:
+                _lines.append(f"Agent: {_rest}")
+            else:
+                _lines.append(_rest)
+        else:
+            _lines.append(ln)
+    return "; ".join(x for x in _lines if x) or (summary or "")
+
+
+@dataclass
+class GraphConfig:
+    """Connection settings for the Neo4j graph database."""
+
+    uri: str = "bolt://localhost:7687"
+    database: str = "colony"
+    auth: Optional[tuple[str, SecretStr]] = None  # (user, password) — password masked in logs
+    max_pool_size: int = 50
+    connection_timeout_secs: float = 10.0
+    max_retry_secs: float = 30.0
+
+
+class MemorySourceType(str, Enum):
+    CONVERSATION = "conversation"
+    FILE = "file"
+    TOOL_OUTPUT = "tool_output"
+    USER_ASSERTION = "user_assertion"
+    INFERENCE = "inference"
+
+
+class EpistemicState(str, Enum):
+    INFERRED = "inferred"
+    OBSERVED = "observed"
+    CORROBORATED = "corroborated"
+    VERIFIED = "verified"
+    STALE = "stale"
+    SUPERSEDED = "superseded"
+    DEPRECATED = "deprecated"
+    ARCHIVED = "archived"
+
+
+SOURCE_RELIABILITY: Dict[str, float] = {
+    MemorySourceType.USER_ASSERTION: 1.0,
+    MemorySourceType.FILE: 0.9,
+    MemorySourceType.TOOL_OUTPUT: 0.85,
+    MemorySourceType.CONVERSATION: 0.7,
+    MemorySourceType.INFERENCE: 0.5,
+}
+
+MAX_IMPORTANCE: Dict[str, float] = {
+    MemorySourceType.USER_ASSERTION: 1.0,
+    MemorySourceType.FILE: 0.95,
+    MemorySourceType.TOOL_OUTPUT: 0.9,
+    MemorySourceType.CONVERSATION: 0.8,
+    MemorySourceType.INFERENCE: 0.7,
+}
+
+
+class ColonyGraph:
+    """Neo4j graph memory system replacing Hermes MEMORY.md.
+
+    Provides:
+    - Memory storage with automatic entity linking
+    - Semantic recall via vector index + strength decay
+    - Ebbinghaus forgetting‐curve decay
+    - Pruning of weak / stale memories
+    - Multi-hop traversal across memory connections
+    """
+
+    def __init__(self, config: GraphConfig) -> None:
+        self._config = config
+        driver_auth = (
+            (config.auth[0], config.auth[1].get_secret_value())
+            if config.auth is not None
+            else None
+        )
+        self.driver: AsyncDriver = AsyncGraphDatabase.driver(
+            config.uri,
+            auth=driver_auth,
+            max_connection_pool_size=config.max_pool_size,
+            connection_timeout=config.connection_timeout_secs,
+            max_transaction_retry_time=config.max_retry_secs,
+            keep_alive=True,
+            # Suppress benign DBMS notifications (unknown-label/property warnings
+            # for nodes not yet created) — pure log noise, not errors.
+            notifications_min_severity="OFF",
+        )
+        self.database: str = config.database
+        self._embed_fn: Optional[
+            Callable[[str], Coroutine[Any, Any, List[float]]]
+        ] = None
+        self._vector_store: Optional["VectorStore"] = None
+        self._rerank_fn: Optional[Callable[..., Coroutine[Any, Any, Any]]] = None
+        # Runtime-wide hard exclusions protect untyped recall consumers (for
+        # example model tools and background synthesis) that cannot safely
+        # render a governed source directly. Empty preserves legacy behavior.
+        self._recall_source_exclusions: tuple[str, ...] = ()
+        self._recall_metadata_exclusions: tuple[str, ...] = ()
+
+    @staticmethod
+    def _bounded_source_uris(source_uris) -> tuple[str, ...]:
+        """Normalize a small exact-match source-URI exclusion set."""
+        return tuple(sorted(dict.fromkeys(
+            str(value).strip() for value in (source_uris or ())
+            if 0 < len(str(value).strip()) <= 256
+        )))[:16]
+
+    def set_recall_source_exclusions(
+        self,
+        source_uris,
+        *,
+        legacy_metadata_markers=(),
+    ) -> None:
+        """Set graph-wide hard recall exclusions for runtime policy.
+
+        Per-call exclusions are additive and can never relax this boundary.
+        ``legacy_metadata_markers`` covers rows written before a governed
+        source URI existed. Both sets are bounded exact strings; passing empty
+        iterables restores the historical default behavior.
+        """
+        self._recall_source_exclusions = self._bounded_source_uris(source_uris)
+        self._recall_metadata_exclusions = self._bounded_source_uris(
+            legacy_metadata_markers)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Verify connectivity to Neo4j."""
+        await self.driver.verify_connectivity()
+
+    async def ensure_colony_self(self) -> None:
+        """Ensure Colony's self-representation exists in the graph (v0.11.0).
+
+        Creates an Agent node for Colony with DEPENDS_ON edges to
+        known Subsystem nodes. Idempotent — safe to call multiple times.
+        """
+        try:
+            async with self.driver.session(database=self.database) as session:
+                # Create Agent node
+                await session.run("""
+                    MERGE (a:Agent {id: 'colony-sidecar'})
+                    SET a.name = 'Colony',
+                        a.version = '0.11.1',
+                        a.status = 'active',
+                        a.created_at = coalesce(a.created_at, datetime())
+                """)
+
+                # Create Subsystem nodes for known components
+                subsystems = [
+                    ("embed_pipeline", "Embedding Pipeline"),
+                    ("delivery_bridge", "Delivery Bridge"),
+                    ("event_bus", "Event Bus"),
+                    ("graph_client", "Graph Client"),
+                    ("initiative_engine", "Initiative Engine"),
+                    ("mind_model", "Mind Model"),
+                ]
+                for sub_id, sub_name in subsystems:
+                    await session.run("""
+                        MERGE (s:Subsystem {id: $id})
+                        SET s.name = $name,
+                            s.status = coalesce(s.status, 'active'),
+                            s.created_at = coalesce(s.created_at, datetime())
+                    """, id=sub_id, name=sub_name)
+
+                    # Create DEPENDS_ON edge from Agent to Subsystem
+                    await session.run("""
+                        MATCH (a:Agent {id: 'colony-sidecar'}), (s:Subsystem {id: $id})
+                        MERGE (a)-[r:DEPENDS_ON]->(s)
+                        SET r.created_at = coalesce(r.created_at, datetime())
+                    """, id=sub_id)
+
+                logger.info("Colony self-representation verified in graph")
+        except Exception as e:
+            logger.warning("Failed to ensure Colony self-representation: %s", e)
+
+    async def close(self) -> None:
+        """Cleanly shut down the driver."""
+        await self.driver.close()
+
+    # ------------------------------------------------------------------
+    # Embedding helper
+    # ------------------------------------------------------------------
+
+    def set_embed_fn(
+        self,
+        fn: Callable[[str], Coroutine[Any, Any, List[float]]],
+    ) -> None:
+        """Register an async embedding function used by *recall*.
+
+        Args:
+            fn: async callable that maps a string to a float vector.
+        """
+        self._embed_fn = fn
+        owner = getattr(fn, '__self__', None)
+        self._embed_query_fn = getattr(owner, 'embed_query', None)
+
+    def set_vector_store(self, store: "VectorStore") -> None:
+        """Register a VectorStore for ANN search (replaces Neo4j vector index)."""
+        self._vector_store = store
+
+    def set_rerank_fn(
+        self,
+        fn: Callable[..., Coroutine[Any, Any, Any]],
+        *,
+        calibration_metadata: Optional[Callable[[], Dict[str, Any]]] = None,
+    ) -> None:
+        """Register an async rerank function used by *recall* (mirrors
+        :meth:`set_embed_fn`).
+
+        Args:
+            fn: async callable ``fn(query, documents, top_k=N)`` returning a
+                list of objects with ``index`` and ``score`` attributes (the
+                RerankerProvider.rerank contract). Only consulted when
+                COLONY_RECALL_RERANK is ``shadow`` or ``on``.
+            calibration_metadata: current provider/model/format configuration.
+                Optional calibrated abstention is invalidated when this changes.
+        """
+        self._rerank_fn = fn
+        self._rerank_calibration_metadata = calibration_metadata
+        self._recall_selector = None
+
+    def set_adaptive_params(self, params: Any) -> None:
+        """Register an AdaptiveParamStore consulted by *recall* for the
+        meta-learned relevance floor (recall.min_relevance)."""
+        self._adaptive_params = params
+
+    async def _embed(self, text: str) -> List[float]:
+        """Produce an embedding vector for *text* (document side).
+
+        Raises:
+            RuntimeError: If no embedding function has been registered.
+        """
+        if self._embed_fn is None:
+            raise RuntimeError(
+                "No embedding function registered. Call set_embed_fn() first."
+            )
+        return await self._embed_fn(text)
+
+    async def _embed_query(self, query: str) -> List[float]:
+        """Embed a *query* for retrieval (v0.21.1).
+
+        Instruct-tuned embedders (Qwen3-Embedding, E5, BGE, …) are ASYMMETRIC:
+        the query gets an instruction prefix while documents do not. Without it,
+        retrieval quality collapses (every result lands at ~0.9 cosine distance
+        and the right memory never surfaces). Configurable via
+        COLONY_EMBED_QUERY_INSTRUCTION (set to empty for symmetric models).
+        """
+        if callable(getattr(self, '_embed_query_fn', None)):
+            return await self._embed_query_fn(query)
+        import os
+        default_instr = ("Instruct: Given a search query, retrieve relevant "
+                         "memories that answer it\nQuery: ")
+        instr = os.environ.get("COLONY_EMBED_QUERY_INSTRUCTION", default_instr)
+        return await self._embed((instr + query) if instr else query)
+
+    @staticmethod
+    def compute_effective_confidence(
+        base_confidence: float,
+        source_reliability: float,
+        corroboration_count: int,
+        contradiction_count: int,
+        recalls: int,
+        last_verified_at: Optional[Any],
+        created_at: Any,
+        epistemic_state: str,
+        now: Any,
+    ) -> float:
+        """Compute effective confidence from multiple signals.
+
+        Args:
+            base_confidence: Initial confidence (0-1)
+            source_reliability: Reliability of the source (0-1)
+            corroboration_count: Number of corroborating memories
+            contradiction_count: Number of contradicting memories
+            recalls: Number of times recalled
+            last_verified_at: Last verification timestamp or None
+            created_at: Creation timestamp
+            epistemic_state: Current epistemic state string
+            now: Current timestamp
+
+        Returns:
+            Effective confidence in [0, 1].
+        """
+        from datetime import datetime as _dt, timezone as _tz
+
+        if now is None:
+            now = _dt.now(_tz.utc)
+        if hasattr(now, "to_native"):
+            now = now.to_native()
+        if isinstance(now, str):
+            now = _dt.fromisoformat(now.replace("Z", "+00:00"))
+        if hasattr(created_at, "to_native"):
+            created_at = created_at.to_native()
+        if isinstance(created_at, str):
+            created_at = _dt.fromisoformat(created_at.replace("Z", "+00:00"))
+
+        # Source weight
+        confidence = base_confidence * source_reliability
+
+        # Corroboration / contradiction adjustment
+        net_support = corroboration_count - contradiction_count
+        confidence *= min(1.0, 1.0 + net_support * 0.1)
+
+        # Recall reinforcement (diminishing returns)
+        confidence *= min(1.3, 1.0 + recalls * 0.03)
+
+        # Recency weighting (v0.21.0, configurable half-life + floor — see
+        # _recency_factor). Recent memories surface; VERIFIED memories are
+        # additionally floored at 0.9 by the epistemic-state clamp below.
+        days_old = max(0, (now - created_at).days)
+        recency_factor = _recency_factor(days_old)
+        confidence *= recency_factor
+
+        # Verification boost
+        if last_verified_at:
+            if hasattr(last_verified_at, "to_native"):
+                last_verified_at = last_verified_at.to_native()
+            if isinstance(last_verified_at, str):
+                last_verified_at = _dt.fromisoformat(last_verified_at.replace("Z", "+00:00"))
+            if (now - last_verified_at).days < 7:
+                confidence *= 1.2
+
+        # State clamp
+        if epistemic_state == EpistemicState.VERIFIED.value:
+            confidence = max(confidence, 0.9)
+        elif epistemic_state in (EpistemicState.STALE.value, EpistemicState.SUPERSEDED.value):
+            confidence *= 0.3
+        elif epistemic_state == EpistemicState.DEPRECATED.value:
+            confidence *= 0.1
+
+        return min(1.0, max(0.0, confidence))
+
+    # ------------------------------------------------------------------
+    # Core operations
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _source_projection_erased(source_uri: str | None) -> bool:
+        if not source_uri or not source_uri.startswith("turn:"):
+            return False
+        from apsimo import get_state_dir
+        from apsimo.turns import get_turn_idempotency_ledger
+        return get_turn_idempotency_ledger(get_state_dir()).is_projection_erased(source_uri[5:])
+
+    async def _filter_erased_source_memories(self, memories: list[dict]) -> list[dict]:
+        """A durable erase fence remains effective during projection outages."""
+        return [memory for memory in memories
+                if not self._source_projection_erased(memory.get("source_uri"))]
+
+    async def delete_source_memories(self, turn_ids: list[str]) -> int:
+        """Remove graph and vector copies after the source fence commits."""
+        uris = ["turn:" + item for item in dict.fromkeys(turn_ids)]
+        if not uris:
+            return 0
+        # Keep IDs until both stores have been addressed. The graph's source
+        # tombstone filter blocks recall even if vector deletion must be retried.
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run("MATCH (m:Memory) WHERE m.source_uri IN $uris RETURN m.id AS id", uris=uris)
+            ids = [record["id"] async for record in result]
+        for memory_id in ids:
+            if self._vector_store is not None:
+                from apsimo.vector.collections import Collection
+                await self._vector_store.delete(collection=Collection.MEMORIES, id=memory_id)
+            async with self.driver.session(database=self.database) as session:
+                await session.run("MATCH (m:Memory {id: $id}) DETACH DELETE m", id=memory_id)
+        ring = getattr(self, "_distill_preview", None)
+        if ring is not None:
+            retained = [item for item in ring if item.get("source_turn_id") not in turn_ids]
+            ring.clear()
+            ring.extend(retained)
+        return len(ids)
+
+    async def iter_indexable_memories(self, batch_size: int = 128):
+        """Current graph evidence for a projection rebuild, without old vectors."""
+        after = ''
+        while True:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run('''
+                    MATCH (m:Memory) WHERE m.id > $after
+                    WITH m ORDER BY m.id LIMIT $limit
+                    OPTIONAL MATCH (m)-[:ABOUT]->(p:Person)
+                    RETURN properties(m) AS memory, collect(p.id) AS people
+                    ORDER BY memory.id
+                ''', after=after, limit=batch_size)
+                rows = [dict(row) async for row in result]
+            if not rows:
+                return
+            for row in rows:
+                memory = row['memory']
+                after = memory['id']
+                if self._source_projection_erased(memory.get('source_uri')):
+                    continue
+                if memory.get('superseded_by') or not memory.get('content'):
+                    continue
+                metadata = memory.get('metadata') or {}
+                if isinstance(metadata, str):
+                    try:
+                        metadata = json.loads(metadata)
+                    except json.JSONDecodeError:
+                        # Earlier store_memory writers used str(dict), not JSON.
+                        # Read those retained records without rewriting evidence.
+                        metadata = ast.literal_eval(metadata)
+                if not isinstance(metadata, dict):
+                    raise ValueError('Graph memory metadata must be an object')
+                metadata = {**metadata, **{key: memory.get(key) for key in
+                    ('source_uri', 'source_type', 'source_version', 'content_hash', 'session_id',
+                     'type', 'strength', 'effective_confidence', 'epistemic_state', 'protected')}}
+                metadata['person_id'] = (row['people'] or [None])[0]
+                metadata['memory_id'] = memory['id']
+                yield {'id': memory['id'], 'text': memory['content'], 'metadata': metadata}
+
+    async def store_memory(
+        self,
+        content: str,
+        memory_type: str,
+        entities: List[str],
+        metadata: Dict[str, Any] | None = None,
+        importance: float = 1.0,
+        person_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        source_type: str = "inference",
+        source_uri: Optional[str] = None,
+        source_version: Optional[str] = None,
+        content_hash: Optional[str] = None,
+    ) -> str:
+        """Store a memory with automatic entity linking.
+
+        Creates a :Memory node and :MENTIONS edges to each :Entity.
+        If an embedding function is registered the memory's vector is stored
+        on the node so it participates in semantic search.
+
+        Args:
+            content: Memory content text
+            memory_type: Type of memory (episodic, semantic, procedural, identity)
+            entities: Named entities to link to this memory
+            metadata: Optional key-value metadata
+            importance: Initial importance / strength (0-1, default 1.0)
+            person_id: Optional person ID to link this memory to via (Memory)-[:ABOUT]->(Person)
+            source_type: Origin of this memory (conversation, file, tool_output, user_assertion, inference)
+            source_uri: Optional URI referencing the source
+            source_version: Optional version string for the source
+            content_hash: Optional SHA-256 hash of the content
+
+        Returns:
+            The UUID of the newly created Memory node.
+        """
+        metadata = metadata or {}
+        if self._source_projection_erased(source_uri):
+            return ""
+        # Guard (v0.21.1): never store empty/whitespace memories — they were
+        # accumulating as duplicate junk nodes.
+        if not content or not content.strip():
+            return ""
+        max_importance = MAX_IMPORTANCE.get(source_type, 0.7)
+        if importance > max_importance:
+            logger.warning(
+                "Importance %.2f for source_type '%s' exceeds max %.2f; clamping.",
+                importance, source_type, max_importance,
+            )
+            importance = max_importance
+        importance = max(0.0, min(1.0, importance))
+
+        # Resolve person_id from explicit arg or metadata fallback
+        person_id = person_id or metadata.get("person_id")
+        # Never mint a :Person node for a non-contact sentinel. Ids like 'default'/'unknown'/empty are
+        # NOT real people; attributing memories to them created a catch-all junk Person that polluted
+        # per-person recall (a host whose resolver fell back to "default" dumped most of its memory
+        # onto one pseudo-contact). Such memories are stored UNATTRIBUTED (no :ABOUT edge) instead.
+        # Real contact ids still create/link a Person normally (that is the graph's discovery design).
+        if isinstance(person_id, str):
+            person_id = person_id.strip() or None
+            if person_id and person_id.lower() in {"default", "unknown", "none", "null", "anonymous"}:
+                person_id = None
+        elif person_id is not None:
+            person_id = None
+        # Resolve session_id from explicit arg or metadata fallback
+        session_id = session_id or (metadata.get("session_id") if metadata else None)
+
+        source_type = (source_type or MemorySourceType.INFERENCE.value).lower()
+        source_uri = source_uri or None
+        source_version = source_version or None
+        # Always derive a content hash so identical memories can be deduped
+        # (v0.21.1 — previously null, so every write created a duplicate node).
+        content_hash = content_hash or hashlib.sha256(content.encode("utf-8")).hexdigest()
+        source_reliability = SOURCE_RELIABILITY.get(source_type, 0.5)
+        protected = source_type == MemorySourceType.USER_ASSERTION
+        base_confidence = importance
+        epistemic_state = EpistemicState.INFERRED
+        created_at = self._utcnow()
+
+        effective_confidence = self.compute_effective_confidence(
+            base_confidence=base_confidence,
+            source_reliability=source_reliability,
+            corroboration_count=0,
+            contradiction_count=0,
+            recalls=0,
+            last_verified_at=None,
+            created_at=created_at,
+            epistemic_state=epistemic_state.value,
+            now=created_at,
+        )
+
+        # Dedup (v0.21.1): if an identical memory already exists (same content
+        # hash), reinforce it instead of creating a duplicate — and skip the
+        # embed cost entirely. This collapses the runaway duplication (e.g. a
+        # recurring cron prompt that had been stored 70+ times).
+        if content_hash:
+            async with self.driver.session(database=self.database) as session:
+                dq = await session.run(
+                    """
+                    MATCH (m:Memory {content_hash: $content_hash})
+                    WHERE m.superseded_by IS NULL
+                      AND ($source_uri IS NULL OR m.source_uri = $source_uri)
+                    SET m.accessed_at = datetime(),
+                        m.corroboration_count = coalesce(m.corroboration_count, 0) + 1,
+                        m.strength = CASE WHEN coalesce(m.strength, 0.0) < 1.0
+                                          THEN coalesce(m.strength, 0.0) + 0.05 ELSE 1.0 END
+                    RETURN m.id AS id
+                    ORDER BY m.created_at ASC
+                    LIMIT 1
+                    """,
+                    content_hash=content_hash,
+                    source_uri=source_uri,
+                )
+                existing = await dq.single()
+                if existing is not None:
+                    logger.debug("store_memory dedup: reinforced %s", existing["id"])
+                    return existing["id"]
+
+        # Compute embedding. If an embedder is configured but we can't get a
+        # usable vector (outage that survived retries), FAIL the write rather than
+        # create an unsearchable memory (silent loss). The vector lives in the
+        # LanceDB store; the Neo4j m.embedding property is secondary/best-effort.
+        embedding: Optional[List[float]] = None
+        if self._embed_fn is not None:
+            embedding = await self._embed(content)
+            if not embedding:
+                raise RuntimeError(
+                    "embedding unavailable — refusing to store unsearchable memory")
+
+        # Preserve dict for vector store before stringifying for Neo4j
+        metadata_dict = metadata
+        metadata_str = json.dumps(metadata_dict, default=str)
+
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(
+                """
+                CREATE (m:Memory {
+                    id: randomUUID(),
+                    content: $content,
+                    type: $memory_type,
+                    importance: $importance,
+                    strength: $importance,
+                    recalls: 0,
+                    created_at: datetime(),
+                    accessed_at: datetime(),
+                    embedding: $embedding,
+                    metadata: $metadata,
+                    session_id: $session_id,
+                    source_type: $source_type,
+                    source_uri: $source_uri,
+                    source_version: $source_version,
+                    content_hash: $content_hash,
+                    base_confidence: $base_confidence,
+                    source_reliability: $source_reliability,
+                    corroboration_count: 0,
+                    contradiction_count: 0,
+                    effective_confidence: $effective_confidence,
+                    epistemic_state: $epistemic_state,
+                    protected: $protected,
+                    last_verified_at: null,
+                    superseded_by: null,
+                    provenance: []
+                })
+                WITH m
+                FOREACH (entity_name IN $entities |
+                    MERGE (e:Entity {name: entity_name})
+                    CREATE (m)-[:MENTIONS]->(e)
+                )
+                WITH m
+                FOREACH (_ IN CASE WHEN $person_id IS NOT NULL THEN [1] ELSE [] END |
+                    MERGE (p:Person {id: $person_id})
+                    CREATE (m)-[:ABOUT]->(p)
+                )
+                WITH m
+                FOREACH (_ IN CASE WHEN $source_uri IS NOT NULL AND $source_type = "file" THEN [1] ELSE [] END |
+                    MERGE (fa:FileAnchor {uri: $source_uri})
+                    ON CREATE SET fa.first_seen = datetime()
+                    CREATE (m)-[:DERIVED_FROM {derivation_type: "file_read"}]->(fa)
+                )
+                RETURN m.id AS id
+                """,
+                content=content,
+                memory_type=memory_type,
+                importance=importance,
+                entities=entities,
+                embedding=embedding,
+                metadata=metadata_str,
+                person_id=person_id,
+                session_id=session_id,
+                source_type=source_type,
+                source_uri=source_uri,
+                source_version=source_version,
+                content_hash=content_hash,
+                base_confidence=base_confidence,
+                source_reliability=source_reliability,
+                effective_confidence=effective_confidence,
+                epistemic_state=epistemic_state,
+                protected=protected,
+            )
+            record = await result.single()
+            if record is None:
+                raise RuntimeError("Failed to create memory node")
+            memory_id = record["id"]
+
+        # Write to LanceDB vector store (if configured)
+        if self._vector_store is not None and embedding is not None:
+            try:
+                from apsimo.vector.collections import Collection
+                await self._vector_store.add(
+                    collection=Collection.MEMORIES,
+                    id=memory_id,
+                    text=content,
+                    vector=embedding,
+                    metadata={
+                        "memory_id": memory_id,
+                        "type": memory_type,
+                        "strength": importance,
+                        "importance": importance,
+                        # Keep the vector candidate's scope aligned with the
+                        # authoritative graph ABOUT edge. Historically this
+                        # read only metadata["person_id"], so callers using the
+                        # explicit argument produced unscoped vector rows.
+                        "person_id": person_id,
+                        "tags": metadata_dict.get("tags", []) if metadata_dict else [],
+                        "created_at": metadata_dict.get("created_at") if metadata_dict else None,
+                        "session_id": session_id,
+                        "source_type": source_type,
+                        "source_uri": source_uri,
+                        "source_version": source_version,
+                        "content_hash": content_hash,
+                        "effective_confidence": effective_confidence,
+                        "epistemic_state": epistemic_state.value,
+                        "protected": protected,
+                    },
+                )
+            except Exception as exc:
+                logger.warning("Failed to write memory to vector store: %s", exc)
+
+        # A deletion may have committed while embedding or graph I/O awaited.
+        if self._source_projection_erased(source_uri):
+            await self.delete_source_memories([source_uri[5:]])
+            return ""
+        return memory_id
+
+    def _distill_preview_ring(self) -> "deque":
+        """Bounded ring of shadow distill previews (created on first use so
+        alternate construction paths, e.g. tests, still work)."""
+        ring = getattr(self, "_distill_preview", None)
+        if ring is None:
+            ring = deque(maxlen=50)
+            self._distill_preview = ring
+        return ring
+
+    def distill_preview(self) -> List[Dict[str, Any]]:
+        """Newest-first shadow distill previews (empty once the flag is live)."""
+        return list(reversed(self._distill_preview_ring()))
+
+    async def record_turn(
+        self,
+        session_id: str,
+        contact_id: Optional[str],
+        topics: List[str],
+        entities: List[str],
+        tools_used: List[str],
+        summary: Optional[str],
+        turn_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """Store a conversation turn as an episodic memory.
+
+        Creates a :Memory node of type ``episodic`` linked to the
+        conversation session and contact.  Entities and topics are
+        merged as :Entity nodes.  Tools used are stored in metadata.
+
+        Args:
+            session_id: Hermes session identifier
+            contact_id: Optional contact / person identifier
+            topics: Extracted topics from the turn
+            entities: Named entities mentioned
+            tools_used: Tool names invoked during the turn
+            summary: Human-readable summary of the exchange
+
+        Returns:
+            The UUID of the created Memory node, or None if storage fails.
+        """
+        if not summary or self._source_projection_erased("turn:" + turn_id if turn_id else None):
+            return None
+        # Salience gate: don't memorialize internal-plumbing turns (context-compaction references and
+        # host-specific system-prompt wrappers / self-checks). Generic markers are built in; a
+        # deployment adds its own via COLONY_MEMORY_SKIP_MARKERS ('|'-separated, case-insensitive).
+        # This is what keeps the memory graph facts-and-events, not a verbatim transcript log.
+        _sl = summary.lower()
+        _skip = ("[context compaction", "[post-compaction", "reference only]", "[context summary]")
+        _env = os.environ.get("COLONY_MEMORY_SKIP_MARKERS", "")
+        if any(m in _sl for m in _skip) or any(m.strip().lower() in _sl for m in _env.split("|") if m.strip()):
+            logger.debug("record_turn: skipped low-salience / internal-marker turn")
+            return None
+
+        # Real salience score (attribution redesign Phase 2), replacing the old hardcoded
+        # importance=0.85 that overrode the computed value. Signal from what the turn
+        # actually carries: named entities (facts about people/things), tool use (an
+        # action happened), and substance (length). A throwaway "ok thanks" scores low
+        # and decays fast; a fact-dense exchange scores high and persists.
+        _ent_n = len(entities or [])
+        _score = 0.35
+        _score += min(0.30, 0.10 * _ent_n)        # up to +0.30 for entities
+        if tools_used:
+            _score += 0.15                         # an action was taken
+        if len(summary) > 240:
+            _score += 0.10                         # substantive exchange
+        if "?" in summary:
+            _score += 0.05                         # a question = intent/curiosity worth recalling
+        importance = round(min(_score, 0.95), 3)
+
+        # Optional distillation (shadow by default): store the salient content rather
+        # than the verbatim "User:/Agent:" wrapper. The distilled form is ALWAYS
+        # computed; off => stored content is unchanged and the would-be result goes
+        # into a bounded in-memory preview ring (GET /v1/host/memory/distill-preview)
+        # so the flip can be validated on real traffic first. On => store it.
+        content = summary
+        distilled = distill_turn_summary(summary)
+        _distill = os.environ.get("COLONY_DISTILL_TURNS", "0") not in ("0", "false", "no")
+        if _distill:
+            content = distilled
+        else:
+            try:
+                self._distill_preview_ring().append({
+                    "session_id": session_id,
+                    "source_turn_id": turn_id,
+                    "original": summary[:400],
+                    "distilled": distilled[:400],
+                    "importance": importance,
+                    "ts": time.time(),
+                })
+            except Exception:
+                logger.debug("distill preview append failed", exc_info=True)
+            logger.debug("distill(shadow): would store salient content for session %s (imp=%.2f)",
+                         session_id, importance)
+
+        metadata: Dict[str, Any] = {
+            "turn": True,
+            "source_turn_id": turn_id,
+            "topics": topics,
+            "tools_used": tools_used,
+            "salience": importance,
+        }
+
+        try:
+            content_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()
+            return await self.store_memory(
+                content=content,
+                memory_type="episodic",
+                entities=entities or [],
+                metadata=metadata,
+                importance=importance,
+                person_id=contact_id,
+                source_type=MemorySourceType.CONVERSATION.value,
+                source_uri=f"turn:{turn_id}" if turn_id else f"session:{session_id}",
+                session_id=session_id,
+                content_hash=content_hash,
+            )
+        except Exception as exc:
+            logger.warning("record_turn failed: %s", exc)
+            return None
+
+    async def read_memories(
+        self,
+        *,
+        person_id: Optional[str] = None,
+        memory_id: Optional[str] = None,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        """Read recent memories, preserving the same hard ABOUT boundary as recall.
+
+        ``person_id`` is intentionally a single exact lane. A scoped miss is
+        empty and never retries against the unscoped graph. Omitting the person
+        remains only for the deprecated legacy/internal authority path; the API
+        boundary always supplies a server-derived person for scoped callers.
+        """
+
+        person_scope = str(person_id).strip() if person_id else None
+        memory_scope = str(memory_id).strip() if memory_id else None
+        safe_limit = max(1, min(int(limit or 20), 100))
+        excluded_sources = getattr(self, "_recall_source_exclusions", ())
+        excluded_metadata_markers = getattr(
+            self, "_recall_metadata_exclusions", ())
+        policy_active = bool(
+            excluded_sources or excluded_metadata_markers)
+        async with self.driver.session(database=self.database) as session:
+            if person_scope:
+                if policy_active:
+                    result = await session.run(
+                        """
+                        MATCH (m:Memory)-[:ABOUT]->(:Person {id: $person_id})
+                        WHERE ($memory_id IS NULL OR m.id = $memory_id)
+                          AND (size($exclude_source_uris) = 0 OR NOT (
+                            coalesce(m.source_uri, "") IN
+                            $exclude_source_uris))
+                          AND (size($exclude_metadata_markers) = 0 OR
+                            NONE(marker IN $exclude_metadata_markers
+                              WHERE toLower(coalesce(m.metadata, ""))
+                                CONTAINS marker))
+                        OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                        WITH m, collect(DISTINCT e.name) AS entity_names
+                        RETURN m {.*, entities: entity_names,
+                                  person_id: $person_id} AS memory
+                        ORDER BY m.created_at DESC
+                        LIMIT $limit
+                        """,
+                        person_id=person_scope,
+                        memory_id=memory_scope,
+                        limit=safe_limit,
+                        exclude_source_uris=excluded_sources,
+                        exclude_metadata_markers=excluded_metadata_markers,
+                    )
+                else:
+                    result = await session.run(
+                        """
+                        MATCH (m:Memory)-[:ABOUT]->(:Person {id: $person_id})
+                        WHERE $memory_id IS NULL OR m.id = $memory_id
+                        OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                        WITH m, collect(DISTINCT e.name) AS entity_names
+                        RETURN m {.*, entities: entity_names,
+                                  person_id: $person_id} AS memory
+                        ORDER BY m.created_at DESC
+                        LIMIT $limit
+                        """,
+                        person_id=person_scope,
+                        memory_id=memory_scope,
+                        limit=safe_limit,
+                    )
+            else:
+                if policy_active:
+                    result = await session.run(
+                        """
+                        MATCH (m:Memory)
+                        WHERE ($memory_id IS NULL OR m.id = $memory_id)
+                          AND (size($exclude_source_uris) = 0 OR NOT (
+                            coalesce(m.source_uri, "") IN
+                            $exclude_source_uris))
+                          AND (size($exclude_metadata_markers) = 0 OR
+                            NONE(marker IN $exclude_metadata_markers
+                              WHERE toLower(coalesce(m.metadata, ""))
+                                CONTAINS marker))
+                        OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                        OPTIONAL MATCH (m)-[:ABOUT]->(p:Person)
+                        WITH m, collect(DISTINCT e.name) AS entity_names,
+                             collect(DISTINCT p.id) AS person_ids
+                        RETURN m {.*, entities: entity_names,
+                                  person_id: head(person_ids)} AS memory
+                        ORDER BY m.created_at DESC
+                        LIMIT $limit
+                        """,
+                        memory_id=memory_scope,
+                        limit=safe_limit,
+                        exclude_source_uris=excluded_sources,
+                        exclude_metadata_markers=excluded_metadata_markers,
+                    )
+                else:
+                    result = await session.run(
+                        """
+                        MATCH (m:Memory)
+                        WHERE $memory_id IS NULL OR m.id = $memory_id
+                        OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                        OPTIONAL MATCH (m)-[:ABOUT]->(p:Person)
+                        WITH m, collect(DISTINCT e.name) AS entity_names,
+                             collect(DISTINCT p.id) AS person_ids
+                        RETURN m {.*, entities: entity_names,
+                                  person_id: head(person_ids)} AS memory
+                        ORDER BY m.created_at DESC
+                        LIMIT $limit
+                        """,
+                        memory_id=memory_scope,
+                        limit=safe_limit,
+                    )
+            memories: List[Dict[str, Any]] = []
+            async for record in result:
+                memories.append(dict(record["memory"]))
+            return await self._filter_erased_source_memories(memories)
+
+    def _memory_is_recall_excluded(self, memory: Dict[str, Any]) -> bool:
+        if self._source_projection_erased(memory.get("source_uri")):
+            return True
+        sources = set(getattr(self, "_recall_source_exclusions", ()))
+        if str(memory.get("source_uri") or "") in sources:
+            return True
+        metadata = memory.get("metadata")
+        raw_metadata = str(
+            memory if metadata is None else metadata).lower()
+        return any(
+            marker in raw_metadata
+            for marker in getattr(self, "_recall_metadata_exclusions", ())
+        )
+
+    async def filter_memory_vector_results(
+        self,
+        rows: List[Dict[str, Any]],
+    ) -> List[Dict[str, Any]]:
+        """Apply the graph's hard content policy to raw vector result text.
+
+        Vector metadata catches current mirrors cheaply. Ambiguous/legacy rows
+        are hydrated by ID so their authoritative graph metadata is checked.
+        Non-graph vectors (for example image captions) remain available.
+        """
+        rows = [row for row in rows if not self._source_projection_erased(
+            row.get("source_uri") or (row.get("metadata") or {}).get("source_uri"))]
+        if not (
+            getattr(self, "_recall_source_exclusions", ())
+            or getattr(self, "_recall_metadata_exclusions", ())
+        ):
+            return rows
+
+        candidates = [row for row in rows[:512] if isinstance(row, dict)]
+        ids = tuple(dict.fromkeys(
+            str(row.get("id") or "").strip() for row in candidates
+            if str(row.get("id") or "").strip()
+        ))
+        graph_rows: Dict[str, Dict[str, Any]] = {}
+        if ids:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    """
+                    MATCH (m:Memory) WHERE m.id IN $ids
+                    RETURN m {.*} AS memory
+                    """,
+                    ids=ids,
+                )
+                async for record in result:
+                    memory = dict(record["memory"])
+                    mid = str(memory.get("id") or "")
+                    if mid:
+                        graph_rows[mid] = memory
+
+        allowed: List[Dict[str, Any]] = []
+        for row in candidates:
+            mid = str(row.get("id") or "").strip()
+            if not mid:
+                continue
+            vector_metadata = row.get("metadata")
+            vector_view = dict(vector_metadata) if isinstance(
+                vector_metadata, dict) else {"metadata": vector_metadata}
+            if self._memory_is_recall_excluded(vector_view):
+                continue
+            graph_view = graph_rows.get(mid)
+            if graph_view is not None and self._memory_is_recall_excluded(
+                graph_view
+            ):
+                continue
+            if graph_view is None:
+                metadata = (
+                    vector_metadata
+                    if isinstance(vector_metadata, dict) else {}
+                )
+                modality = str(metadata.get("modality") or "").lower()
+                source_uri = str(metadata.get("source_uri") or "").strip()
+                # Missing graph hydration is not authority for ambiguous text.
+                # Preserve explicit non-graph media and text with an identified,
+                # non-excluded source; unknown text fails closed.
+                if modality != "image" and not source_uri:
+                    continue
+            allowed.append(row)
+        return allowed
+
+    async def recall_candidates(self, **kwargs):
+        """Authorized graph candidates without reranking or reinforcement."""
+        return await self.recall(**kwargs, candidates_only=True)
+
+    def record_recall_use(self, memories):
+        """Reinforce only graph records that actually entered turn context."""
+        for memory in memories:
+            if memory.get("kind", "belief") == "belief" and memory.get("id"):
+                # Annotated packets have a presentation ID, separate from the
+                # graph record whose use should slow subsequent memory decay.
+                memory_id = memory.get("_recall_memory_id") or memory["id"]
+                self._retain_task(asyncio.create_task(
+                    self._touch_memory_safe(memory_id)))
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 10,
+        min_strength: Optional[float] = None,
+        min_confidence: float = 0.1,
+        person_id: Optional[str] = None,
+        exclude_source_uris: Optional[List[str]] = None,
+        *,
+        candidates_only: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Retrieve memories by semantic similarity with strength decay.
+
+        Uses LanceDB for ANN search, then hydrates full Memory nodes from
+        Neo4j with entity mentions.  Falls back to graph-only keyword
+        recall if no vector store or embedding function is configured.
+
+        ``min_strength`` is the hard exclusion floor for decayed memories.
+        An explicit caller value always wins; when omitted it comes from
+        COLONY_RECALL_MIN_STRENGTH (default 0.1, the historical floor).
+        The floor stays hard — decayed junk is excluded, not demoted — and
+        is only lowered stepwise as live pruning cleans the graph.
+
+        An explicit ``person_id`` is a hard candidate boundary: only memories
+        linked ``ABOUT`` that exact person may be hydrated or ranked. A scoped
+        miss stays empty and never falls back to global recall. Trusted owner
+        or internal callers that intentionally need global memory must omit
+        ``person_id`` after establishing that authority outside this method.
+
+        ``exclude_source_uris`` is a bounded hard hydration filter applied
+        before confidence/relevance ranking and reranking.  The ANN candidate
+        fetch is widened when this filter is present so excluded mirrors do
+        not ordinarily starve the requested result window.
+
+        ``candidates_only`` skips final reranking and recall-strength updates;
+        the caller must select authorized candidates and record actual use.
+
+        Returns:
+            A list of memory dicts, each annotated with ``entities`` and
+            sorted by relevance descending.
+        """
+        if min_strength is None:
+            try:
+                min_strength = float(os.environ.get(
+                    "COLONY_RECALL_MIN_STRENGTH", "0.1"))
+            except (TypeError, ValueError):
+                min_strength = 0.1
+        # Strength-blended ranking (COLONY_RECALL_STRENGTH_RANKING, default
+        # off = legacy vector_score * effective_confidence). When on, decayed
+        # memories are demoted smoothly ABOVE the hard floor:
+        # relevance = vector_score * effective_confidence * (0.5 + 0.5*strength)
+        strength_ranking = os.environ.get(
+            "COLONY_RECALL_STRENGTH_RANKING", "off").strip().lower() in (
+            "on", "1", "true", "yes")
+        person_scope = str(person_id).strip() if person_id else None
+        excluded_sources = self._bounded_source_uris((
+            *getattr(self, "_recall_source_exclusions", ()),
+            *(exclude_source_uris or ()),
+        ))
+        excluded_metadata_markers = self._bounded_source_uris(
+            getattr(self, "_recall_metadata_exclusions", ()))
+        hybrid = os.environ.get("COLONY_RECALL_HYBRID", "off").strip().lower() in (
+            "on", "1", "true", "yes")
+        # Vector search path: embed query (with instruction) → LanceDB ANN → Neo4j hydration
+        if self._vector_store is not None and self._embed_fn is not None:
+            try:
+                embedding = await self._embed_query(query)
+                from apsimo.vector.collections import Collection
+                # Oversample the ANN fetch (COLONY_RECALL_OVERSAMPLE, default 1
+                # = legacy exact-limit fetch) so the post-hydration filters
+                # (strength floor, terminal epistemic states, low confidence)
+                # can't silently shrink the result set below the requested
+                # limit. Oversampled fetches are capped at 100 candidates and
+                # trimmed back to `limit` after filtering.
+                try:
+                    oversample = int(os.environ.get(
+                        "COLONY_RECALL_OVERSAMPLE", "1"))
+                except (TypeError, ValueError):
+                    oversample = 1
+                fetch_limit = (limit if oversample <= 1
+                               else min(limit * oversample, max(100, limit)))
+                # Existing vector rows predate structured recipient metadata,
+                # so the authoritative scope check happens during Neo4j
+                # hydration. Widen scoped ANN candidate generation to reduce
+                # false-empty results without ever relaxing that graph gate.
+                if person_scope:
+                    try:
+                        scope_oversample = max(1, int(os.environ.get(
+                            "COLONY_RECALL_SCOPE_OVERSAMPLE", "20")))
+                    except (TypeError, ValueError):
+                        scope_oversample = 20
+                    fetch_limit = max(
+                        fetch_limit,
+                        min(limit * scope_oversample, max(200, limit)),
+                    )
+                elif excluded_sources or excluded_metadata_markers:
+                    fetch_limit = max(
+                        fetch_limit, min(limit * 20, max(200, limit)))
+                results = await self._vector_store.search(
+                    collection=Collection.MEMORIES,
+                    query_vector=embedding,
+                    limit=fetch_limit,
+                    # metadata is stored as a JSON string (pa.utf8()); LanceDB's
+                    # filter dialect does not support json_extract on utf8 columns.
+                    # Strength filtering is applied post-hydration from Neo4j below.
+                    filter=None,
+                )
+                # Adaptive relevance floor (meta-learning knob): vector hits
+                # scoring below recall.min_relevance are dropped before
+                # hydration. Default 0.0 = no filter; store caps at 0.5 so a
+                # self-adjustment can never starve retrieval.
+                min_relevance = 0.0
+                params = getattr(self, "_adaptive_params", None)
+                if params is not None:
+                    try:
+                        from apsimo.self_model.params import (
+                            PARAM_RECALL_MIN_RELEVANCE,
+                        )
+                        min_relevance = float(params.get(
+                            PARAM_RECALL_MIN_RELEVANCE, default=0.0))
+                    except Exception:
+                        min_relevance = 0.0
+                if min_relevance > 0.0:
+                    results = [r for r in results if r.score >= min_relevance]
+                memories = []
+                if results:
+                    memory_ids = [r.id for r in results]
+                    score_map = {r.id: r.score for r in results}
+
+                    # Hydrate from Neo4j
+                    async with self.driver.session(database=self.database) as session:
+                        if person_scope:
+                            result = await session.run(
+                                """
+                                MATCH (m:Memory)-[:ABOUT]->(:Person {id: $person_id})
+                                WHERE m.id IN $ids
+                                  AND (size($exclude_source_uris) = 0 OR NOT (
+                                    coalesce(m.source_uri, "") IN
+                                    $exclude_source_uris))
+                                  AND (size($exclude_metadata_markers) = 0 OR
+                                    NONE(marker IN $exclude_metadata_markers
+                                      WHERE toLower(coalesce(m.metadata, ""))
+                                        CONTAINS marker))
+                                OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                                WITH m, collect(e.name) AS entity_names
+                                RETURN m {.*, entities: entity_names,
+                                          person_id: $person_id} AS memory
+                                """,
+                                ids=memory_ids,
+                                person_id=person_scope,
+                                exclude_source_uris=excluded_sources,
+                                exclude_metadata_markers=(
+                                    excluded_metadata_markers),
+                            )
+                        else:
+                            result = await session.run(
+                                """
+                                MATCH (m:Memory) WHERE m.id IN $ids
+                                  AND (size($exclude_source_uris) = 0 OR NOT (
+                                    coalesce(m.source_uri, "") IN
+                                    $exclude_source_uris))
+                                  AND (size($exclude_metadata_markers) = 0 OR
+                                    NONE(marker IN $exclude_metadata_markers
+                                      WHERE toLower(coalesce(m.metadata, ""))
+                                        CONTAINS marker))
+                                OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                                WITH m, collect(e.name) AS entity_names
+                                RETURN m {.*, entities: entity_names} AS memory
+                                """,
+                                ids=memory_ids,
+                                exclude_source_uris=excluded_sources,
+                                exclude_metadata_markers=(
+                                    excluded_metadata_markers),
+                            )
+                        memories = []
+                        async for record in result:
+                            mem = record["memory"]
+                            mid = mem.get("id", "")
+                            vector_score = score_map.get(mid, 0.0)
+                            strength = float(mem.get("strength", 1.0))
+                            if strength < min_strength:
+                                continue
+                            # Filter terminal epistemic states and low confidence
+                            epistemic_state = mem.get("epistemic_state", "inferred")
+                            if mem.get("superseded_by") or epistemic_state in ("stale", "superseded", "deprecated", "archived"):
+                                continue
+                            effective_confidence = float(mem.get("effective_confidence", mem.get("strength", 1.0)))
+                            if effective_confidence < min_confidence:
+                                continue
+                            if strength_ranking:
+                                mem["relevance"] = (vector_score
+                                                    * effective_confidence
+                                                    * (0.5 + 0.5 * strength))
+                            else:
+                                mem["relevance"] = vector_score * effective_confidence
+                            memories.append(mem)
+
+                if hybrid:
+                    from .recall import fuse_candidates
+                    candidate_limit = min(max(limit * 5, limit), max(100, limit))
+                    lexical = await self._recall_lexical(
+                        query, candidate_limit, min_strength, min_confidence,
+                        person_scope, excluded_sources, excluded_metadata_markers)
+                    memories = fuse_candidates(
+                        memories, lexical, limit=candidate_limit,
+                        strength_ranking=strength_ranking)
+                if results or memories:
+                    memories = await self._filter_erased_source_memories(memories)
+                    if candidates_only:
+                        return sorted(memories, key=lambda m: m.get("relevance", 0), reverse=True)[:limit]
+                    memories = await self._maybe_rerank(
+                        query, memories, limit,
+                        strength_ranking=strength_ranking)
+                    memories = await self._filter_erased_source_memories(memories)
+                    memories.sort(key=lambda m: m.get("relevance", 0), reverse=True)
+                    memories = memories[:limit]
+                    # Fire-and-forget touch_memory for each recalled result
+                    for mem in memories:
+                        mid = mem.get("id")
+                        if mid:
+                            self._retain_task(asyncio.create_task(self._touch_memory_safe(mid)))
+                    return memories
+            except Exception as exc:
+                logger.warning("Vector recall failed, falling back to graph-only: %s", exc)
+
+        # Fallback: graph-only keyword/entity recall
+        if hybrid:
+            memories = await self._recall_lexical(
+                query, min(max(limit * 5, limit), max(100, limit)),
+                min_strength, min_confidence, person_scope,
+                excluded_sources, excluded_metadata_markers)
+            if memories:
+                memories = await self._filter_erased_source_memories(memories)
+                if candidates_only:
+                    return memories[:limit]
+                memories = await self._maybe_rerank(
+                    query, memories, limit, strength_ranking=strength_ranking)
+                memories = await self._filter_erased_source_memories(memories)
+                memories.sort(key=lambda m: m.get("relevance", 0), reverse=True)
+                memories = memories[:limit]
+                for mem in memories:
+                    if mem.get("id"):
+                        self._retain_task(asyncio.create_task(self._touch_memory_safe(mem["id"])))
+                return memories
+        async with self.driver.session(database=self.database) as session:
+            if person_scope:
+                result = await session.run(
+                    """
+                    MATCH (m:Memory)-[:ABOUT]->(:Person {id: $person_id})
+                    WHERE m.strength >= $min_strength
+                      AND (size($exclude_source_uris) = 0 OR NOT (
+                        coalesce(m.source_uri, "") IN
+                        $exclude_source_uris))
+                      AND (size($exclude_metadata_markers) = 0 OR
+                        NONE(marker IN $exclude_metadata_markers
+                          WHERE toLower(coalesce(m.metadata, ""))
+                            CONTAINS marker))
+                      AND toLower(m.content) CONTAINS toLower($search_text)
+                      AND m.superseded_by IS NULL
+                      AND NOT m.epistemic_state IN ["stale", "superseded", "deprecated", "archived"]
+                    OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                    WITH m, collect(e.name) AS entity_names
+                    RETURN m {.*, entities: entity_names,
+                              person_id: $person_id} AS memory,
+                           m.effective_confidence AS relevance
+                    ORDER BY relevance DESC
+                    LIMIT $limit
+                    """,
+                    search_text=query,
+                    limit=limit,
+                    min_strength=min_strength,
+                    person_id=person_scope,
+                    exclude_source_uris=excluded_sources,
+                    exclude_metadata_markers=excluded_metadata_markers,
+                )
+            else:
+                result = await session.run(
+                    """
+                    MATCH (m:Memory)
+                    WHERE m.strength >= $min_strength
+                      AND (size($exclude_source_uris) = 0 OR NOT (
+                        coalesce(m.source_uri, "") IN
+                        $exclude_source_uris))
+                      AND (size($exclude_metadata_markers) = 0 OR
+                        NONE(marker IN $exclude_metadata_markers
+                          WHERE toLower(coalesce(m.metadata, ""))
+                            CONTAINS marker))
+                      AND toLower(m.content) CONTAINS toLower($search_text)
+                      AND m.superseded_by IS NULL
+                      AND NOT m.epistemic_state IN ["stale", "superseded", "deprecated", "archived"]
+                    OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                    WITH m, collect(e.name) AS entity_names
+                    RETURN m {.*, entities: entity_names} AS memory,
+                           m.effective_confidence AS relevance
+                    ORDER BY relevance DESC
+                    LIMIT $limit
+                    """,
+                    search_text=query,
+                    limit=limit,
+                    min_strength=min_strength,
+                    exclude_source_uris=excluded_sources,
+                    exclude_metadata_markers=excluded_metadata_markers,
+                )
+            memories = []
+            async for record in result:
+                mem = record["memory"]
+                mem["relevance"] = record.get("relevance", mem.get("strength", 0.5))
+                effective_confidence = float(mem.get("effective_confidence", mem.get("strength", 1.0)))
+                if effective_confidence < min_confidence:
+                    continue
+                memories.append(mem)
+        memories = await self._filter_erased_source_memories(memories)
+        if candidates_only:
+            return memories[:limit]
+        # Fire-and-forget touch_memory for each recalled result
+        for mem in memories:
+            mid = mem.get("id")
+            if mid:
+                self._retain_task(asyncio.create_task(self._touch_memory_safe(mid)))
+        return memories
+
+    async def _recall_lexical(
+        self, query, limit, min_strength, min_confidence,
+        person_scope, excluded_sources, excluded_metadata_markers,
+    ):
+        """Native source-text candidates with the same authoritative boundary.
+
+        The full-text index is maintained with graph writes, so an embedding
+        backlog does not hide newly stored facts. Filtering happens before
+        content reaches Python/reranking. A missing/populating index degrades
+        to the existing vector/keyword path.
+        """
+        from .recall import FULLTEXT_INDEX, lexical_query
+        search_text = lexical_query(query)
+        if not search_text:
+            return []
+
+        async def search():
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    """
+                    CALL db.index.fulltext.queryNodes($index_name, $search_text)
+                    YIELD node AS m, score
+                    WHERE m:Memory
+                      AND ($person_id IS NULL OR EXISTS {
+                        MATCH (m)-[:ABOUT]->(:Person {id: $person_id})
+                      })
+                      AND coalesce(m.strength, 1.0) >= $min_strength
+                      AND coalesce(m.effective_confidence, m.strength, 1.0) >= $min_confidence
+                      AND m.superseded_by IS NULL
+                      AND NOT coalesce(m.epistemic_state, "inferred") IN
+                        ["stale", "superseded", "deprecated", "archived"]
+                      AND (size($exclude_source_uris) = 0 OR NOT (
+                        coalesce(m.source_uri, "") IN $exclude_source_uris))
+                      AND (size($exclude_metadata_markers) = 0 OR
+                        NONE(marker IN $exclude_metadata_markers
+                          WHERE toLower(coalesce(m.metadata, "")) CONTAINS marker))
+                    WITH m, score
+                    ORDER BY score DESC
+                    LIMIT $limit
+                    OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                    WITH m, score, collect(DISTINCT e.name) AS entity_names
+                    RETURN m {.*, entities: entity_names} AS memory,
+                           score AS lexical_score
+                    ORDER BY lexical_score DESC
+                    """,
+                    index_name=FULLTEXT_INDEX, search_text=search_text,
+                    limit=limit, person_id=person_scope,
+                    min_strength=min_strength, min_confidence=min_confidence,
+                    exclude_source_uris=excluded_sources,
+                    exclude_metadata_markers=excluded_metadata_markers,
+                )
+                memories = []
+                async for record in result:
+                    mem = dict(record["memory"])
+                    mem["relevance"] = float(record["lexical_score"])
+                    mem["retrieval_method"] = "lexical"
+                    memories.append(mem)
+                return memories
+        try:
+            return await asyncio.wait_for(search(), timeout=1.2)
+        except Exception as exc:
+            logger.warning("Lexical recall unavailable, using existing recall: %s", type(exc).__name__)
+            return []
+
+    def _retain_task(self, task) -> None:
+        """Keep a strong ref to a fire-and-forget task until it finishes; the
+        loop only weak-refs it, so an unreferenced recall-touch task can be
+        GC-cancelled mid neo4j session ("Task was destroyed but it is
+        pending" + an abandoned session)."""
+        if not hasattr(self, "_bg_tasks"):
+            self._bg_tasks = set()
+        self._bg_tasks.add(task)
+        task.add_done_callback(self._bg_tasks.discard)
+
+    async def _touch_memory_safe(self, memory_id: str) -> None:
+        """Touch a memory, logging but not raising on failure."""
+        try:
+            await self.touch_memory(memory_id)
+        except Exception as exc:
+            logger.debug("touch_memory failed for %s: %s", memory_id, exc)
+
+    async def _maybe_rerank(
+        self, query, memories, limit, *, strength_ranking=False,
+    ):
+        # The same selector is used for mixed source/belief turn context.
+        from .selection import RecallSelector
+        selector = getattr(self, "_recall_selector", None)
+        if selector is None:
+            selector = self._recall_selector = RecallSelector(
+                getattr(self, "_rerank_fn", None),
+                calibration_metadata=getattr(self, "_rerank_calibration_metadata", None),
+                logger=logger)
+        return await selector.rerank(
+            query, memories, limit, strength_ranking=strength_ranking)
+
+    # ------------------------------------------------------------------
+    # Decay & pruning
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _compute_decay_factor(
+        importance: float,
+        days_elapsed: float,
+        recalls: int,
+        half_life_days: float,
+        memory_type: str = "episodic",
+        semantic_half_life_days: Optional[float] = None,
+    ) -> float:
+        """Compute Ebbinghaus decay for a memory.
+
+        Formula: strength = importance * e^(-lambda * days) * (1 + recalls * 0.2)
+
+        Where lambda = ln(2) / half_life_days.  Identity memories never decay;
+        procedural memories decay at half the normal rate; fact/semantic
+        memories use their own half-life when one is given (defaults to the
+        episodic value, i.e. no behavior change).  Result is capped at 1.0.
+
+        Args:
+            importance: Initial importance value (0-1)
+            days_elapsed: Days since last access
+            recalls: Number of times the memory has been recalled
+            half_life_days: Days for strength to halve (default 7)
+            memory_type: One of "identity", "procedural", "episodic",
+                "semantic", "fact"
+            semantic_half_life_days: Half-life for fact/semantic memories
+                (None = same as half_life_days)
+
+        Returns:
+            New strength value in [0, 1].
+        """
+        if memory_type == "identity":
+            return float(importance)
+
+        lambda_base = math.log(2) / max(half_life_days, 0.001)
+        if memory_type == "procedural":
+            # Procedural memories decay at half the normal rate
+            lambda_val = lambda_base / 2
+        elif memory_type in ("fact", "semantic"):
+            sem_half_life = (semantic_half_life_days
+                             if semantic_half_life_days is not None
+                             else half_life_days)
+            lambda_val = math.log(2) / max(sem_half_life, 0.001)
+        else:
+            lambda_val = lambda_base
+
+        strength = importance * math.exp(-lambda_val * max(days_elapsed, 0)) * (1.0 + recalls * 0.2)
+        return min(1.0, max(0.0, strength))
+
+    async def decay_memories(
+        self,
+        half_life_days: Optional[float] = None,
+        semantic_half_life_days: Optional[float] = None,
+    ) -> None:
+        """Apply Ebbinghaus forgetting curve to all non-identity, non-protected memories.
+
+        Formula: strength = importance * e^(-lambda * days) * (1 + recalls * 0.2)
+
+        Where lambda = ln(2) / half_life_days.
+        - Identity memories are skipped (never decay).
+        - Protected memories are skipped.
+        - Procedural memories use lambda / 2 (half rate).
+        - Fact/semantic memories use their own half-life (defaults to the
+          episodic value — distilled knowledge can be made to outlive the
+          episodes it came from by raising COLONY_DECAY_HALF_LIFE_SEMANTIC_DAYS).
+        - Result is capped at 1.0.
+
+        Half-lives resolve, in order: explicit argument, environment
+        (COLONY_DECAY_HALF_LIFE_DAYS / COLONY_DECAY_HALF_LIFE_SEMANTIC_DAYS),
+        then the historical default of 7 days. Strength is RECOMPUTED from
+        importance on every pass (not compounded), so raising a half-life
+        retroactively resurrects previously-decayed strength — which is why
+        half-life tuning must land before pruning goes live, never after.
+
+        This pass is the single writer for memory decay; nothing else may
+        call it as a side effect (see StrategyAdjuster._decay_signals,
+        retired for exactly that reason).
+        """
+        if half_life_days is None:
+            try:
+                half_life_days = float(os.environ.get(
+                    "COLONY_DECAY_HALF_LIFE_DAYS", "7"))
+            except (TypeError, ValueError):
+                half_life_days = 7.0
+        if semantic_half_life_days is None:
+            _sem_env = os.environ.get("COLONY_DECAY_HALF_LIFE_SEMANTIC_DAYS", "")
+            try:
+                semantic_half_life_days = (
+                    float(_sem_env) if _sem_env.strip() else half_life_days)
+            except (TypeError, ValueError):
+                semantic_half_life_days = half_life_days
+
+        lambda_normal = math.log(2) / max(half_life_days, 0.001)
+        lambda_procedural = lambda_normal / 2
+        lambda_semantic = math.log(2) / max(semantic_half_life_days, 0.001)
+
+        async with self.driver.session(database=self.database) as session:
+            # First pass: update strength
+            await session.run(
+                """
+                MATCH (m:Memory)
+                WHERE m.type <> 'identity' AND coalesce(m.protected, false) = false
+                WITH m,
+                     toFloat(duration.inDays(coalesce(m.accessed_at, m.created_at, datetime()), datetime()).days) AS days_since,
+                     CASE WHEN m.type = 'procedural'
+                          THEN $lambda_proc
+                          WHEN m.type IN ['fact', 'semantic']
+                          THEN $lambda_sem
+                          ELSE $lambda_norm
+                     END AS lam
+                WITH m,
+                     coalesce(m.importance, 1.0) *
+                         exp(-lam * days_since) *
+                         (1.0 + coalesce(m.recalls, 0) * 0.2) AS new_strength
+                SET m.strength = CASE
+                    WHEN new_strength > 1.0 THEN 1.0
+                    WHEN new_strength < 0.0 THEN 0.0
+                    ELSE new_strength
+                END
+                """,
+                lambda_norm=lambda_normal,
+                lambda_proc=lambda_procedural,
+                lambda_sem=lambda_semantic,
+            )
+
+        # Second pass: update effective_confidence in batches
+        await self._update_effective_confidence_batch()
+
+    async def prune_weak_memories(
+        self,
+        threshold: float = 0.05,
+        *,
+        dry_run: bool = False,
+        max_delete: int = 500,
+    ) -> Dict[str, Any]:
+        """Delete memories whose strength has decayed below *threshold*.
+
+        Only targets memories in ``inferred``, ``observed``, or ``stale``
+        epistemic states. Skips protected memories, ``corroborated``,
+        ``verified``, and fully terminal states (``superseded``,
+        ``deprecated``, ``archived``).
+
+        A deleted memory's vector-store entry is removed too (same coupling
+        as :meth:`archive_memories`), so pruning does not accumulate orphan
+        vectors that keep matching in ANN search. Deletion is capped at
+        *max_delete* per call (weakest first); ``dry_run=True`` only counts.
+
+        Fails closed on Neo4j errors: exceptions propagate to the caller
+        and nothing further is deleted; a vector is only removed after its
+        graph node is gone.
+
+        Returns:
+            Dict with ``matched`` (total below threshold), ``deleted``,
+            ``dry_run``, and the capped candidate ``ids``.
+        """
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(
+                """
+                MATCH (m:Memory)
+                WHERE m.strength < $threshold
+                  AND coalesce(m.protected, false) = false
+                  AND m.epistemic_state IN ["inferred", "observed", "stale"]
+                WITH m ORDER BY m.strength ASC
+                RETURN collect(m.id)[0..$max_delete] AS ids,
+                       count(m) AS matched
+                """,
+                threshold=threshold,
+                max_delete=max_delete,
+            )
+            record = await result.single()
+            ids = list(record["ids"]) if record else []
+            matched = int(record["matched"]) if record else 0
+
+        if dry_run:
+            return {"matched": matched, "deleted": 0, "dry_run": True,
+                    "ids": ids}
+
+        deleted = 0
+        for memory_id in ids:
+            async with self.driver.session(database=self.database) as session:
+                await session.run(
+                    "MATCH (m:Memory {id: $memory_id}) DETACH DELETE m",
+                    memory_id=memory_id,
+                )
+            deleted += 1
+            # Vector removal only after the graph node is gone; a failure
+            # here leaves an orphan vector (swept later), never a memory
+            # that recalls without a backing node.
+            if self._vector_store is not None:
+                try:
+                    from apsimo.vector.collections import Collection
+                    await self._vector_store.delete(
+                        collection=Collection.MEMORIES,
+                        id=memory_id,
+                    )
+                except Exception as exc:
+                    logger.debug(
+                        "Failed to remove pruned memory %s from vector "
+                        "store: %s", memory_id, exc)
+        return {"matched": matched, "deleted": deleted, "dry_run": False,
+                "ids": ids}
+
+    async def vacuum_orphan_vectors(
+        self,
+        *,
+        dry_run: bool = False,
+        max_delete: Optional[int] = None,
+        batch_size: int = 200,
+        batch_sleep_secs: float = 0.05,
+    ) -> Dict[str, Any]:
+        """Delete MEMORIES-collection vectors whose graph node no longer exists.
+
+        Orphan vectors (a node deleted without its vector — pre-coupling
+        prunes, or a vector removal that failed after node deletion) keep
+        matching in ANN search and then silently vanish at hydration,
+        stealing recall slots from real memories.
+
+        Fails closed: the graph-id read is NOT exception-wrapped — a Neo4j
+        failure aborts the vacuum before any deletion, because an empty or
+        partial graph-id set would classify every vector as an orphan and
+        wipe the store. Deletion runs in batches of *batch_size* with
+        *batch_sleep_secs* between batches; *max_delete* bounds one run.
+
+        Returns:
+            Dict with ``vectors`` (total scanned), ``orphans`` (total found),
+            ``deleted``, ``dry_run``, and a capped ``ids`` sample.
+        """
+        if self._vector_store is None:
+            return {"available": False, "vectors": 0, "orphans": 0,
+                    "deleted": 0, "dry_run": dry_run, "ids": []}
+
+        from apsimo.vector.collections import Collection
+        vector_ids = await self._vector_store.list_ids(Collection.MEMORIES)
+
+        graph_ids: set = set()
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run("MATCH (m:Memory) RETURN m.id AS id")
+            async for record in result:
+                if record["id"]:
+                    graph_ids.add(record["id"])
+
+        orphans = [vid for vid in vector_ids if vid not in graph_ids]
+        total_orphans = len(orphans)
+        if max_delete is not None:
+            orphans = orphans[:max_delete]
+
+        if dry_run:
+            return {"available": True, "vectors": len(vector_ids),
+                    "orphans": total_orphans, "deleted": 0, "dry_run": True,
+                    "ids": orphans[:20]}
+
+        deleted = 0
+        for start in range(0, len(orphans), batch_size):
+            for vid in orphans[start:start + batch_size]:
+                await self._vector_store.delete(
+                    collection=Collection.MEMORIES, id=vid)
+                deleted += 1
+            if start + batch_size < len(orphans) and batch_sleep_secs > 0:
+                await asyncio.sleep(batch_sleep_secs)
+
+        return {"available": True, "vectors": len(vector_ids),
+                "orphans": total_orphans, "deleted": deleted,
+                "dry_run": False, "ids": orphans[:20]}
+
+    async def touch_memory(self, memory_id: str) -> None:
+        """Record a memory recall, incrementing its recall counter and updating accessed_at.
+
+        Calling this after retrieval ensures the recall bonus in the Ebbinghaus
+        formula is applied on the next decay pass, slowing future decay.
+
+        Args:
+            memory_id: UUID of the Memory node to touch.
+        """
+        async with self.driver.session(database=self.database) as session:
+            await session.run(
+                """
+                MATCH (m:Memory {id: $memory_id})
+                SET m.recalls = coalesce(m.recalls, 0) + 1,
+                    m.accessed_at = datetime()
+                """,
+                memory_id=memory_id,
+            )
+
+    async def _update_effective_confidence_batch(self, batch_size: int = 1000) -> None:
+        """Update effective_confidence for all memories in batches.
+
+        Each batch is one read and one write round trip: the confidences are
+        computed in Python, then written back with a single UNWIND. Writing
+        one auto-commit statement per memory made this pass scale with the
+        memory count (thousands of round trips), which overran the autonomy
+        tick budget and cancelled the whole tick every time it ran. The read
+        is ordered by id so SKIP/LIMIT paging is stable while we write.
+        """
+        from datetime import datetime as _dt, timezone as _tz
+        now = _dt.now(_tz.utc)
+        offset = 0
+        while True:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    """
+                    MATCH (m:Memory)
+                    RETURN m {
+                        .id, .base_confidence, .source_reliability,
+                        .corroboration_count, .contradiction_count,
+                        .recalls, .last_verified_at, .created_at,
+                        .epistemic_state
+                    } AS mem
+                    ORDER BY m.id
+                    SKIP $offset LIMIT $limit
+                    """,
+                    offset=offset,
+                    limit=batch_size,
+                )
+                rows = [dict(r["mem"]) async for r in result]
+                if not rows:
+                    break
+                updates = []
+                for row in rows:
+                    if row.get("id") is None:
+                        continue
+                    new_confidence = self.compute_effective_confidence(
+                        base_confidence=row.get("base_confidence") or 1.0,
+                        source_reliability=row.get("source_reliability") or 0.5,
+                        corroboration_count=row.get("corroboration_count") or 0,
+                        contradiction_count=row.get("contradiction_count") or 0,
+                        recalls=row.get("recalls") or 0,
+                        last_verified_at=row.get("last_verified_at"),
+                        created_at=row.get("created_at") or now,
+                        epistemic_state=row.get("epistemic_state") or "inferred",
+                        now=now,
+                    )
+                    updates.append({"id": row["id"], "effective_confidence": new_confidence})
+                if updates:
+                    await session.run(
+                        """
+                        UNWIND $updates AS u
+                        MATCH (m:Memory {id: u.id})
+                        SET m.effective_confidence = u.effective_confidence
+                        """,
+                        updates=updates,
+                    )
+                if len(rows) < batch_size:
+                    break
+                offset += batch_size
+
+    async def verify_memory(self, memory_id: str) -> None:
+        """Mark a memory as manually verified.
+
+        Sets last_verified_at, transitions epistemic_state to ``verified``
+        if currently in an active state, and floors effective_confidence
+        at 0.9.
+        """
+        async with self.driver.session(database=self.database) as session:
+            await session.run(
+                """
+                MATCH (m:Memory {id: $memory_id})
+                SET m.last_verified_at = datetime(),
+                    m.epistemic_state = CASE
+                        WHEN m.epistemic_state IN ["inferred", "observed", "corroborated"]
+                        THEN "verified"
+                        ELSE m.epistemic_state
+                    END,
+                    m.effective_confidence = CASE
+                        WHEN m.effective_confidence < 0.9 THEN 0.9
+                        ELSE m.effective_confidence
+                    END
+                """,
+                memory_id=memory_id,
+            )
+
+    async def get_memory(self, memory_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch a single memory by ID.
+
+        Returns:
+            Memory dict or None if not found.
+        """
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(
+                """
+                MATCH (m:Memory {id: $memory_id})
+                OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity)
+                WITH m, collect(e.name) AS entity_names
+                RETURN m {.*, entities: entity_names} AS memory
+                """,
+                memory_id=memory_id,
+            )
+            record = await result.single()
+            return dict(record["memory"]) if record else None
+
+    async def transition_epistemic_state(
+        self,
+        memory_id: str,
+        new_state: str,
+        superseded_by: Optional[str] = None,
+    ) -> None:
+        """Transition a memory to a new epistemic state.
+
+        Args:
+            memory_id: UUID of the memory to transition.
+            new_state: Target EpistemicState value.
+            superseded_by: Optional UUID of the memory that superseded this one.
+        """
+        async with self.driver.session(database=self.database) as session:
+            await session.run(
+                """
+                MATCH (m:Memory {id: $memory_id})
+                SET m.epistemic_state = $new_state
+                WITH m
+                FOREACH (_ IN CASE WHEN $superseded_by IS NOT NULL THEN [1] ELSE [] END |
+                    SET m.superseded_by = $superseded_by
+                )
+                """,
+                memory_id=memory_id,
+                new_state=new_state,
+                superseded_by=superseded_by,
+            )
+
+    async def archive_memories(self, max_age_days: int = 30) -> int:
+        """Archive memories that have been in a terminal state for too long.
+
+        Relabels :Memory to :ArchivedMemory, copies key relationships,
+        removes from vector store, and deletes the original.
+
+        Returns:
+            Number of memories archived.
+        """
+        archived = 0
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(
+                """
+                MATCH (m:Memory)
+                WHERE m.epistemic_state IN ["superseded", "deprecated", "stale"]
+                  AND duration.inDays(m.accessed_at, datetime()).days >= $max_age_days
+                RETURN m.id AS id
+                """,
+                max_age_days=max_age_days,
+            )
+            memory_ids = [r["id"] async for r in result]
+
+        for memory_id in memory_ids:
+            try:
+                async with self.driver.session(database=self.database) as session:
+                    # Copy to ArchivedMemory with key relationships
+                    await session.run(
+                        """
+                        MATCH (m:Memory {id: $memory_id})
+                        CREATE (a:ArchivedMemory)
+                        SET a = properties(m)
+                        WITH m, a
+                        OPTIONAL MATCH (m)-[r:MENTIONS]->(e:Entity)
+                        FOREACH (_ IN CASE WHEN e IS NOT NULL THEN [1] ELSE [] END |
+                            CREATE (a)-[:MENTIONS {created_at: datetime()}]->(e)
+                        )
+                        WITH m, a
+                        OPTIONAL MATCH (m)-[r:ABOUT]->(p:Person)
+                        FOREACH (_ IN CASE WHEN p IS NOT NULL THEN [1] ELSE [] END |
+                            CREATE (a)-[:ABOUT {created_at: datetime()}]->(p)
+                        )
+                        WITH m, a
+                        OPTIONAL MATCH (m)-[r:SUPERSEDES]->(old:Memory)
+                        FOREACH (_ IN CASE WHEN old IS NOT NULL THEN [1] ELSE [] END |
+                            CREATE (a)-[:SUPERSEDES {superseded_at: r.superseded_at}]->(old)
+                        )
+                        WITH m, a
+                        OPTIONAL MATCH (m)-[r:DERIVED_FROM]->(fa:FileAnchor)
+                        FOREACH (_ IN CASE WHEN fa IS NOT NULL THEN [1] ELSE [] END |
+                            CREATE (a)-[:DERIVED_FROM {derivation_type: r.derivation_type}]->(fa)
+                        )
+                        DETACH DELETE m
+                        """,
+                        memory_id=memory_id,
+                    )
+                # Remove from vector store
+                if self._vector_store is not None:
+                    try:
+                        from apsimo.vector.collections import Collection
+                        await self._vector_store.delete(
+                            collection=Collection.MEMORIES,
+                            id=memory_id,
+                        )
+                    except Exception as exc:
+                        logger.debug("Failed to remove archived memory from vector store: %s", exc)
+                archived += 1
+            except Exception as exc:
+                logger.warning("Failed to archive memory %s: %s", memory_id, exc)
+
+        return archived
+
+    # ------------------------------------------------------------------
+    # Traversal
+    # ------------------------------------------------------------------
+
+    # Allowlist of permitted Cypher templates.  Each entry is an exact string
+    # match against the cypher argument.  This prevents run_query from being
+    # used as a Cypher injection sink while retaining the escape hatch for
+    # known safe ad-hoc queries added here explicitly.
+    _ALLOWED_CYPHER: frozenset = frozenset({
+        # (similarity_threshold Config write removed: adjustments now go
+        # through the AdaptiveParamStore, which consumers actually read.)
+        # StrategyAdjuster._recalibrate_baselines — recalculate baseline signals
+        """MATCH (p:Person)-[:EXHIBITED]->(s:Signal)
+                   WHERE s.timestamp >= datetime() - duration({days: 30})
+                   WITH p.id AS pid, s.signal_type AS stype, avg(s.normalized_value) AS baseline_val
+                   MERGE (b:Baseline {person_id: pid, signal_type: stype})
+                   SET b.value = baseline_val, b.updated_at = datetime()
+                   RETURN count(b) AS updated_baselines""",
+        # Neo4jCognitionSeeder.seed — upsert BootstrapEvent node on first boot
+        """
+            MERGE (b:BootstrapEvent {colony_id: $colony_id})
+            SET b.colony_name      = $colony_name,
+                b.colony_version   = $colony_version,
+                b.network_id       = $network_id,
+                b.corpus_version   = $corpus_version,
+                b.bootstrapped_at  = $bootstrapped_at,
+                b.layer_count      = $layer_count,
+                b.endpoint_count   = $endpoint_count
+            RETURN b.colony_id
+            """,
+
+        # ConnectionDiscoverer._find_temporal_patterns (with person_id)
+        "MATCH (m1:Memory)-[:ABOUT]->(p:Person {id: $person_id})\n"
+        "MATCH (m2:Memory)-[:ABOUT]->(p)\n"
+        "WHERE m1.id < m2.id\n"
+        "  AND abs(duration.between(m1.created_at, m2.created_at).hours) <= $window_hours\n"
+        "  AND m1.created_at >= datetime() - duration({days: $lookback_days})\n"
+        "WITH m1, m2, count(*) AS co_occurrences\n"
+        "WHERE co_occurrences >= $min_count\n"
+        "RETURN m1.id AS source_id, m2.id AS target_id,\n"
+        "       m1.type AS source_type, m2.type AS target_type,\n"
+        "       m1.metadata AS source_meta, m2.metadata AS target_meta,\n"
+        "       co_occurrences,\n"
+        "       toFloat(co_occurrences) / $lookback_days AS daily_rate\n"
+        "ORDER BY daily_rate DESC\n"
+        "LIMIT 20",
+        # ConnectionDiscoverer._find_temporal_patterns (without person_id)
+        "MATCH (m1:Memory), (m2:Memory)\n"
+        "WHERE m1.id < m2.id\n"
+        "  AND abs(duration.between(m1.created_at, m2.created_at).hours) <= $window_hours\n"
+        "  AND m1.created_at >= datetime() - duration({days: $lookback_days})\n"
+        "WITH m1, m2, count(*) AS co_occurrences\n"
+        "WHERE co_occurrences >= $min_count\n"
+        "RETURN m1.id AS source_id, m2.id AS target_id,\n"
+        "       m1.type AS source_type, m2.type AS target_type,\n"
+        "       m1.metadata AS source_meta, m2.metadata AS target_meta,\n"
+        "       co_occurrences,\n"
+        "       toFloat(co_occurrences) / $lookback_days AS daily_rate\n"
+        "ORDER BY daily_rate DESC\n"
+        "LIMIT 20",
+# ConnectionDiscoverer._find_entity_patterns
+        "MATCH (e:Entity)<-[:MENTIONS]-(m:Memory)\n"
+        "WHERE ($person_id IS NULL OR (m)-[:ABOUT]->(:Person {id: $person_id}))\n"
+        "WITH e, collect(DISTINCT m.id) AS mems\n"
+        "WITH e, mems, size(mems) AS mem_count\n"
+        "WHERE mem_count >= 2\n"
+        "RETURN e.name AS entity_name,\n"
+        "       mem_count AS occurrence_count,\n"
+        "       mems[0..5] AS evidence_sample\n"
+        "ORDER BY mem_count DESC\n"
+        "LIMIT 20",
+                # ConnectionDiscoverer._find_behavioral_patterns
+        "MATCH (p:Person {id: $person_id})-[:EXHIBITED]->(s1:Signal)\n"
+        "MATCH (p)-[:EXHIBITED]->(s2:Signal)\n"
+        "WHERE s1.signal_type <> s2.signal_type\n"
+        "  AND s2.timestamp > s1.timestamp\n"
+        "  AND duration.between(s1.timestamp, s2.timestamp).hours <= $window_hours\n"
+        "WITH s1.signal_type AS type_a, s2.signal_type AS type_b,\n"
+        "     count(*) AS occurrences,\n"
+        "     avg(s2.normalized_value - s1.normalized_value) AS avg_delta,\n"
+        "     collect(s1.id)[0..5] AS evidence\n"
+        "WHERE occurrences >= $min_occurrences\n"
+        "RETURN type_a, type_b, occurrences, avg_delta, evidence\n"
+        "ORDER BY occurrences DESC\n"
+        "LIMIT 15",
+        # Consolidator._detect_conflicts
+        "MATCH (m1:Memory)-[:MENTIONS]->(e:Entity)<-[:MENTIONS]-(m2:Memory) "
+        "WHERE id(m1) < id(m2) "
+        "AND NOT (m1)-[:MERGED_INTO]-() AND NOT (m2)-[:MERGED_INTO]-() "
+        "RETURN m1.id AS id_a, m2.id AS id_b, e.name AS entity, "
+        "       m1.content AS content_a, m2.content AS content_b",
+    })
+
+    # Additional allowlisted queries registered by callers via
+    # register_allowed_cypher(). Same discipline as _ALLOWED_CYPHER: exact,
+    # fully-parameterized strings only, never built from user input. This
+    # keeps each query single-sourced next to the code that owns it instead
+    # of duplicating string literals here.
+    _EXTRA_ALLOWED_CYPHER: set = set()
+
+    @classmethod
+    def register_allowed_cypher(cls, cypher: str) -> str:
+        """Register one exact, parameterized Cypher string for run_query."""
+        cls._EXTRA_ALLOWED_CYPHER.add(cypher)
+        return cypher
+
+    async def run_query(self, cypher: str, params: dict) -> List[Dict[str, Any]]:
+        """Execute a Cypher query and return results as dicts.
+
+        WARNING: The ``cypher`` argument must never be constructed from
+        user-controlled input.  Only queries listed in ``_ALLOWED_CYPHER``
+        are permitted; all others raise ``ValueError``.  To add a new query,
+        add its exact string to ``_ALLOWED_CYPHER`` after security review.
+
+        Args:
+            cypher: Exact Cypher query string (must be in _ALLOWED_CYPHER).
+            params: Dict of $param bindings — always parameterized, never interpolated.
+
+        Returns:
+            List of result records as plain dicts.
+
+        Raises:
+            ValueError: If ``cypher`` is not in the allowlist.
+        """
+        if (cypher not in self._ALLOWED_CYPHER
+                and cypher not in self._EXTRA_ALLOWED_CYPHER):
+            raise ValueError(
+                "run_query: cypher string not in allowlist. "
+                "Add to GraphClient._ALLOWED_CYPHER or register via "
+                "register_allowed_cypher() after security review."
+            )
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(cypher, **params)
+            return [dict(r) async for r in result]
+
+    # GRAPH-01: server-enforced maximum traversal depth
+    MAX_GRAPH_DEPTH = 10
+
+    async def traverse_memory_connections(
+        self,
+        memory_id: str,
+        max_depth: int = 3,
+        min_strength: float = 0.3,
+        limit: int = 20,
+    ) -> List[Dict[str, Any]]:
+        """Walk multi-hop causal / supporting chains from a memory.
+
+        Uses ``CAUSED_BY``, ``LED_TO``, and ``SUPPORTS`` edge types up to
+        *max_depth* hops, filtering out nodes below *min_strength*.
+
+        Returns:
+            A list of dicts with ``memory``, ``distance``, and
+            ``path_weight`` keys.
+        """
+        # GRAPH-01: clamp depth to server-enforced maximum
+        max_depth = min(int(max_depth), self.MAX_GRAPH_DEPTH)
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(
+                """
+                MATCH path = (m1:Memory)-[:CAUSED_BY|LED_TO|SUPPORTS*1..$max_depth]->(m2:Memory)
+                WHERE m1.id = $memory_id
+                AND all(node IN nodes(path) WHERE node.strength >= $min_strength)
+                RETURN m2 {.*} AS memory,
+                       length(path) AS distance,
+                       reduce(w = 1.0, r IN relationships(path) | w * r.weight) AS path_weight
+                ORDER BY path_weight DESC
+                LIMIT $limit
+                """,
+                memory_id=memory_id,
+                max_depth=max_depth,
+                min_strength=min_strength,
+                limit=limit,
+            )
+            return [
+                {
+                    "memory": record["memory"],
+                    "distance": record["distance"],
+                    "path_weight": record["path_weight"],
+                }
+                async for record in result
+            ]
+
+
+    # ------------------------------------------------------------------
+    # Baseline methods (GraphBaselineStore)
+    # ------------------------------------------------------------------
+
+    async def _run_get_baseline(self, person_id: str) -> dict | None:
+        """Read baseline properties from a Person node. Returns None if not found."""
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(GET_BASELINE, person_id=person_id)
+                record = await result.single()
+                if record is None:
+                    return None
+                return dict(record)
+        except Exception as exc:
+            logger.debug("_run_get_baseline failed for %s: %s", person_id, exc)
+            return None
+
+    async def _run_update_baseline(
+        self,
+        person_id: str,
+        msg_count: int,
+        length_mean: float,
+        length_m2: float,
+        length_std: float,
+        hour_histogram: str,
+    ) -> None:
+        """Write updated baseline properties to a Person node."""
+        try:
+            async with self.driver.session(database=self.database) as session:
+                await session.run(
+                    UPDATE_BASELINE,
+                    person_id=person_id,
+                    msg_count=msg_count,
+                    length_mean=length_mean,
+                    length_m2=length_m2,
+                    length_std=length_std,
+                    hour_histogram=hour_histogram,
+                )
+        except Exception as exc:
+            logger.debug("_run_update_baseline failed for %s: %s", person_id, exc)
+
+    async def list_person_ids(self) -> List[str]:
+        """Return all person IDs that have a Person node in the graph."""
+        query = "MATCH (p:Person) RETURN p.id AS id"
+        async with self.driver.session(database=self.database) as session:
+            result = await session.run(query)
+            records = await result.values()
+            return [r[0] for r in records if r[0]]
+
+    async def delete_person(self, person_id: str) -> bool:
+        """Permanently delete a Person node and all attached relationships."""
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    "MATCH (p:Person {id: $person_id}) DETACH DELETE p RETURN count(p) AS deleted",
+                    person_id=person_id,
+                )
+                record = await result.single()
+                deleted = record["deleted"] if record else 0
+                logger.debug(
+                    "delete_person %s deleted=%d %.1fms",
+                    person_id, deleted, (time.monotonic() - t0) * 1000,
+                )
+                return deleted > 0
+        except Exception as exc:
+            logger.error("delete_person failed for %s: %s", person_id, exc)
+            return False
+
+    async def get_people_with_substance(
+        self,
+        min_signals: int = 2,
+        min_memories: int = 2,
+    ) -> List[Dict[str, Any]]:
+        """Return Person nodes that have enough substance to become contacts.
+
+        A person has substance if they have:
+        - a name AND (a phone or email)  
+        - OR a name AND (>= min_signals OR >= min_memories)
+        """
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    """
+                    MATCH (p:Person)
+                    WHERE p.name IS NOT NULL
+                    OPTIONAL MATCH (p)-[:EXHIBITED]->(s:Signal)
+                    OPTIONAL MATCH (m:Memory)-[:ABOUT]->(p)
+                    WITH p, count(s) AS sigs, count(m) AS mems
+                    WHERE p.phone IS NOT NULL OR p.email IS NOT NULL
+                       OR sigs >= $min_signals OR mems >= $min_memories
+                    RETURN p.id AS id,
+                           p.name AS name,
+                           p.phone AS phone,
+                           p.email AS email,
+                           coalesce(p.score, 0.0) AS score,
+                           coalesce(p.tier, 'regular') AS tier,
+                           sigs,
+                           mems
+                    """,
+                    min_signals=min_signals,
+                    min_memories=min_memories,
+                )
+                people = [dict(r) async for r in result]
+                logger.debug(
+                    "get_people_with_substance count=%d %.1fms",
+                    len(people), (time.monotonic() - t0) * 1000,
+                )
+                return people
+        except Exception as exc:
+            logger.error("get_people_with_substance failed: %s", exc)
+            return []
+
+    # ------------------------------------------------------------------
+    # Signal & relationship methods (required by SignalCollector,
+    # BaselineStore, and RelationshipScorer)
+    # ------------------------------------------------------------------
+
+    async def store_signal(self, signal: Any) -> str:
+        """Persist a behavioral signal to the graph.
+
+        Creates a :Signal node linked to the :Person via [:EXHIBITED].
+        """
+        from apsimo.intelligence.graph.queries import STORE_SIGNAL, GET_BASELINE, UPDATE_BASELINE
+
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    STORE_SIGNAL,
+                    person_id=signal.person_id,
+                    signal_type=signal.signal_type,
+                    raw_value=signal.raw_value,
+                    normalized_value=signal.normalized_value,
+                    timestamp=signal.timestamp.isoformat(),
+                    source=signal.source,
+                )
+                record = await result.single()
+                sid = record["id"] if record else ""
+                logger.debug(
+                    "store_signal person=%s type=%s %.1fms",
+                    signal.person_id, signal.signal_type, (time.monotonic() - t0) * 1000,
+                )
+                return sid
+        except Exception as exc:
+            logger.error("store_signal failed for person %s: %s", signal.person_id, exc)
+            return ""
+
+    async def get_recent_signals(
+        self, person_id: str, hours: int = 24, signal_type: Optional[str] = None
+    ) -> List[Any]:
+        """Fetch recent signals for a person within a time window.
+
+        Returns a list of Signal dataclass instances from the
+        signal_collector module.
+        """
+        from apsimo.intelligence.mind_model.signal_collector import Signal
+        from datetime import timedelta
+
+        cutoff = (self._utcnow() - timedelta(hours=hours)).isoformat()
+
+        cypher = (
+            "MATCH (p:Person {id: $person_id})-[:EXHIBITED]->(s:Signal)\n"
+            "WHERE s.timestamp >= datetime($cutoff)\n"
+        )
+        if signal_type:
+            cypher += "AND s.signal_type = $signal_type\n"
+        cypher += (
+            "RETURN s.signal_type AS signal_type,\n"
+            "       s.raw_value AS raw_value,\n"
+            "       s.normalized_value AS normalized_value,\n"
+            "       s.timestamp AS timestamp,\n"
+            "       s.source AS source\n"
+            "ORDER BY s.timestamp DESC"
+        )
+
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    cypher,
+                    person_id=person_id,
+                    cutoff=cutoff,
+                    signal_type=signal_type,
+                )
+                signals = []
+                async for record in result:
+                    ts = record["timestamp"]
+                    if hasattr(ts, "to_native"):
+                        ts = ts.to_native()
+                    signals.append(Signal(
+                        signal_type=record["signal_type"],
+                        raw_value=float(record["raw_value"]),
+                        normalized_value=float(record["normalized_value"]),
+                        timestamp=ts,
+                        person_id=person_id,
+                        source=record["source"] or "message",
+                    ))
+                logger.debug(
+                    "get_recent_signals person=%s count=%d %.1fms",
+                    person_id, len(signals), (time.monotonic() - t0) * 1000,
+                )
+                return signals
+        except Exception as exc:
+            logger.error("get_recent_signals failed for person %s: %s", person_id, exc)
+            return []
+
+    async def get_all_people(self) -> List[Dict[str, Any]]:
+        """Return all Person nodes with their current scores."""
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    "MATCH (p:Person) "
+                    "RETURN p.id AS id, p.name AS name, "
+                    "       coalesce(p.score, 50.0) AS score, "
+                    "       coalesce(p.tier, 'regular') AS tier, "
+                    "       p.lastInteraction AS last_interaction"
+                )
+                people = [dict(r) async for r in result]
+                logger.debug("get_all_people count=%d %.1fms", len(people), (time.monotonic() - t0) * 1000)
+                return people
+        except Exception as exc:
+            logger.error("get_all_people failed: %s", exc)
+            return []
+
+    async def record_score_change(
+        self,
+        person_id: str,
+        new_score: float,
+        new_tier: str,
+        old_score: float,
+        reason: str,
+        store = None,  # Optional SQLiteContactStore for reverse sync
+    ) -> None:
+        """Persist a relationship score change with audit trail."""
+        from apsimo.intelligence.graph.queries import RECORD_SCORE_CHANGE
+
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                await session.run(
+                    RECORD_SCORE_CHANGE,
+                    person_id=person_id,
+                    new_score=new_score,
+                    new_tier=new_tier,
+                    delta=new_score - old_score,
+                    reason=reason,
+                )
+            logger.debug(
+                "record_score_change person=%s %.1f→%.1f (%s) %.1fms",
+                person_id, old_score, new_score, new_tier, (time.monotonic() - t0) * 1000,
+            )
+            # Sync to SQLite if linked contact exists
+            if store is not None:
+                try:
+                    contact = await store.find_by_person_node_id(person_id)
+                    if contact:
+                        # scorer works in 0-100; the contact field is 0-1
+                        _norm = new_score / 100.0 if new_score > 1.0 else new_score
+                        await store.update_relationship_score(contact.contact_id, _norm)
+                except Exception as exc:
+                    logger.debug("Score sync to SQLite failed for %s: %s", person_id, exc)
+        except Exception as exc:
+            logger.error("record_score_change failed for person %s: %s", person_id, exc)
+
+    async def get_person(self, person_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch a Person node with all properties."""
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                result = await session.run(
+                    "MATCH (p:Person {id: $person_id}) RETURN p {.*} AS person",
+                    person_id=person_id,
+                )
+                record = await result.single()
+                logger.debug("get_person %s %.1fms", person_id, (time.monotonic() - t0) * 1000)
+                return dict(record["person"]) if record else None
+        except Exception as exc:
+            logger.error("get_person failed for %s: %s", person_id, exc)
+            return None
+
+    # Property names permitted on Person nodes. Values are always passed as
+    # parameters; this allowlist guards the one remaining interpolation point
+    # (the property name itself) against accidental misuse from a caller that
+    # forwards an attacker-controlled dict.
+    _PERSON_PROPS_ALLOWED = frozenset({
+        "name", "tier", "score", "lastInteraction", "created_at",
+        "baseline_msg_count",
+        "baseline_length_mean",
+        "baseline_length_m2",
+        "baseline_length_std",
+        "baseline_hour_histogram",
+        "baseline_updated_at",
+    })
+
+    async def update_person(self, person_id: str, **props: Any) -> None:
+        """Update arbitrary properties on a Person node.
+
+        Only called from trusted internal code (BaselineStore).
+        All values are passed as Neo4j parameters; property names are
+        validated against ``_PERSON_PROPS_ALLOWED``.
+        """
+        if not props:
+            return
+        unknown = set(props) - self._PERSON_PROPS_ALLOWED
+        if unknown:
+            raise ValueError(
+                f"update_person rejected unknown properties: {sorted(unknown)}"
+            )
+        set_clauses = ", ".join(f"p.{k} = ${k}" for k in props)
+        cypher = f"MATCH (p:Person {{id: $person_id}}) SET {set_clauses}"
+        t0 = time.monotonic()
+        try:
+            async with self.driver.session(database=self.database) as session:
+                await session.run(cypher, person_id=person_id, **props)
+            logger.debug("update_person %s props=%s %.1fms", person_id, list(props), (time.monotonic() - t0) * 1000)
+        except Exception as exc:
+            logger.error("update_person failed for %s: %s", person_id, exc)
+
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _utcnow() -> "datetime":
+        """Return timezone-aware UTC now (isolated for testability)."""
+        from datetime import datetime as _dt, timezone as _tz
+        return _dt.now(_tz.utc)