apsimo 1.3.0__py3-none-any.whl

apsimo/intelligence/graph/distiller.py

@@ -0,0 +1,312 @@
+"""MemoryDistiller — promote frequently-recalled episodic memories into semantic facts.
+
+Gap A from the intelligence-systems-improvement spec.  Runs as a weekly
+background task in the autonomy loop (after consolidation and pruning).
+
+Algorithm:
+1. Identify episodic memories with high recall frequency and sufficient strength
+2. Cluster by shared entity mentions (union-find on entity overlap)
+3. For qualifying clusters (3+ members), create a semantic summary memory
+4. Mark source memories as distilled (they continue to decay naturally)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DistillationResult:
+    """Outcome of one MemoryDistiller.run() call."""
+
+    clusters_found: int = 0
+    memories_promoted: int = 0
+    source_memories_marked: int = 0
+    errors: List[str] = field(default_factory=list)
+    duration_ms: float = 0.0
+
+
+class MemoryDistiller:
+    """Promote frequently-recalled episodic memories into durable semantic facts.
+
+    Args:
+        graph_client: ColonyGraph instance (or compatible mock with execute())
+        metrics: Optional ColonyMetricsCollector for instrumentation
+        min_recalls: Minimum recall count for a memory to be a distillation
+            candidate (None = COLONY_DISTILL_MIN_RECALLS, default 3)
+        min_strength: Minimum strength for a candidate
+            (None = COLONY_DISTILL_MIN_STRENGTH, default 0.5)
+        min_age_days: Minimum age in days, only distill established memories
+            (None = COLONY_DISTILL_MIN_AGE_DAYS, default 7)
+        min_cluster_size: Minimum cluster size to trigger distillation
+        candidate_limit: Max candidates per run
+
+    The env knobs exist because the defaults assume memories survive long
+    enough to accumulate 3 recalls over 7 days — on a fast-decay graph that
+    can mean nothing ever qualifies. An explicit constructor argument always
+    wins over the environment.
+    """
+
+    def __init__(
+        self,
+        graph_client: Any,
+        metrics: Optional[Any] = None,
+        min_recalls: Optional[int] = None,
+        min_strength: Optional[float] = None,
+        min_age_days: Optional[int] = None,
+        min_cluster_size: int = 3,
+        candidate_limit: int = 200,
+    ) -> None:
+        self.graph = graph_client
+        self._metrics = metrics
+        self._min_recalls = (self._env_int("COLONY_DISTILL_MIN_RECALLS", 3)
+                             if min_recalls is None else min_recalls)
+        self._min_strength = (self._env_float("COLONY_DISTILL_MIN_STRENGTH", 0.5)
+                              if min_strength is None else min_strength)
+        self._min_age_days = (self._env_int("COLONY_DISTILL_MIN_AGE_DAYS", 7)
+                              if min_age_days is None else min_age_days)
+        self._min_cluster_size = min_cluster_size
+        self._candidate_limit = candidate_limit
+
+    @staticmethod
+    def _env_int(name: str, default: int) -> int:
+        try:
+            return int(os.environ.get(name, str(default)))
+        except (TypeError, ValueError):
+            return default
+
+    @staticmethod
+    def _env_float(name: str, default: float) -> float:
+        try:
+            return float(os.environ.get(name, str(default)))
+        except (TypeError, ValueError):
+            return default
+
+    async def run(self) -> DistillationResult:
+        """Execute one distillation pass. Never raises — errors are captured."""
+        import time
+        start = time.monotonic()
+        result = DistillationResult()
+
+        try:
+            candidates = await self._fetch_candidates()
+        except Exception as exc:
+            result.errors.append(f"fetch_candidates: {exc}")
+            result.duration_ms = (time.monotonic() - start) * 1000
+            return result
+
+        if not candidates:
+            result.duration_ms = (time.monotonic() - start) * 1000
+            return result
+
+        # Cluster by shared entities
+        clusters = self._cluster_by_entities(candidates)
+        result.clusters_found = len(clusters)
+
+        # Distill each qualifying cluster
+        for cluster in clusters:
+            try:
+                promoted = await self._distill_cluster(cluster)
+                if promoted:
+                    result.memories_promoted += 1
+                    result.source_memories_marked += len(cluster)
+            except Exception as exc:
+                result.errors.append(f"distill_cluster: {exc}")
+
+        result.duration_ms = (time.monotonic() - start) * 1000
+
+        if self._metrics is not None:
+            try:
+                self._metrics.record_distillation_run(
+                    clusters=result.clusters_found,
+                    promoted=result.memories_promoted,
+                )
+            except Exception:
+                pass
+
+        logger.info(
+            "MemoryDistiller: clusters=%d promoted=%d marked=%d errors=%d (%.1fms)",
+            result.clusters_found,
+            result.memories_promoted,
+            result.source_memories_marked,
+            len(result.errors),
+            result.duration_ms,
+        )
+        return result
+
+    async def _fetch_candidates(self) -> List[Dict[str, Any]]:
+        """Fetch episodic memories eligible for distillation."""
+        query = (
+            "MATCH (m:Memory) "
+            "WHERE m.type = 'episodic' "
+            "  AND m.recalls >= $min_recalls "
+            "  AND m.strength >= $min_strength "
+            "  AND m.created_at < datetime() - duration({days: $min_age_days}) "
+            "  AND coalesce(m.distilled, false) = false "
+            "OPTIONAL MATCH (m)-[:MENTIONS]->(e:Entity) "
+            "RETURN m.id AS id, m.content AS content, m.strength AS strength, "
+            "       m.recalls AS recalls, collect(e.name) AS entities "
+            "ORDER BY m.recalls DESC "
+            "LIMIT $limit"
+        )
+        rows = await self._execute(
+            query,
+            min_recalls=self._min_recalls,
+            min_strength=self._min_strength,
+            min_age_days=self._min_age_days,
+            limit=self._candidate_limit,
+        )
+        return rows if rows else []
+
+    def _cluster_by_entities(
+        self, candidates: List[Dict[str, Any]]
+    ) -> List[List[Dict[str, Any]]]:
+        """Group memories that share 2+ entity mentions using union-find."""
+        # Build entity → memory indices mapping
+        entity_to_indices: Dict[str, List[int]] = defaultdict(list)
+        for idx, mem in enumerate(candidates):
+            for entity in (mem.get("entities") or []):
+                entity_to_indices[entity].append(idx)
+
+        # Union-find
+        parent: List[int] = list(range(len(candidates)))
+
+        def find(x: int) -> int:
+            while parent[x] != x:
+                parent[x] = parent[parent[x]]
+                x = parent[x]
+            return x
+
+        def union(a: int, b: int) -> None:
+            ra, rb = find(a), find(b)
+            if ra != rb:
+                parent[ra] = rb
+
+        # Union memories that share entities
+        for indices in entity_to_indices.values():
+            for i in range(1, len(indices)):
+                union(indices[0], indices[i])
+
+        # Group by root and filter for shared-entity overlap >= 2
+        groups: Dict[int, List[int]] = defaultdict(list)
+        for idx in range(len(candidates)):
+            groups[find(idx)].append(idx)
+
+        clusters: List[List[Dict[str, Any]]] = []
+        for member_indices in groups.values():
+            if len(member_indices) < self._min_cluster_size:
+                continue
+            cluster = [candidates[i] for i in member_indices]
+            # Verify the cluster actually shares entities (not just single-entity links)
+            all_entities: List[Set[str]] = [
+                set(m.get("entities") or []) for m in cluster
+            ]
+            if all_entities:
+                shared = all_entities[0]
+                for eset in all_entities[1:]:
+                    shared = shared & eset
+                # At least some pair must share 2+ entities
+                if not shared:
+                    # Check pairwise: any pair with 2+ shared?
+                    has_overlap = False
+                    for i in range(len(all_entities)):
+                        for j in range(i + 1, len(all_entities)):
+                            if len(all_entities[i] & all_entities[j]) >= 2:
+                                has_overlap = True
+                                break
+                        if has_overlap:
+                            break
+                    if not has_overlap:
+                        continue
+            clusters.append(cluster)
+
+        return clusters
+
+    async def _distill_cluster(self, cluster: List[Dict[str, Any]]) -> bool:
+        """Create a semantic memory from a cluster of episodic memories.
+
+        Returns True if a new semantic memory was created.
+        """
+        # Sort by strength descending — strongest memory is the base
+        cluster.sort(key=lambda m: float(m.get("strength") or 0), reverse=True)
+
+        # Collect all unique entities across cluster
+        all_entities: Set[str] = set()
+        for mem in cluster:
+            for e in (mem.get("entities") or []):
+                all_entities.add(e)
+
+        # Build summary from strongest memory + additional entity context
+        base_content = cluster[0].get("content", "")
+        base_entities = set(cluster[0].get("entities") or [])
+        extra_entities = all_entities - base_entities
+
+        if extra_entities:
+            summary = f"[Distilled] {base_content} (also: {', '.join(sorted(extra_entities))})"
+        else:
+            summary = f"[Distilled] {base_content}"
+
+        source_ids = [m["id"] for m in cluster if m.get("id")]
+
+        # Create semantic memory node
+        create_query = (
+            "CREATE (m:Memory {"
+            "  id: randomUUID(),"
+            "  content: $content,"
+            "  type: 'semantic',"
+            "  importance: 1.0,"
+            "  strength: 1.0,"
+            "  recalls: 0,"
+            "  created_at: datetime(),"
+            "  accessed_at: datetime(),"
+            "  provenance: $source_ids,"
+            "  distilled: true"
+            "}) "
+            "WITH m "
+            "FOREACH (entity_name IN $entities | "
+            "  MERGE (e:Entity {name: entity_name}) "
+            "  CREATE (m)-[:MENTIONS]->(e) "
+            ") "
+            "RETURN m.id AS id"
+        )
+        rows = await self._execute(
+            create_query,
+            content=summary,
+            source_ids=source_ids,
+            entities=list(all_entities),
+        )
+        if not rows:
+            return False
+
+        semantic_id = rows[0].get("id", "")
+        logger.debug(
+            "Created semantic memory %s from %d episodic sources",
+            semantic_id, len(source_ids),
+        )
+
+        # Mark source memories as distilled
+        if source_ids:
+            await self._execute(
+                "MATCH (m:Memory) WHERE m.id IN $ids "
+                "SET m.distilled = true",
+                ids=source_ids,
+            )
+
+        return True
+
+    async def _execute(self, query: str, **params: Any) -> List[Dict[str, Any]]:
+        """Execute a Cypher query via the graph client."""
+        if hasattr(self.graph, "execute"):
+            result = await self.graph.execute(query, **params)
+            return result if result is not None else []
+
+        async with self.graph.driver.session(database=self.graph.database) as session:
+            result = await session.run(query, **params)
+            return [dict(record) async for record in result]

apsimo/intelligence/graph/migrations.py

@@ -0,0 +1,129 @@
+"""Colony Graph Schema Migrations.
+
+Applies Neo4j constraints and indexes required by the Colony graph memory
+system. Designed to be idempotent and safe to re-run.
+
+Vectors are maintained in a local LanceDB store in this implementation
+(see apsimo/vector/), so these migrations create no vector index.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List
+
+try:
+    from neo4j import AsyncDriver
+except ImportError:
+    pass
+
+logger = logging.getLogger(__name__)
+
+# ──────────────────────────────────────────────────────────────────────
+# Schema V1 — initial Colony graph schema
+# ──────────────────────────────────────────────────────────────────────
+
+# Each statement is executed individually so that one failure does not
+# block subsequent (independent) statements.
+
+SCHEMA_V1: List[str] = [
+    # ── Node constraints (id-based) ───────────────────────────────────
+    "CREATE CONSTRAINT memory_id IF NOT EXISTS FOR (m:Memory) REQUIRE m.id IS UNIQUE",
+    "CREATE CONSTRAINT person_id IF NOT EXISTS FOR (p:Person) REQUIRE p.id IS UNIQUE",
+    "CREATE CONSTRAINT entity_name IF NOT EXISTS FOR (e:Entity) REQUIRE e.name IS UNIQUE",
+    "CREATE CONSTRAINT owner_id IF NOT EXISTS FOR (o:Owner) REQUIRE o.id IS UNIQUE",
+    "CREATE CONSTRAINT signal_id IF NOT EXISTS FOR (s:Signal) REQUIRE s.id IS UNIQUE",
+    "CREATE CONSTRAINT context_id IF NOT EXISTS FOR (c:Context) REQUIRE c.id IS UNIQUE",
+    "CREATE CONSTRAINT score_event_id IF NOT EXISTS FOR (se:ScoreEvent) REQUIRE se.id IS UNIQUE",
+    "CREATE CONSTRAINT prediction_id IF NOT EXISTS FOR (pr:Prediction) REQUIRE pr.id IS UNIQUE",
+    "CREATE CONSTRAINT agent_id IF NOT EXISTS FOR (a:Agent) REQUIRE a.id IS UNIQUE",
+    "CREATE CONSTRAINT capability_id IF NOT EXISTS FOR (c:Capability) REQUIRE c.id IS UNIQUE",
+    "CREATE CONSTRAINT concept_id IF NOT EXISTS FOR (c:Concept) REQUIRE c.id IS UNIQUE",
+    "CREATE CONSTRAINT goal_id IF NOT EXISTS FOR (g:Goal) REQUIRE g.id IS UNIQUE",
+    "CREATE CONSTRAINT initiative_category_id IF NOT EXISTS FOR (ic:InitiativeCategory) REQUIRE ic.id IS UNIQUE",
+    "CREATE CONSTRAINT observation_id IF NOT EXISTS FOR (o:Observation) REQUIRE o.id IS UNIQUE",
+    "CREATE CONSTRAINT pattern_id IF NOT EXISTS FOR (p:Pattern) REQUIRE p.id IS UNIQUE",
+    "CREATE CONSTRAINT subsystem_id IF NOT EXISTS FOR (s:Subsystem) REQUIRE s.id IS UNIQUE",
+    "CREATE CONSTRAINT task_id IF NOT EXISTS FOR (t:Task) REQUIRE t.id IS UNIQUE",
+    # ── Indexes for common queries ────────────────────────────────────
+    "CREATE INDEX memory_type IF NOT EXISTS FOR (m:Memory) ON (m.type)",
+    "CREATE INDEX memory_strength IF NOT EXISTS FOR (m:Memory) ON (m.strength)",
+    "CREATE INDEX memory_accessed_at IF NOT EXISTS FOR (m:Memory) ON (m.accessed_at)",
+    "CREATE INDEX memory_created_at IF NOT EXISTS FOR (m:Memory) ON (m.created_at)",
+    # Synchronous full-text updates keep new/corrected source memories
+    # searchable while their independently maintained vectors catch up.
+    "CREATE FULLTEXT INDEX memory_content_fulltext IF NOT EXISTS FOR (m:Memory) ON EACH [m.content]",
+    "CREATE INDEX person_tier IF NOT EXISTS FOR (p:Person) ON (p.tier)",
+    "CREATE INDEX person_score IF NOT EXISTS FOR (p:Person) ON (p.score)",
+    "CREATE INDEX person_last_interaction IF NOT EXISTS FOR (p:Person) ON (p.lastInteraction)",
+    "CREATE INDEX signal_type IF NOT EXISTS FOR (s:Signal) ON (s.signal_type)",
+    "CREATE INDEX signal_timestamp IF NOT EXISTS FOR (s:Signal) ON (s.timestamp)",
+    "CREATE INDEX signal_processed IF NOT EXISTS FOR (s:Signal) ON (s.processed)",
+    "CREATE INDEX prediction_expires IF NOT EXISTS FOR (pr:Prediction) ON (pr.expires_at)",
+    "CREATE INDEX prediction_resolved IF NOT EXISTS FOR (pr:Prediction) ON (pr.resolved)",
+    "CREATE INDEX concept_confidence IF NOT EXISTS FOR (c:Concept) ON (c.confidence_score)",
+    "CREATE INDEX concept_status IF NOT EXISTS FOR (c:Concept) ON (c.status)",
+    "CREATE INDEX pattern_type IF NOT EXISTS FOR (p:Pattern) ON (p.pattern_type)",
+    "CREATE INDEX pattern_active IF NOT EXISTS FOR (p:Pattern) ON (p.is_active)",
+    "CREATE INDEX pattern_recurrence IF NOT EXISTS FOR (p:Pattern) ON (p.recurrence_count)",
+    "CREATE INDEX goal_status IF NOT EXISTS FOR (g:Goal) ON (g.status)",
+    "CREATE INDEX goal_priority IF NOT EXISTS FOR (g:Goal) ON (g.priority)",
+    "CREATE INDEX task_status IF NOT EXISTS FOR (t:Task) ON (t.status)",
+    "CREATE INDEX task_priority IF NOT EXISTS FOR (t:Task) ON (t.priority)",
+    "CREATE INDEX task_due IF NOT EXISTS FOR (t:Task) ON (t.due_at)",
+    "CREATE INDEX initiative_auto_exec IF NOT EXISTS FOR (ic:InitiativeCategory) ON (ic.auto_execute)",
+    "CREATE INDEX initiative_triggered IF NOT EXISTS FOR (ic:InitiativeCategory) ON (ic.last_triggered)",
+    "CREATE INDEX subsystem_status IF NOT EXISTS FOR (s:Subsystem) ON (s.status)",
+    "CREATE INDEX observation_created IF NOT EXISTS FOR (o:Observation) ON (o.created_at)",
+    "CREATE INDEX observation_entity IF NOT EXISTS FOR (o:Observation) ON (o.entity_id)",
+    # Memory governance indexes (v0.15.0)
+    "CREATE INDEX memory_source_type IF NOT EXISTS FOR (m:Memory) ON (m.source_type)",
+    "CREATE INDEX memory_epistemic_state IF NOT EXISTS FOR (m:Memory) ON (m.epistemic_state)",
+    "CREATE INDEX memory_effective_confidence IF NOT EXISTS FOR (m:Memory) ON (m.effective_confidence)",
+    "CREATE INDEX memory_content_hash IF NOT EXISTS FOR (m:Memory) ON (m.content_hash)",
+    "CREATE INDEX memory_protected IF NOT EXISTS FOR (m:Memory) ON (m.protected)",
+]
+
+async def run_migrations(
+    driver: AsyncDriver,
+    database: str = "colony",
+    embedding_dimensions: int = 1536,
+) -> dict[str, int]:
+    """Apply all Colony graph schema migrations.
+
+    Args:
+        driver: An authenticated ``AsyncDriver`` instance.
+        database: Target Neo4j database name.
+        embedding_dimensions: Kept for API compat; vector index creation
+            is now handled by LanceDB (see colony/vector/).
+
+    Returns:
+        A summary dict with counts of ``applied``, ``skipped``, and
+        ``failed`` statements.
+    """
+    applied = 0
+    skipped = 0
+    failed = 0
+
+    async with driver.session(database=database) as session:
+        # ── Constraints & indexes ─────────────────────────────────────
+        for stmt in SCHEMA_V1:
+            try:
+                await session.run(stmt)
+                applied += 1
+            except Exception as exc:
+                msg = str(exc).lower()
+                if "already exists" in msg or "equivalent" in msg:
+                    skipped += 1
+                else:
+                    failed += 1
+
+    # Vector index creation removed — vector search now uses local LanceDB.
+    # Neo4j Community Edition does not support db.index.vector.* procedures.
+    logger.info(
+        "Graph migrations complete (applied=%d, skipped=%d, failed=%d). "
+        "Vector search handled by LanceDB — run 'colony vector setup' to configure.",
+        applied, skipped, failed,
+    )
+
+    return {"applied": applied, "skipped": skipped, "failed": failed}

apsimo/intelligence/graph/queries.py

@@ -0,0 +1,248 @@
+"""Colony Graph Cypher Query Templates.
+
+All Cypher queries used by the Colony intelligence layer are defined here
+as module-level constants.  This keeps query text out of business logic
+and makes it easy to test / review / optimise in one place.
+
+Parameters are referenced with ``$param`` syntax for Neo4j driver binding.
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Memory operations
+# ──────────────────────────────────────────────────────────────────────
+
+STORE_MEMORY = """\
+CREATE (m:Memory {
+    id: randomUUID(),
+    content: $content,
+    type: $memory_type,
+    strength: 1.0,
+    created_at: datetime(),
+    accessed_at: datetime(),
+    embedding: $embedding,
+    metadata: $metadata
+})
+WITH m
+UNWIND $entities AS entity_name
+MERGE (e:Entity {name: entity_name})
+CREATE (m)-[:MENTIONS]->(e)
+RETURN m.id AS id
+"""
+
+RECALL_BY_ENTITY = """\
+MATCH (e:Entity {name: $entity_name})<-[:MENTIONS]-(m:Memory)
+WHERE m.strength >= $min_strength
+RETURN m {.*, entity: e.name} AS memory
+ORDER BY m.strength DESC, m.accessed_at DESC
+LIMIT $limit
+"""
+
+RECALL_BY_TYPE = """\
+MATCH (m:Memory {type: $memory_type})
+WHERE m.strength >= $min_strength
+RETURN m {.*} AS memory
+ORDER BY m.strength DESC, m.created_at DESC
+LIMIT $limit
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Decay & pruning
+# ──────────────────────────────────────────────────────────────────────
+
+DECAY_ALL = """\
+MATCH (m:Memory)
+WITH m,
+     duration.between(m.accessed_at, datetime()).days AS days_since
+SET m.strength = m.strength * (0.5 ^ (toFloat(days_since) / $half_life))
+"""
+
+PRUNE_WEAK_MEMORIES = """\
+MATCH (m:Memory)
+WHERE m.strength < $threshold
+DETACH DELETE m
+RETURN count(m) AS pruned
+"""
+
+TOUCH_MEMORY = """\
+MATCH (m:Memory {id: $memory_id})
+SET m.accessed_at = datetime(),
+    m.strength = CASE
+        WHEN m.strength + 0.1 > 1.0 THEN 1.0
+        ELSE m.strength + 0.1
+    END
+RETURN m {.*} AS memory
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Person / signal queries
+# ──────────────────────────────────────────────────────────────────────
+
+GET_PERSON_WITH_SIGNALS = """\
+MATCH (p:Person {id: $person_id})
+OPTIONAL MATCH (p)-[:EXHIBITED]->(s:Signal)
+WHERE s.timestamp >= datetime() - duration({days: 7})
+WITH p, collect(s) AS signals
+OPTIONAL MATCH (p)-[:HAS_CONTEXT]->(c:Context)
+WHERE c.end_date >= date() OR c.end_date IS NULL
+RETURN p {.*, signals: signals, contexts: collect(c)}
+"""
+
+GET_PERSON_SIGNALS_IN_WINDOW = """\
+MATCH (p:Person {id: $person_id})-[:EXHIBITED]->(s:Signal)
+WHERE s.timestamp >= datetime($cutoff)
+RETURN s.signal_type AS type,
+       s.normalized_value AS value,
+       s.timestamp AS ts
+ORDER BY s.timestamp DESC
+"""
+
+STORE_SIGNAL = """\
+MERGE (p:Person {id: $person_id})
+CREATE (s:Signal {
+    id: randomUUID(),
+    signal_type: $signal_type,
+    raw_value: $raw_value,
+    normalized_value: $normalized_value,
+    timestamp: datetime($timestamp),
+    source: $source
+})
+CREATE (p)-[:EXHIBITED]->(s)
+RETURN s.id AS id
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Relationship scoring
+# ──────────────────────────────────────────────────────────────────────
+
+COMPUTE_RELATIONSHIP_SCORES = """\
+MATCH (p:Person)
+WHERE p.lastInteraction >= datetime() - duration({days: 90})
+MATCH (p)-[:EXHIBITED]->(s:Signal)
+WHERE s.timestamp >= datetime() - duration({days: 90})
+WITH p, s.signal_type AS type,
+     avg(s.normalized_value) AS avg_value,
+     count(s) AS signal_count
+WITH p, collect({type: type, avg: avg_value, count: signal_count}) AS signals
+RETURN p.id, p.name, signals
+"""
+
+RECORD_SCORE_CHANGE = """\
+MATCH (p:Person {id: $person_id})
+SET p.score = $new_score,
+    p.tier = $new_tier,
+    p.lastInteraction = datetime()
+WITH p
+CREATE (se:ScoreEvent {
+    id: randomUUID(),
+    score: $new_score,
+    tier: $new_tier,
+    delta: $delta,
+    reason: $reason,
+    createdAt: datetime()
+})
+CREATE (p)-[:SCORE_CHANGED]->(se)
+RETURN se.id AS id
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Relationship maintenance
+# ──────────────────────────────────────────────────────────────────────
+
+FIND_NEGLECTED_RELATIONSHIPS = """\
+MATCH (p:Person)
+WHERE p.tier IN ['inner_circle', 'trusted']
+AND p.lastInteraction < datetime() - duration({days: 14})
+RETURN p.id, p.name, p.tier, p.lastInteraction,
+       duration.between(p.lastInteraction, datetime()).days AS days_since
+ORDER BY days_since DESC
+LIMIT $limit
+"""
+
+FIND_NEGLECTED_BY_TIER = """\
+MATCH (p:Person)
+WHERE p.tier = $tier
+AND p.lastInteraction < datetime() - duration({days: $days_threshold})
+RETURN p.id AS id, p.name AS name, p.tier AS tier,
+       p.lastInteraction AS last_interaction,
+       duration.between(p.lastInteraction, datetime()).days AS days_since
+ORDER BY days_since DESC
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Traversal / graph exploration
+# ──────────────────────────────────────────────────────────────────────
+
+TRAVERSE_MEMORY_CONNECTIONS = """\
+MATCH path = (m1:Memory)-[:CAUSED_BY|LED_TO|SUPPORTS*1..3]->(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
+"""
+
+FIND_SHARED_ENTITIES = """\
+MATCH (m1:Memory {id: $memory_id})-[:MENTIONS]->(e:Entity)<-[:MENTIONS]-(m2:Memory)
+WHERE m1 <> m2
+AND m2.strength >= $min_strength
+RETURN m2 {.*, shared_entity: e.name} AS memory
+ORDER BY m2.strength DESC
+LIMIT $limit
+"""
+
+# ──────────────────────────────────────────────────────────────────────
+# Owner / setup
+# ──────────────────────────────────────────────────────────────────────
+
+ENSURE_OWNER = """\
+MERGE (o:Owner {id: $owner_id})
+ON CREATE SET o.name = $name,
+              o.timezone = $timezone,
+              o.created_at = datetime()
+RETURN o {.*} AS owner
+"""
+
+LINK_PERSON_TO_OWNER = """\
+MATCH (o:Owner {id: $owner_id})
+MERGE (p:Person {id: $person_id})
+ON CREATE SET p.name = $name,
+              p.tier = $tier,
+              p.score = 0.0,
+              p.created_at = datetime()
+MERGE (o)-[:KNOWS]->(p)
+RETURN p {.*} AS person
+"""
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Baseline queries (GraphBaselineStore)
+# ──────────────────────────────────────────────────────────────────────
+
+GET_BASELINE = """\
+MATCH (p:Person {id: $person_id})
+RETURN p.baseline_msg_count AS msg_count,
+       p.baseline_length_mean AS length_mean,
+       p.baseline_length_m2 AS length_m2,
+       p.baseline_length_std AS length_std,
+       p.baseline_hour_histogram AS hour_histogram
+"""
+
+UPDATE_BASELINE = """\
+MERGE (p:Person {id: $person_id})
+ON CREATE SET p.baseline_msg_count = 0,
+              p.baseline_length_mean = 0.0,
+              p.baseline_length_m2 = 0.0,
+              p.baseline_length_std = 0.0,
+              p.baseline_hour_histogram = '[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]',
+              p.baseline_updated_at = datetime(),
+              p.created_at = datetime()
+SET p.baseline_msg_count = $msg_count,
+    p.baseline_length_mean = $length_mean,
+    p.baseline_length_m2 = $length_m2,
+    p.baseline_length_std = $length_std,
+    p.baseline_hour_histogram = $hour_histogram,
+    p.baseline_updated_at = datetime()
+RETURN p.id AS id
+"""