memuron 0.1.1__py3-none-any.whl

memuron/memory/recipes.py

@@ -0,0 +1,3247 @@
+"""Memuron memory recipes: ingest, CRUD, and graph helpers."""
+
+from __future__ import annotations
+
+import json
+from collections import OrderedDict
+from dataclasses import replace
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from artha_engine import ArthaEngine, EmbeddingArthaanu, EmbeddingCandidate, EmbeddingSearchParams
+from artha_engine.runtime.serde import arthaanu_from_dict, arthaanu_to_dict
+from artha_engine.store.projection_sql import sql_store_fetchall, sql_store_has_tables
+
+from memuron.domain.encoders import MemoryEncoderInput, MemoryLinkEncoderInput
+from memuron.application.config import settings
+from memuron.documents.parser import ParsedDocument, parse_source
+from memuron.documents.storage import maybe_store_source_file, presign_source_object
+from memuron.domain.scope_filter import parse_comma_scope, scope_matches_filter
+from memuron.domain.schemas import merge_source_identity_metadata, source_identity_from_metadata
+from memuron.search.pgvector import (
+    pgvector_is_ready,
+    pgvector_link_search,
+    pgvector_memory_search,
+    pgvector_memory_search_ids,
+)
+from memuron.ingest.guardian import AgnoGuardian, GuardianError
+from memuron.ingest.prompts import ConnectionSpec, GuardianWritePlan
+from memuron.spaces.service import apply_guardian_space_scope
+from memuron.domain.representations import MemoryArthaanu, MemoryLinkArthaanu, MemoryLinkValue, MemoryValue
+from memuron.security.tenant import merge_org_scope, org_scope_token
+
+MAX_GUARDIAN_LINKS = 2
+CANDIDATE_TOP_K = 10
+LINK_CANDIDATE_TOP_K = 15
+AUTO_LINK_MIN_SCORE = 0.2
+DOCUMENT_MARKDOWN_PREVIEW_CHARS = 12_000
+DOCUMENT_CHUNK_SCOPE_PREFIX = "document:"
+QUERY_EMBEDDING_CACHE_SIZE = 128
+EXTERNAL_ID_FIELDS = ("custom_id", "session_id", "thread_id", "source_id", "source_url")
+IDEMPOTENCY_EXTERNAL_ID_FIELDS = ("custom_id", "source_id")
+
+
+def _now_stamp() -> str:
+    return datetime.now(UTC).strftime("%Y%m%d%H%M")
+
+
+def external_identity_from_values(**values: str | None) -> dict[str, str]:
+    identity: dict[str, str] = {}
+    for key in EXTERNAL_ID_FIELDS:
+        value = values.get(key)
+        if not isinstance(value, str):
+            continue
+        cleaned = value.strip()
+        if cleaned:
+            identity[key] = cleaned
+    return identity
+
+
+def _external_identity_from_metadata(metadata: dict[str, Any] | None) -> dict[str, str]:
+    if not isinstance(metadata, dict):
+        return {}
+    identity: dict[str, str] = {}
+    identity.update(source_identity_from_metadata(metadata))
+    system = metadata.get("system")
+    if isinstance(system, dict):
+        legacy_source = system.get("source")
+        if isinstance(legacy_source, dict):
+            identity.update(external_identity_from_values(**legacy_source))
+        nested = system.get("external_identity")
+        if isinstance(nested, dict):
+            identity.update(external_identity_from_values(**nested))
+    identity.update(external_identity_from_values(**metadata))
+    return identity
+
+
+def _external_identity_from_payload(payload: dict[str, Any] | None) -> dict[str, str]:
+    if not isinstance(payload, dict):
+        return {}
+    identity: dict[str, str] = {}
+    nested = payload.get("source_identity")
+    if isinstance(nested, dict):
+        identity.update(external_identity_from_values(**nested))
+    identity.update(external_identity_from_values(**payload))
+    return identity
+
+
+def _memory_external_identity(memory: dict[str, Any]) -> dict[str, str]:
+    identity = _external_identity_from_payload(memory.get("payload"))
+    identity.update(_external_identity_from_metadata(memory.get("metadata")))
+    return identity
+
+
+def _metadata_with_external_identity(
+    metadata: dict[str, Any] | None,
+    external_identity: dict[str, str] | None,
+) -> dict[str, Any]:
+    output = dict(metadata or {})
+    identity = {
+        **_external_identity_from_metadata(output),
+        **external_identity_from_values(**(external_identity or {})),
+    }
+    if not identity:
+        return output
+    output = merge_source_identity_metadata(output, **identity)
+    for key, value in identity.items():
+        output[key] = value
+    system = dict(output.get("system") or {})
+    # Keep the old worker alias readable while standardizing on system.source.
+    system["external_identity"] = identity
+    output["system"] = system
+    return output
+
+
+def _payload_with_external_identity(
+    payload: dict[str, Any] | None,
+    external_identity: dict[str, str] | None,
+) -> dict[str, Any]:
+    output = dict(payload or {})
+    identity = {
+        **_external_identity_from_payload(output),
+        **external_identity_from_values(**(external_identity or {})),
+    }
+    if identity:
+        output["source_identity"] = identity
+    return output
+
+
+def refresh_memory_projections(engine: ArthaEngine) -> None:
+    engine.refresh_projection("memuron_memories")
+    engine.refresh_projection("memuron_links")
+    engine.refresh_projection("memuron_placements")
+    engine.refresh_projection("memuron_fs")
+
+
+_PROJECTIONS_READY_FLAG = "_memuron_projections_ready"
+
+
+def projections_are_ready(store: object) -> bool:
+    return bool(getattr(store, _PROJECTIONS_READY_FLAG, False))
+
+
+def _require_memory_projections(engine: ArthaEngine) -> None:
+    if not projections_are_ready(engine.store):
+        raise RuntimeError(
+            "Memuron projections are not initialized. "
+            "Call ensure_memory_projections during app startup or test setup."
+        )
+
+
+def ensure_memory_projections(engine: ArthaEngine) -> None:
+    """Create projection tables if they do not exist yet."""
+    store = engine.store
+    if projections_are_ready(store):
+        return
+    for name in ("memuron_memories", "memuron_links", "memuron_placements", "memuron_fs"):
+        projection = engine.registry.create_projection(name)
+        projection.init(store)  # type: ignore[attr-defined]
+    from memuron.search.pgvector import ensure_pgvector_schema
+
+    ensure_pgvector_schema(store, engine.embedder.dimensions)
+    setattr(store, _PROJECTIONS_READY_FLAG, True)
+
+
+def _memory_node_type(existing: MemoryArthaanu) -> str:
+    return str(getattr(existing.value, "node_type", "text") or "text")
+
+
+def _rich_fields_from_memory(existing: MemoryArthaanu) -> dict[str, Any]:
+    return {
+        "node_type": _memory_node_type(existing),
+        "payload": dict(getattr(existing.value, "payload", {}) or {}),
+        "perception": getattr(existing.value, "perception", None),
+        "encoding": getattr(existing.value, "encoding", "memory"),
+        "metadata": dict(getattr(existing.value, "metadata", {}) or {}),
+    }
+
+
+def _coerce_memory_arthaanu(engine: ArthaEngine, item: object) -> MemoryArthaanu:
+    if isinstance(item, MemoryArthaanu):
+        return item
+    return arthaanu_from_dict(
+        arthaanu_to_dict(item),
+        type_registry=engine.registry.arthaanu_types,
+    )
+
+
+def _guardian_may_update_target(existing: MemoryArthaanu) -> bool:
+    """Text ingest may merge into text memories only — not image/document/collection nodes."""
+    return _memory_node_type(existing) == "text"
+
+
+def _encode_memory(
+    engine: ArthaEngine,
+    *,
+    content: str,
+    scope: list[str] | None = None,
+    node_type: str = "text",
+    payload: dict[str, Any] | None = None,
+    perception: str | None = None,
+    encoding: str = "memory",
+    metadata: dict[str, Any] | None = None,
+    artha_id: str | None = None,
+    retrieval_count: int = 0,
+    persist: bool = False,
+) -> MemoryArthaanu:
+    encoded = engine.encode(
+        "memory",
+        {
+            "content": content,
+            "scope": scope or [],
+            "node_type": node_type,
+            "payload": payload or {},
+            "perception": perception,
+            "encoding": encoding,
+            "metadata": metadata or {},
+            "artha_id": artha_id,
+            "retrieval_count": retrieval_count,
+        },
+        persist=persist,
+    )
+    if not isinstance(encoded, MemoryArthaanu):
+        raise TypeError("memory encoder must return MemoryArthaanu")
+    return encoded
+
+
+def _encode_link(
+    engine: ArthaEngine,
+    *,
+    source_id: str,
+    target_id: str,
+    description: str,
+    metadata: dict[str, Any] | None = None,
+    persist: bool = False,
+) -> MemoryLinkArthaanu:
+    encoded = engine.encode(
+        "memory_link",
+        {
+            "source_id": source_id,
+            "target_id": target_id,
+            "description": description,
+            "metadata": metadata or {},
+        },
+        persist=persist,
+    )
+    if not isinstance(encoded, MemoryLinkArthaanu):
+        raise TypeError("memory_link encoder must return MemoryLinkArthaanu")
+    return encoded
+
+
+def _append_memory_event(
+    engine: ArthaEngine,
+    *,
+    event_type: str,
+    memory: MemoryArthaanu,
+    component: str,
+    extra_payload: dict[str, object] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> str:
+    payload: dict[str, object] = {"created_at": _now_stamp()}
+    if extra_payload:
+        payload.update(extra_payload)
+    if event_metadata:
+        payload.update(event_metadata)
+    return engine.store.append_event(
+        event_type=event_type,
+        arthaanu=memory,
+        component=component,
+        payload=payload,
+    )
+
+
+def _append_link_event(
+    engine: ArthaEngine,
+    *,
+    event_type: str,
+    link: MemoryLinkArthaanu,
+    component: str,
+    extra_payload: dict[str, object] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> str:
+    payload: dict[str, object] = {}
+    if extra_payload:
+        payload.update(extra_payload)
+    if event_metadata:
+        payload.update(event_metadata)
+    return engine.store.append_event(
+        event_type=event_type,
+        arthaanu=link,
+        component=component,
+        payload=payload,
+    )
+
+
+def _list_memory_rows(engine: ArthaEngine) -> list[dict[str, Any]]:
+    _require_memory_projections(engine)
+    store = engine.store
+    if sql_store_has_tables(store):
+        return sql_store_fetchall(
+            store,
+            """
+            SELECT artha_id, content, scope_json, embedding_json,
+                   node_type, payload_json, perception, encoding, metadata_json,
+                   created_at, updated_at, sequence
+            FROM memuron_memories
+            ORDER BY sequence DESC
+            """,
+        )
+    bucket = getattr(store, "memuron_memories", {})
+    rows: list[dict[str, Any]] = []
+    for artha_id, item in bucket.items():
+        rows.append(
+            {
+                "artha_id": artha_id,
+                "content": item["content"],
+                "node_type": item.get("node_type", "text"),
+                "payload_json": item.get("payload", {}),
+                "perception": item.get("perception"),
+                "encoding": item.get("encoding", "memory"),
+                "metadata_json": item.get("metadata", {}),
+                "scope_json": item.get("scope", []),
+                "embedding_json": item.get("embedding", []),
+                "created_at": item.get("created_at"),
+                "updated_at": item.get("updated_at"),
+                "sequence": item.get("sequence", 0),
+            }
+        )
+    return rows
+
+
+def _row_to_memory_dict(row: dict[str, Any]) -> dict[str, Any]:
+    scope = row.get("scope_json")
+    embedding = row.get("embedding_json")
+    payload = row.get("payload_json")
+    metadata = row.get("metadata_json")
+    if isinstance(scope, str):
+        scope = json.loads(scope)
+    if isinstance(embedding, str):
+        embedding = json.loads(embedding)
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    if isinstance(metadata, str):
+        metadata = json.loads(metadata)
+    return {
+        "id": row["artha_id"],
+        "content": row["content"],
+        "node_type": row.get("node_type") or "text",
+        "payload": payload if isinstance(payload, dict) else {},
+        "perception": row.get("perception") or row["content"],
+        "encoding": row.get("encoding") or "memory",
+        "metadata": metadata if isinstance(metadata, dict) else {},
+        "scope": scope if isinstance(scope, list) else [],
+        "embedding": embedding if isinstance(embedding, list) else [],
+        "timestamp": row.get("created_at") or row.get("updated_at") or _now_stamp(),
+    }
+
+
+def _list_link_rows(engine: ArthaEngine) -> list[dict[str, Any]]:
+    _require_memory_projections(engine)
+    store = engine.store
+    if sql_store_has_tables(store):
+        return sql_store_fetchall(
+            store,
+            """
+            SELECT link_id, source_id, target_id, description, metadata_json,
+                   embedding_json, sequence
+            FROM memuron_links
+            ORDER BY sequence DESC
+            """,
+        )
+    bucket = getattr(store, "memuron_links", {})
+    return [
+        {
+            "link_id": link_id,
+            "source_id": item["source_id"],
+            "target_id": item["target_id"],
+            "description": item["description"],
+            "metadata_json": item.get("metadata", {}),
+            "embedding_json": item.get("embedding", []),
+            "sequence": item.get("sequence", 0),
+        }
+        for link_id, item in bucket.items()
+    ]
+
+
+def _list_placement_rows(engine: ArthaEngine) -> list[dict[str, Any]]:
+    _require_memory_projections(engine)
+    store = engine.store
+    if sql_store_has_tables(store):
+        return sql_store_fetchall(
+            store,
+            """
+            SELECT placement_id, parent_id, child_id, name, scope_json, metadata_json,
+                   inherit_parent_scope, sequence
+            FROM memuron_placements
+            ORDER BY sequence DESC
+            """,
+        )
+    bucket = getattr(store, "memuron_placements", {})
+    return [
+        {
+            "placement_id": placement_id,
+            "parent_id": item["parent_id"],
+            "child_id": item["child_id"],
+            "name": item["name"],
+            "scope_json": item.get("scope", []),
+            "metadata_json": item.get("metadata", {}),
+            "inherit_parent_scope": item.get("inherit_parent_scope", True),
+            "sequence": item.get("sequence", 0),
+        }
+        for placement_id, item in bucket.items()
+    ]
+
+
+def _filtered_memory_rows(
+    engine: ArthaEngine,
+    *,
+    scope: list[str] | None = None,
+) -> list[dict[str, Any]]:
+    scope_patterns = list(scope or [])
+    rows: list[dict[str, Any]] = []
+    for row in _list_memory_rows(engine):
+        memory = _row_to_memory_dict(row)
+        if scope_patterns and not scope_matches_filter(memory.get("scope") or [], scope_patterns):
+            continue
+        rows.append(row)
+    return rows
+
+
+def _scope_matches_filter(scope: list[str], scope_filter: list[str] | None) -> bool:
+    return scope_matches_filter(scope, scope_filter)
+
+
+def _parse_json_field(value: Any, default: Any) -> Any:
+    if value is None:
+        return default
+    if isinstance(value, (list, dict)):
+        return value
+    try:
+        return json.loads(str(value))
+    except json.JSONDecodeError:
+        return default
+
+
+def _cosine_score(left: list[float], right: list[float]) -> float:
+    if not left or not right or len(left) != len(right):
+        return 0.0
+    dot = sum(a * b for a, b in zip(left, right, strict=False))
+    left_norm = sum(a * a for a in left) ** 0.5
+    right_norm = sum(b * b for b in right) ** 0.5
+    if left_norm == 0 or right_norm == 0:
+        return 0.0
+    raw = dot / (left_norm * right_norm)
+    return max(0.0, min(1.0, (raw + 1.0) / 2.0))
+
+
+def _embed_query_vector(engine: ArthaEngine, text: str) -> list[float]:
+    normalized = text.strip()
+    cache = getattr(engine, "_memuron_query_embedding_cache", None)
+    if not isinstance(cache, OrderedDict):
+        cache = OrderedDict()
+        setattr(engine, "_memuron_query_embedding_cache", cache)
+    cached = cache.get(normalized)
+    if cached is not None:
+        cache.move_to_end(normalized)
+        return list(cached)
+    vector = engine.embedder.embed_queries([normalized])[0]
+    cache[normalized] = tuple(vector)
+    cache.move_to_end(normalized)
+    while len(cache) > QUERY_EMBEDDING_CACHE_SIZE:
+        cache.popitem(last=False)
+    return vector
+
+
+def _list_memory_search_rows(engine: ArthaEngine) -> list[dict[str, Any]]:
+    """Slim projection rows for similarity search (no content text)."""
+    _require_memory_projections(engine)
+    store = engine.store
+    if sql_store_has_tables(store):
+        return sql_store_fetchall(
+            store,
+            """
+            SELECT artha_id, scope_json, embedding_json
+            FROM memuron_memories
+            """,
+        )
+    bucket = getattr(store, "memuron_memories", {})
+    return [
+        {
+            "artha_id": artha_id,
+            "scope_json": item.get("scope", []),
+            "embedding_json": item.get("embedding", []),
+        }
+        for artha_id, item in bucket.items()
+    ]
+
+
+def _list_link_search_rows(engine: ArthaEngine) -> list[dict[str, Any]]:
+    _require_memory_projections(engine)
+    store = engine.store
+    if sql_store_has_tables(store):
+        return sql_store_fetchall(
+            store,
+            """
+            SELECT link_id, source_id, target_id, description, metadata_json, embedding_json
+            FROM memuron_links
+            """,
+        )
+    bucket = getattr(store, "memuron_links", {})
+    return [
+        {
+            "link_id": link_id,
+            "source_id": item["source_id"],
+            "target_id": item["target_id"],
+            "description": item["description"],
+            "metadata_json": item.get("metadata", {}),
+            "embedding_json": item.get("embedding", []),
+        }
+        for link_id, item in bucket.items()
+    ]
+
+
+def _fetch_memory_rows_by_ids(
+    engine: ArthaEngine,
+    memory_ids: list[str],
+) -> dict[str, dict[str, Any]]:
+    if not memory_ids:
+        return {}
+    wanted = set(memory_ids)
+    found: dict[str, dict[str, Any]] = {}
+    store = engine.store
+    if sql_store_has_tables(store):
+        placeholders = ", ".join("?" for _ in memory_ids)
+        rows = sql_store_fetchall(
+            store,
+            f"""
+            SELECT artha_id, content, scope_json, embedding_json,
+                   node_type, payload_json, perception, encoding, metadata_json,
+                   created_at, updated_at, sequence
+            FROM memuron_memories
+            WHERE artha_id IN ({placeholders})
+            """,
+            tuple(memory_ids),
+        )
+        for row in rows:
+            found[str(row["artha_id"])] = row
+        return found
+    bucket = getattr(store, "memuron_memories", {})
+    for artha_id, item in bucket.items():
+        if artha_id in wanted:
+            found[artha_id] = {
+                "artha_id": artha_id,
+                "content": item["content"],
+                "node_type": item.get("node_type") or "text",
+                "payload_json": item.get("payload", {}),
+                "perception": item.get("perception"),
+                "encoding": item.get("encoding", "memory"),
+                "scope_json": item.get("scope", []),
+                "embedding_json": item.get("embedding", []),
+                "metadata_json": item.get("metadata", {}),
+                "created_at": item.get("created_at"),
+                "updated_at": item.get("updated_at"),
+                "sequence": item.get("sequence", 0),
+            }
+    return found
+
+
+def _cosine_similarity_hits(
+    engine: ArthaEngine,
+    query_vector: list[float],
+    rows: list[dict[str, Any]],
+    *,
+    scope: list[str] | None = None,
+    top_k: int,
+    id_key: str,
+    embedding_key: str = "embedding_json",
+    scope_key: str | None = "scope_json",
+) -> list[tuple[str, float]]:
+    if not rows:
+        return []
+
+    filtered_rows: list[dict[str, Any]] = []
+    if scope_key is not None and scope:
+        filtered_rows = [
+            row
+            for row in rows
+            if _scope_matches_filter(
+                _parse_json_field(row.get(scope_key), []),
+                scope,
+            )
+        ]
+    else:
+        filtered_rows = rows
+
+    query = EmbeddingArthaanu(
+        name="memuron_query",
+        value=query_vector,
+        dimensions=len(query_vector),
+        model=engine.embedder.query_model_name,
+    )
+    candidates: list[EmbeddingCandidate] = []
+    for row in filtered_rows:
+        embedding = _parse_json_field(row.get(embedding_key), [])
+        if not embedding or len(embedding) != len(query_vector):
+            continue
+        item_id = str(row[id_key])
+        if id_key == "link_id":
+            link = _link_row_to_dict(row)
+            item = MemoryLinkArthaanu(
+                artha_id=item_id,
+                name="memory_link",
+                value=MemoryLinkValue(
+                    source_id=link["source_id"],
+                    target_id=link["target_id"],
+                    description=link["description"],
+                    embedding=embedding,
+                ),
+            )
+        else:
+            item = MemoryArthaanu(
+                artha_id=item_id,
+                name="memory",
+                value=MemoryValue(
+                    content="",
+                    scope=_parse_json_field(row.get(scope_key), []) if scope_key else [],
+                    embedding=embedding,
+                ),
+            )
+        candidates.append(
+            EmbeddingCandidate(
+                item=item,
+                embedding=EmbeddingArthaanu(
+                    name=f"{item_id}_embedding",
+                    value=embedding,
+                    dimensions=len(embedding),
+                ),
+            )
+        )
+    if not candidates:
+        return []
+
+    result = engine.decode(
+        "cosine_similarity",
+        query,
+        EmbeddingSearchParams(candidates=candidates, top_k=top_k),
+    )
+    hits = result.hits if hasattr(result, "hits") else []
+    output: list[tuple[str, float]] = []
+    for hit in hits:
+        output.append((hit.item.artha_id, float(hit.score)))
+    return output
+
+
+def _memory_similarity_hits(
+    engine: ArthaEngine,
+    query_vector: list[float],
+    *,
+    scope: list[str] | None = None,
+    top_k: int,
+) -> list[tuple[str, float]]:
+    store = engine.store
+    if pgvector_is_ready(store):
+        return pgvector_memory_search_ids(store, query_vector, top_k=top_k, scope=scope)
+    rows = _list_memory_search_rows(engine)
+    return _cosine_similarity_hits(
+        engine,
+        query_vector,
+        rows,
+        scope=scope,
+        top_k=top_k,
+        id_key="artha_id",
+    )
+
+
+def find_candidates(
+    engine: ArthaEngine,
+    content: str,
+    *,
+    scope: list[str] | None = None,
+    top_k: int = CANDIDATE_TOP_K,
+    query_vector: list[float] | None = None,
+) -> list[tuple[str, float, dict[str, Any]]]:
+    if not pgvector_is_ready(engine.store):
+        rows = _list_memory_search_rows(engine)
+        if not rows:
+            return []
+
+    vector = query_vector or _embed_query_vector(engine, content)
+    hit_ids = _memory_similarity_hits(
+        engine,
+        vector,
+        scope=scope,
+        top_k=top_k,
+    )
+    if not hit_ids:
+        return []
+
+    details = _fetch_memory_rows_by_ids(engine, [memory_id for memory_id, _score in hit_ids])
+    output: list[tuple[str, float, dict[str, Any]]] = []
+    for memory_id, score in hit_ids:
+        row = details.get(memory_id)
+        if not row:
+            continue
+        output.append((memory_id, score, _row_to_memory_dict(row)))
+    return output
+
+
+def _tenant_id_from_metadata(event_metadata: dict[str, object] | None) -> str | None:
+    if not event_metadata:
+        return None
+    tenant_id = event_metadata.get("tenant_id")
+    return str(tenant_id) if tenant_id else None
+
+
+def _memory_belongs_to_tenant(memory: dict[str, Any], tenant_id: str | None) -> bool:
+    if not tenant_id:
+        return True
+    return scope_matches_filter(memory.get("scope") or [], [org_scope_token(tenant_id)])
+
+
+def _space_tokens_for_identity_context(
+    scope: list[str],
+    space_context: dict[str, str] | None,
+) -> list[str]:
+    tokens: list[str] = []
+    active_space = (space_context or {}).get("active_space_token")
+    if active_space:
+        tokens.append(active_space)
+    for token in scope:
+        if str(token).startswith("space.") and token not in tokens:
+            tokens.append(str(token))
+    return tokens
+
+
+def _memory_matches_identity_context(
+    memory: dict[str, Any],
+    *,
+    tenant_id: str | None,
+    scope: list[str],
+    space_context: dict[str, str] | None,
+) -> bool:
+    if not _memory_belongs_to_tenant(memory, tenant_id):
+        return False
+    memory_scope = memory.get("scope") or []
+    for space_token in _space_tokens_for_identity_context(scope, space_context):
+        if space_token not in memory_scope:
+            return False
+    return True
+
+
+def _find_external_identity_match(
+    engine: ArthaEngine,
+    *,
+    external_identity: dict[str, str] | None,
+    tenant_id: str | None,
+    scope: list[str],
+    space_context: dict[str, str] | None,
+    node_type: str | None = None,
+) -> dict[str, Any] | None:
+    identity = external_identity_from_values(**(external_identity or {}))
+    if not any(identity.get(key) for key in IDEMPOTENCY_EXTERNAL_ID_FIELDS):
+        return None
+    matches: list[dict[str, Any]] = []
+    for row in _list_memory_rows(engine):
+        memory = _row_to_memory_dict(row)
+        if node_type is not None and str(memory.get("node_type") or "text") != node_type:
+            continue
+        if not _memory_matches_identity_context(
+            memory,
+            tenant_id=tenant_id,
+            scope=scope,
+            space_context=space_context,
+        ):
+            continue
+        existing_identity = _memory_external_identity(memory)
+        if any(
+            identity.get(key) and identity.get(key) == existing_identity.get(key)
+            for key in IDEMPOTENCY_EXTERNAL_ID_FIELDS
+        ):
+            matches.append(memory)
+    if not matches:
+        return None
+    matches.sort(key=lambda item: str(item.get("timestamp") or ""))
+    return matches[-1]
+
+
+def _filter_candidates_by_tenant(
+    candidates: list[tuple[str, float, dict[str, Any]]],
+    tenant_id: str | None,
+) -> list[tuple[str, float, dict[str, Any]]]:
+    if not tenant_id:
+        return candidates
+    return [
+        (memory_id, score, memory)
+        for memory_id, score, memory in candidates
+        if _memory_belongs_to_tenant(memory, tenant_id)
+    ]
+
+
+def _merge_memory_metadata(
+    existing: dict[str, Any] | None,
+    incoming: dict[str, Any] | None,
+) -> dict[str, Any]:
+    output = dict(existing or {})
+    for key, value in (incoming or {}).items():
+        if key == "system" and isinstance(value, dict):
+            system = dict(output.get("system") or {})
+            for system_key, system_value in value.items():
+                if isinstance(system_value, dict) and isinstance(system.get(system_key), dict):
+                    system[system_key] = {**system[system_key], **system_value}
+                else:
+                    system[system_key] = system_value
+            output["system"] = system
+        else:
+            output[key] = value
+    return output
+
+
+def _resolve_update_target(
+    engine: ArthaEngine,
+    *,
+    target_id: str | None,
+    tenant_id: str | None,
+    candidates: list[tuple[str, float, dict[str, Any]]],
+) -> str | None:
+    if not target_id:
+        return None
+    candidate_ids = {memory_id for memory_id, _score, _memory in candidates}
+    if target_id in candidate_ids:
+        return target_id
+    if not tenant_id:
+        return target_id
+    try:
+        existing = get_memory(engine, target_id)
+    except KeyError:
+        return None
+    if _memory_belongs_to_tenant(existing, tenant_id):
+        return target_id
+    return None
+
+
+def _validate_connections(
+    memory_id: str,
+    scope: list[str],
+    raw_connections: list[ConnectionSpec],
+    candidate_ids: list[str],
+    memories_by_id: dict[str, dict[str, Any]],
+) -> list[ConnectionSpec]:
+    validated: list[ConnectionSpec] = []
+    for conn in raw_connections:
+        target_id = conn.target_id
+        description = conn.description.strip()
+        if not target_id:
+            continue
+        if len(validated) >= MAX_GUARDIAN_LINKS:
+            break
+        target = memories_by_id.get(target_id)
+        if not target:
+            continue
+        if target_id != memory_id and target_id not in candidate_ids:
+            overlap = set(scope) & set(target.get("scope") or [])
+            if not overlap:
+                continue
+        if len(description) < 20 or "?" not in description:
+            continue
+        validated.append(conn)
+    return validated
+
+
+def _find_link_ids_between(
+    engine: ArthaEngine,
+    memory_id_1: str,
+    memory_id_2: str,
+) -> list[str]:
+    store = engine.store
+    if sql_store_has_tables(store):
+        rows = sql_store_fetchall(
+            store,
+            """
+            SELECT link_id FROM memuron_links
+            WHERE (source_id = ? AND target_id = ?)
+               OR (source_id = ? AND target_id = ?)
+            """,
+            (memory_id_1, memory_id_2, memory_id_2, memory_id_1),
+        )
+        return [str(row["link_id"]) for row in rows]
+    bucket = getattr(store, "memuron_links", {})
+    link_ids: list[str] = []
+    for link_id, item in bucket.items():
+        src = item["source_id"]
+        tgt = item["target_id"]
+        if {src, tgt} == {memory_id_1, memory_id_2}:
+            link_ids.append(link_id)
+    return link_ids
+
+
+def _normalize_link_description(description: str) -> str:
+    return " ".join(description.strip().casefold().split())
+
+
+def _find_existing_link(
+    engine: ArthaEngine,
+    *,
+    source_id: str,
+    target_id: str,
+    description: str,
+) -> dict[str, Any] | None:
+    normalized = _normalize_link_description(description)
+    for row in _list_link_rows(engine):
+        if str(row["source_id"]) != source_id or str(row["target_id"]) != target_id:
+            continue
+        if _normalize_link_description(str(row.get("description") or "")) == normalized:
+            return _link_row_to_dict(row)
+    return None
+
+
+def create_memory_link(
+    engine: ArthaEngine,
+    *,
+    source_id: str,
+    target_id: str,
+    description: str,
+    event_metadata: dict[str, object] | None = None,
+) -> tuple[dict[str, Any], bool]:
+    _require_memory_projections(engine)
+    if not description.strip():
+        raise ValueError("description is required")
+    get_memory(engine, source_id)
+    get_memory(engine, target_id)
+    existing = _find_existing_link(
+        engine,
+        source_id=source_id,
+        target_id=target_id,
+        description=description,
+    )
+    if existing:
+        return existing, False
+    link = _encode_link(
+        engine,
+        source_id=source_id,
+        target_id=target_id,
+        description=description.strip(),
+        persist=False,
+    )
+    _append_link_event(
+        engine,
+        event_type="link.created",
+        link=link,
+        component="memuron.node.link",
+        event_metadata=event_metadata,
+    )
+    refresh_memory_projections(engine)
+    return {
+        "link_id": link.artha_id,
+        "source_id": source_id,
+        "target_id": target_id,
+        "description": description.strip(),
+        "embedding": list(link.value.embedding),
+    }, True
+
+
+def _remove_link(
+    engine: ArthaEngine,
+    link_id: str,
+    *,
+    event_metadata: dict[str, object] | None = None,
+) -> None:
+    link = engine.store.get(link_id)
+    if link is None:
+        return
+    if not isinstance(link, MemoryLinkArthaanu):
+        link = arthaanu_from_dict(
+            arthaanu_to_dict(link),
+            type_registry=engine.registry.arthaanu_types,
+        )
+    engine.semantic_delete(
+        link_id,
+        event_type="delete",
+        component="memuron.unlink",
+        metadata={
+            "domain_event_type": "link.removed",
+            "link_id": link_id,
+            **(event_metadata or {}),
+        },
+    )
+
+
+def _apply_guardian_links(
+    engine: ArthaEngine,
+    memory_id: str,
+    scope: list[str],
+    plan: GuardianWritePlan,
+    candidate_ids: list[str],
+    memories_by_id: dict[str, dict[str, Any]],
+    *,
+    event_metadata: dict[str, object] | None = None,
+) -> int:
+    validated = _validate_connections(
+        memory_id,
+        scope,
+        plan.connections,
+        candidate_ids,
+        memories_by_id,
+    )
+    for conn in validated:
+        link = _encode_link(
+            engine,
+            source_id=memory_id,
+            target_id=conn.target_id,
+            description=conn.description,
+            persist=False,
+        )
+        _append_link_event(
+            engine,
+            event_type="link.created",
+            link=link,
+            component="memuron.ingest.guardian",
+            event_metadata=event_metadata,
+        )
+
+    for pair in plan.links_to_remove:
+        if not isinstance(pair, list) or len(pair) != 2:
+            continue
+        for link_id in _find_link_ids_between(engine, str(pair[0]), str(pair[1])):
+            _remove_link(engine, link_id, event_metadata=event_metadata)
+    return len(validated)
+
+
+def _find_link_candidates(
+    engine: ArthaEngine,
+    content: str,
+    *,
+    tenant_id: str | None,
+    exclude_memory_id: str | None = None,
+    top_k: int = LINK_CANDIDATE_TOP_K,
+) -> list[tuple[str, float, dict[str, Any]]]:
+    """Similar memories for linking — org-wide within tenant, not AND-scoped to space tokens."""
+    candidates = find_candidates(engine, content, scope=None, top_k=top_k)
+    candidates = _filter_candidates_by_tenant(candidates, tenant_id)
+    if exclude_memory_id:
+        candidates = [
+            (memory_id, score, memory)
+            for memory_id, score, memory in candidates
+            if memory_id != exclude_memory_id
+        ]
+    return candidates
+
+
+def _ingest_scope_context(
+    *,
+    scope: list[str] | None,
+    event_metadata: dict[str, object] | None,
+    space_context: dict[str, str] | None,
+    candidate_scope: list[str] | None,
+) -> tuple[list[str], str | None, list[str]]:
+    request_scope = list(scope or [])
+    if space_context is None and event_metadata:
+        backup = event_metadata.get("space_context")
+        if isinstance(backup, dict) and backup.get("active_space_token"):
+            space_context = backup
+    active_space_token = (space_context or {}).get("active_space_token")
+    tenant_id = _tenant_id_from_metadata(event_metadata)
+    if not tenant_id:
+        for token in request_scope:
+            if str(token).startswith("org:"):
+                tenant_id = str(token)[4:]
+                break
+    if tenant_id:
+        request_scope = merge_org_scope(request_scope, tenant_id)
+    search_scope = list(candidate_scope or request_scope or [])
+    if not search_scope and active_space_token:
+        search_scope = [active_space_token]
+    if tenant_id and not any(str(token).startswith("org:") for token in search_scope):
+        search_scope = merge_org_scope(search_scope, tenant_id)
+    return request_scope, tenant_id, search_scope
+
+
+def _auto_link_neighbors_by_similarity(
+    engine: ArthaEngine,
+    memory_id: str,
+    content: str,
+    *,
+    scope: list[str] | None = None,
+    event_metadata: dict[str, object] | None = None,
+    tenant_id: str | None = None,
+    min_score: float = AUTO_LINK_MIN_SCORE,
+    top_k: int = LINK_CANDIDATE_TOP_K,
+) -> int:
+    """Create semantic links from an existing memory to similar neighbors (Guardian fallback)."""
+    _require_memory_projections(engine)
+    request_scope, resolved_tenant, _search_scope = _ingest_scope_context(
+        scope=scope,
+        event_metadata=event_metadata,
+        space_context=None,
+        candidate_scope=None,
+    )
+    tenant_id = tenant_id or resolved_tenant
+    candidates = _find_link_candidates(
+        engine,
+        content,
+        tenant_id=tenant_id,
+        exclude_memory_id=memory_id,
+        top_k=top_k,
+    )
+    candidates = [
+        (candidate_id, score, memory)
+        for candidate_id, score, memory in candidates
+        if score >= min_score
+    ]
+    if not candidates:
+        return 0
+    candidate_ids = [candidate_id for candidate_id, _score, _memory in candidates]
+    memories_by_id = {candidate_id: memory for candidate_id, _score, memory in candidates}
+    connections: list[ConnectionSpec] = []
+    for candidate_id, score, memory in candidates[:MAX_GUARDIAN_LINKS]:
+        snippet = str(memory.get("content", "")).strip()[:80] or candidate_id
+        connections.append(
+            ConnectionSpec(
+                target_id=candidate_id,
+                description=(
+                    f"How does this memory relate to '{snippet}'? "
+                    f"What shared context connects them (similarity {score:.2f})?"
+                ),
+            )
+        )
+    plan = GuardianWritePlan(
+        action="create",
+        target_memory_id=None,
+        reasoning="auto-linked by embedding similarity",
+        final_content=content,
+        scope=request_scope,
+        connections=connections,
+        links_to_remove=[],
+    )
+    _apply_guardian_links(
+        engine,
+        memory_id,
+        request_scope,
+        plan,
+        candidate_ids,
+        memories_by_id,
+        event_metadata=event_metadata,
+    )
+    refresh_memory_projections(engine)
+    return len(connections)
+
+
+async def link_memory_with_guardian(
+    engine: ArthaEngine,
+    guardian: AgnoGuardian,
+    *,
+    memory_id: str,
+    content: str,
+    scope: list[str] | None = None,
+    event_metadata: dict[str, object] | None = None,
+    space_context: dict[str, str] | None = None,
+    candidate_scope: list[str] | None = None,  # noqa: ARG001 — ignored; linking is org-wide
+) -> int:
+    """Run Guardian link planning for an existing memory without changing its content."""
+    _require_memory_projections(engine)
+    request_scope, tenant_id, _search_scope = _ingest_scope_context(
+        scope=scope,
+        event_metadata=event_metadata,
+        space_context=space_context,
+        candidate_scope=None,
+    )
+    candidates = _find_link_candidates(
+        engine,
+        content,
+        tenant_id=tenant_id,
+        exclude_memory_id=memory_id,
+    )
+    if not candidates:
+        return 0
+    candidate_ids = [candidate_id for candidate_id, _score, _memory in candidates]
+    memories_by_id = {candidate_id: memory for candidate_id, _score, memory in candidates}
+    try:
+        memories_by_id.setdefault(memory_id, get_memory(engine, memory_id))
+    except KeyError:
+        pass
+    if tenant_id:
+        for row in _list_memory_rows(engine):
+            memory = _row_to_memory_dict(row)
+            if _memory_belongs_to_tenant(memory, tenant_id):
+                memories_by_id.setdefault(row["artha_id"], memory)
+
+    if not settings.openrouter_api_key:
+        return _auto_link_neighbors_by_similarity(
+            engine,
+            memory_id,
+            content,
+            scope=request_scope,
+            event_metadata=event_metadata,
+            tenant_id=tenant_id,
+        )
+
+    linked = 0
+    try:
+        plan = await guardian.plan_write(content, candidates, space_context=space_context)
+        merged_scope = list(request_scope)
+        for token in plan.scope or []:
+            if token not in merged_scope:
+                merged_scope.append(token)
+        if space_context:
+            merged_scope = apply_guardian_space_scope(merged_scope, space_context=space_context)
+        if tenant_id:
+            merged_scope = merge_org_scope(merged_scope, tenant_id)
+        linked = _apply_guardian_links(
+            engine,
+            memory_id,
+            merged_scope,
+            plan,
+            candidate_ids,
+            memories_by_id,
+            event_metadata=event_metadata,
+        )
+    except GuardianError:
+        linked = 0
+
+    if linked == 0:
+        linked = _auto_link_neighbors_by_similarity(
+            engine,
+            memory_id,
+            content,
+            scope=request_scope,
+            event_metadata=event_metadata,
+            tenant_id=tenant_id,
+        )
+
+    refresh_memory_projections(engine)
+    return linked
+
+
+async def ingest_memory(
+    engine: ArthaEngine,
+    guardian: AgnoGuardian,
+    *,
+    content: str,
+    scope: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    external_identity: dict[str, str] | None = None,
+    event_metadata: dict[str, object] | None = None,
+    space_context: dict[str, str] | None = None,
+    candidate_scope: list[str] | None = None,
+) -> dict[str, Any]:
+    _require_memory_projections(engine)
+    metadata = metadata or {}
+    external_identity = {
+        **_external_identity_from_metadata(metadata),
+        **external_identity_from_values(**(external_identity or {})),
+    }
+    ingest_event_metadata = {**(event_metadata or {}), **external_identity}
+    request_scope, tenant_id, search_scope = _ingest_scope_context(
+        scope=scope,
+        event_metadata=ingest_event_metadata,
+        space_context=space_context,
+        candidate_scope=candidate_scope,
+    )
+    candidates = find_candidates(engine, content, scope=search_scope or None)
+    candidates = _filter_candidates_by_tenant(candidates, tenant_id)
+    external_match = _find_external_identity_match(
+        engine,
+        external_identity=external_identity,
+        tenant_id=tenant_id,
+        scope=request_scope,
+        space_context=space_context,
+        node_type="text",
+    )
+    if external_match is not None and all(
+        memory_id != external_match["id"] for memory_id, _score, _memory in candidates
+    ):
+        candidates.insert(0, (str(external_match["id"]), 1.0, external_match))
+    candidate_ids = [memory_id for memory_id, _score, _memory in candidates]
+    memories_by_id = {memory_id: memory for memory_id, _score, memory in candidates}
+    if tenant_id:
+        for row in _list_memory_rows(engine):
+            memory = _row_to_memory_dict(row)
+            if _memory_belongs_to_tenant(memory, tenant_id):
+                memories_by_id.setdefault(row["artha_id"], memory)
+    else:
+        for row in _list_memory_rows(engine):
+            memories_by_id.setdefault(row["artha_id"], _row_to_memory_dict(row))
+
+    plan = await guardian.plan_write(content, candidates, space_context=space_context)
+    merged_scope = list(request_scope)
+    for token in plan.scope or []:
+        if token not in merged_scope:
+            merged_scope.append(token)
+    if space_context:
+        merged_scope = apply_guardian_space_scope(merged_scope, space_context=space_context)
+    action = plan.action
+    external_target_id = str(external_match["id"]) if external_match is not None else None
+    if action == "create" and external_target_id:
+        action = "update"
+
+    def _final_scope() -> list[str]:
+        scoped = list(merged_scope)
+        if tenant_id:
+            scoped = merge_org_scope(scoped, tenant_id)
+        if space_context:
+            scoped = apply_guardian_space_scope(scoped, space_context=space_context)
+        return scoped
+
+    if action == "update":
+        target_id = _resolve_update_target(
+            engine,
+            target_id=external_target_id or plan.target_memory_id,
+            tenant_id=tenant_id,
+            candidates=candidates,
+        )
+        if not target_id:
+            action = "create"
+        else:
+            existing_raw = engine.store.get(target_id)
+            if existing_raw is None:
+                action = "create"
+            else:
+                existing = _coerce_memory_arthaanu(engine, existing_raw)
+                if not _guardian_may_update_target(existing):
+                    action = "create"
+                else:
+                    rich = _rich_fields_from_memory(existing)
+                    retrieval_count = existing.value.retrieval_count
+                    memory = _encode_memory(
+                        engine,
+                        content=plan.final_content,
+                        scope=_final_scope(),
+                        node_type=rich["node_type"],
+                        payload=rich["payload"],
+                        perception=plan.final_content,
+                        encoding=rich["encoding"],
+                        metadata=_metadata_with_external_identity(
+                            _merge_memory_metadata(rich["metadata"], metadata),
+                            external_identity,
+                        ),
+                        artha_id=target_id,
+                        retrieval_count=retrieval_count,
+                        persist=False,
+                    )
+                    _append_memory_event(
+                        engine,
+                        event_type="memory.updated",
+                        memory=memory,
+                        component="memuron.ingest.guardian",
+                        extra_payload={
+                            "reasoning": plan.reasoning,
+                            "idempotency_match": bool(external_target_id),
+                        },
+                        event_metadata=ingest_event_metadata,
+                    )
+                    memory_id = target_id
+                    result_action = "updated"
+
+    if action == "create":
+        memory = _encode_memory(
+            engine,
+            content=plan.final_content,
+            scope=_final_scope(),
+            metadata=_metadata_with_external_identity(metadata, external_identity),
+            persist=False,
+        )
+        _append_memory_event(
+            engine,
+            event_type="memory.created",
+            memory=memory,
+            component="memuron.ingest.guardian",
+            extra_payload={"reasoning": plan.reasoning},
+            event_metadata=ingest_event_metadata,
+        )
+        memory_id = memory.artha_id
+        result_action = "created"
+
+    final_scope = _final_scope()
+    memories_by_id.setdefault(memory_id, memory_payload(engine, memory_id))
+    _apply_guardian_links(
+        engine,
+        memory_id,
+        final_scope,
+        plan,
+        candidate_ids,
+        memories_by_id,
+        event_metadata=ingest_event_metadata,
+    )
+    refresh_memory_projections(engine)
+    payload = memory_payload(engine, memory_id)
+    return {
+        "status": "success",
+        "memory_id": memory_id,
+        "action": result_action,
+        "memory": payload,
+    }
+
+
+def _linked_memory_ids(engine: ArthaEngine, memory_id: str) -> list[str]:
+    store = engine.store
+    if sql_store_has_tables(store):
+        rows = sql_store_fetchall(
+            store,
+            """
+            SELECT source_id, target_id FROM memuron_links
+            WHERE source_id = ? OR target_id = ?
+            """,
+            (memory_id, memory_id),
+        )
+    else:
+        rows = []
+        for item in getattr(store, "memuron_links", {}).values():
+            if item["source_id"] == memory_id or item["target_id"] == memory_id:
+                rows.append(item)
+    linked: set[str] = set()
+    for row in rows:
+        source_id = row["source_id"]
+        target_id = row["target_id"]
+        if source_id != memory_id:
+            linked.add(source_id)
+        if target_id != memory_id:
+            linked.add(target_id)
+    return sorted(linked)
+
+
+def _evolution_history(engine: ArthaEngine, memory_id: str) -> list[dict[str, Any]]:
+    list_events = getattr(engine.store, "list_events", None)
+    if not callable(list_events):
+        return []
+    events = list_events(artha_id=memory_id, limit=100)
+    history: list[dict[str, Any]] = []
+    for event in reversed(events):
+        event_type = str(event.get("event_type", ""))
+        payload = event.get("payload") if isinstance(event.get("payload"), dict) else {}
+        domain_event_type = str(payload.get("domain_event_type") or "")
+        if event_type == "delete" and domain_event_type:
+            event_type = domain_event_type
+        if event_type not in {"memory.created", "memory.updated", "memory.deleted"}:
+            continue
+        history.append(
+            {
+                "event_type": event_type,
+                "timestamp": event.get("created_at"),
+                "component": event.get("component"),
+                "reasoning": payload.get("reasoning"),
+                "actor_id": payload.get("actor_id"),
+                "tenant_id": payload.get("tenant_id"),
+            }
+        )
+    return history
+
+
+def memory_payload(engine: ArthaEngine, memory_id: str) -> dict[str, Any]:
+    rows = [
+        row for row in _list_memory_rows(engine) if row["artha_id"] == memory_id
+    ]
+    if rows:
+        memory = _row_to_memory_dict(rows[0])
+    else:
+        item = engine.store.require(memory_id)
+        if not isinstance(item, MemoryArthaanu):
+            item = arthaanu_from_dict(
+                arthaanu_to_dict(item),
+                type_registry=engine.registry.arthaanu_types,
+            )
+        memory = {
+            "id": item.artha_id,
+            "content": item.value.content,
+            "node_type": getattr(item.value, "node_type", "text"),
+            "payload": getattr(item.value, "payload", {}),
+            "perception": getattr(item.value, "perception", None) or item.value.content,
+            "encoding": getattr(item.value, "encoding", "memory"),
+            "metadata": getattr(item.value, "metadata", {}),
+            "scope": list(item.value.scope),
+            "embedding": list(item.value.embedding),
+            "timestamp": _now_stamp(),
+        }
+    node_type = str(memory.get("node_type") or "text")
+    content = str(memory["content"])
+    preview = " ".join(content.split())
+    payload = memory.get("payload") or {}
+    external_identity = {
+        **_external_identity_from_payload(payload if isinstance(payload, dict) else {}),
+        **_external_identity_from_metadata(memory.get("metadata")),
+    }
+    if isinstance(payload, dict) and node_type == "collection" and memory.get("encoding") == "document_collection":
+        source_placement = next(
+            (
+                _placement_row_to_dict(row)
+                for row in _list_placement_rows(engine)
+                if str(row["parent_id"]) == memory_id
+                and (
+                    _parse_json_field(row.get("metadata_json"), {}).get("role")
+                    if isinstance(_parse_json_field(row.get("metadata_json"), {}), dict)
+                    else None
+                )
+                == "source"
+            ),
+            None,
+        )
+        document_id = (
+            str(source_placement["child_id"])
+            if source_placement
+            else payload.get("document_id")
+        )
+        payload = {
+            "collection_kind": "document",
+            "document_id": document_id,
+            "document": payload.get("document")
+            or {
+                "id": document_id,
+                "file_name": payload.get("name"),
+                "source_type": payload.get("source_type"),
+                "chunk_count": payload.get("chunk_count", 0),
+                "image_count": payload.get("image_count", 0),
+                "graph_image_count": payload.get("graph_image_count", 0),
+            },
+            **payload,
+        }
+    return {
+        "id": memory["id"],
+        "content": content,
+        "preview": preview[:240] + ("..." if len(preview) > 240 else ""),
+        "content_length": len(content),
+        "truncated": len(preview) > 240,
+        "type": node_type,
+        "node_type": node_type,
+        "payload": payload,
+        "perception": memory.get("perception") or content,
+        "encoding": memory.get("encoding") or "memory",
+        "metadata": memory.get("metadata") or {},
+        **{key: external_identity.get(key) for key in EXTERNAL_ID_FIELDS},
+        "scope": memory.get("scope") or [],
+        "links": _linked_memory_ids(engine, memory_id),
+        "evolution_history": _evolution_history(engine, memory_id),
+        "retrieval_count": 0,
+        "timestamp": memory.get("timestamp") or _now_stamp(),
+    }
+
+
+def get_memory(engine: ArthaEngine, memory_id: str) -> dict[str, Any]:
+    if engine.store.get(memory_id) is None:
+        rows = [row for row in _list_memory_rows(engine) if row["artha_id"] == memory_id]
+        if not rows:
+            raise KeyError(f"Memory not found: {memory_id}")
+    return memory_payload(engine, memory_id)
+
+
+def get_memories(engine: ArthaEngine, memory_ids: list[str]) -> list[dict[str, Any]]:
+    memories: list[dict[str, Any]] = []
+    for memory_id in memory_ids:
+        try:
+            memories.append(get_memory(engine, memory_id))
+        except KeyError:
+            continue
+    return memories
+
+
+def update_memory(
+    engine: ArthaEngine,
+    memory_id: str,
+    *,
+    content: str | None = None,
+    scope: list[str] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    existing = _coerce_memory_arthaanu(engine, engine.store.require(memory_id))
+    rich = _rich_fields_from_memory(existing)
+    new_scope = scope if scope is not None else list(existing.value.scope)
+    if content is not None:
+        new_content = content
+        new_perception = content
+    else:
+        new_content = existing.value.content
+        new_perception = rich["perception"]
+    memory = _encode_memory(
+        engine,
+        content=new_content,
+        scope=new_scope,
+        node_type=rich["node_type"],
+        payload=rich["payload"],
+        perception=new_perception,
+        encoding=rich["encoding"],
+        metadata=rich["metadata"],
+        artha_id=memory_id,
+        retrieval_count=existing.value.retrieval_count,
+        persist=False,
+    )
+    _append_memory_event(
+        engine,
+        event_type="memory.updated",
+        memory=memory,
+        component="memuron.update",
+        event_metadata=event_metadata,
+    )
+    if scope is not None and rich["node_type"] == "collection":
+        _propagate_parent_scope_to_children(
+            engine,
+            parent_id=memory_id,
+            parent_scope=new_scope,
+            event_metadata=event_metadata,
+        )
+    refresh_memory_projections(engine)
+    return memory_payload(engine, memory_id)
+
+
+def _scope_tokens(scope: list[str], prefix: str) -> list[str]:
+    return [token for token in scope if token.startswith(prefix)]
+
+
+def _merge_inherited_scope(child_scope: list[str], parent_scope: list[str]) -> list[str]:
+    parent_org = _scope_tokens(parent_scope, "org:")
+    parent_space = _scope_tokens(parent_scope, "space.")
+    if not parent_org and not parent_space:
+        return list(child_scope)
+    inherited = [*parent_org, *parent_space]
+    output = [
+        token
+        for token in child_scope
+        if not token.startswith("org:") and not token.startswith("space.")
+    ]
+    for token in inherited:
+        if token not in output:
+            output.append(token)
+    return output
+
+
+def _append_scope_update(
+    engine: ArthaEngine,
+    *,
+    memory_id: str,
+    scope: list[str],
+    component: str,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    existing = _coerce_memory_arthaanu(engine, engine.store.require(memory_id))
+    if list(existing.value.scope) == scope:
+        return memory_payload(engine, memory_id)
+    rich = _rich_fields_from_memory(existing)
+    memory = _encode_memory(
+        engine,
+        content=existing.value.content,
+        scope=scope,
+        node_type=rich["node_type"],
+        payload=rich["payload"],
+        perception=rich["perception"],
+        encoding=rich["encoding"],
+        metadata=rich["metadata"],
+        artha_id=memory_id,
+        retrieval_count=existing.value.retrieval_count,
+        persist=False,
+    )
+    _append_memory_event(
+        engine,
+        event_type="memory.updated",
+        memory=memory,
+        component=component,
+        extra_payload={"reason": "placement_scope_inheritance"},
+        event_metadata=event_metadata,
+    )
+    return {
+        "id": memory_id,
+        "scope": scope,
+        "node_type": rich["node_type"],
+    }
+
+
+def _child_placements(engine: ArthaEngine, parent_id: str) -> list[dict[str, Any]]:
+    placements = []
+    for row in _list_placement_rows(engine):
+        placement = _placement_row_to_dict(row)
+        if str(placement["parent_id"]) == parent_id:
+            placements.append(placement)
+    return placements
+
+
+def _append_placement_scope_update(
+    engine: ArthaEngine,
+    *,
+    placement: dict[str, Any],
+    parent_scope: list[str],
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    new_scope = _merge_inherited_scope(
+        list(placement.get("scope") or []),
+        parent_scope,
+    )
+    if new_scope == list(placement.get("scope") or []):
+        return placement
+    updated = engine.encode(
+        "memory_placement",
+        {
+            "artha_id": placement["id"],
+            "parent_id": placement["parent_id"],
+            "child_id": placement["child_id"],
+            "name": placement["name"],
+            "scope": new_scope,
+            "metadata": placement.get("metadata") or {},
+            "inherit_parent_scope": True,
+        },
+        persist=False,
+    )
+    engine.store.append_event(
+        event_type="placement.created",
+        arthaanu=updated,
+        component="memuron.placement_scope",
+        payload={
+            **(event_metadata or {}),
+            "reason": "placement_scope_inheritance",
+        },
+    )
+    return {**placement, "scope": new_scope}
+
+
+def _propagate_parent_scope_to_children(
+    engine: ArthaEngine,
+    *,
+    parent_id: str,
+    parent_scope: list[str],
+    event_metadata: dict[str, object] | None = None,
+) -> list[dict[str, Any]]:
+    changed: list[dict[str, Any]] = []
+    for placement in _child_placements(engine, parent_id):
+        if not placement.get("inherit_parent_scope", True):
+            continue
+        placement = _append_placement_scope_update(
+            engine,
+            placement=placement,
+            parent_scope=parent_scope,
+            event_metadata=event_metadata,
+        )
+        changed.extend(
+            _propagate_scope_to_node_and_descendants(
+                engine,
+                node_id=str(placement["child_id"]),
+                parent_scope=parent_scope,
+                event_metadata=event_metadata,
+            )
+        )
+    return changed
+
+
+def _propagate_scope_to_node_and_descendants(
+    engine: ArthaEngine,
+    *,
+    node_id: str,
+    parent_scope: list[str],
+    event_metadata: dict[str, object] | None = None,
+) -> list[dict[str, Any]]:
+    try:
+        child = _coerce_memory_arthaanu(engine, engine.store.require(node_id))
+    except KeyError:
+        return []
+    new_scope = _merge_inherited_scope(list(child.value.scope), parent_scope)
+    changed: list[dict[str, Any]] = []
+    child_result = _append_scope_update(
+        engine,
+        memory_id=node_id,
+        scope=new_scope,
+        component="memuron.placement_scope",
+        event_metadata=event_metadata,
+    )
+    if list(child.value.scope) != new_scope:
+        changed.append(child_result)
+    changed.extend(
+        _propagate_parent_scope_to_children(
+            engine,
+            parent_id=node_id,
+            parent_scope=new_scope,
+            event_metadata=event_metadata,
+        )
+    )
+    return changed
+
+
+def delete_memory(
+    engine: ArthaEngine,
+    memory_id: str,
+    *,
+    event_metadata: dict[str, object] | None = None,
+) -> bool:
+    existing = engine.store.get(memory_id)
+    if existing is None:
+        return False
+    if not isinstance(existing, MemoryArthaanu):
+        existing = arthaanu_from_dict(
+            arthaanu_to_dict(existing),
+            type_registry=engine.registry.arthaanu_types,
+        )
+    for link_id in _find_links_for_memory(engine, memory_id):
+        _remove_link(engine, link_id, event_metadata=event_metadata)
+    engine.semantic_delete(
+        memory_id,
+        event_type="delete",
+        component="memuron.delete",
+        metadata={
+            "domain_event_type": "memory.deleted",
+            **(event_metadata or {}),
+        },
+    )
+    refresh_memory_projections(engine)
+    return True
+
+
+def _find_links_for_memory(engine: ArthaEngine, memory_id: str) -> list[str]:
+    store = engine.store
+    if sql_store_has_tables(store):
+        rows = sql_store_fetchall(
+            store,
+            """
+            SELECT link_id FROM memuron_links
+            WHERE source_id = ? OR target_id = ?
+            """,
+            (memory_id, memory_id),
+        )
+        return [str(row["link_id"]) for row in rows]
+    bucket = getattr(store, "memuron_links", {})
+    return [
+        link_id
+        for link_id, item in bucket.items()
+        if item["source_id"] == memory_id or item["target_id"] == memory_id
+    ]
+
+
+def bulk_delete_memories(
+    engine: ArthaEngine,
+    *,
+    scope: str | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> tuple[int, list[str]]:
+    scope_patterns = parse_comma_scope(scope)
+    if not scope_patterns:
+        raise ValueError("scope is required for bulk delete")
+    deleted_ids: list[str] = []
+    for row in _list_memory_rows(engine):
+        memory = _row_to_memory_dict(row)
+        if scope_patterns and not scope_matches_filter(memory.get("scope") or [], scope_patterns):
+            continue
+        if delete_memory(engine, memory["id"], event_metadata=event_metadata):
+            deleted_ids.append(memory["id"])
+    return len(deleted_ids), deleted_ids
+
+
+def count_memories(
+    engine: ArthaEngine,
+    *,
+    scope: str | None = None,
+) -> tuple[int, dict[str, Any]]:
+    scope_patterns = [part.strip() for part in (scope or "").split(",") if part.strip()]
+    filters: dict[str, Any] = {}
+    if scope_patterns:
+        filters["scope"] = scope_patterns
+    rows = _filtered_memory_rows(engine, scope=scope_patterns or None)
+    return len(rows), filters
+
+
+def list_memories(
+    engine: ArthaEngine,
+    *,
+    scope: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+) -> tuple[list[dict[str, Any]], int, dict[str, Any]]:
+    scope_patterns = [part.strip() for part in (scope or "").split(",") if part.strip()]
+    filters: dict[str, Any] = {}
+    if scope_patterns:
+        filters["scope"] = scope_patterns
+
+    rows = _filtered_memory_rows(engine, scope=scope_patterns or None)
+    page = rows[offset : offset + limit]
+    memories = [memory_payload(engine, row["artha_id"]) for row in page]
+    return memories, len(rows), filters
+
+
+def create_rich_node(
+    engine: ArthaEngine,
+    *,
+    content: str,
+    node_type: str = "text",
+    payload: dict[str, Any] | None = None,
+    perception: str | None = None,
+    encoding: str = "memory",
+    metadata: dict[str, Any] | None = None,
+    external_identity: dict[str, str] | None = None,
+    scope: list[str] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    external_identity = external_identity_from_values(**(external_identity or {}))
+    node = _encode_memory(
+        engine,
+        content=content,
+        scope=scope,
+        node_type=node_type,
+        payload=_payload_with_external_identity(payload, external_identity),
+        perception=perception,
+        encoding=encoding,
+        metadata=_metadata_with_external_identity(metadata, external_identity),
+        persist=False,
+    )
+    event_type = "collection.created" if node_type == "collection" else "memory.created"
+    _append_memory_event(
+        engine,
+        event_type=event_type,
+        memory=node,
+        component="memuron.nodes",
+        event_metadata={**(event_metadata or {}), **external_identity},
+    )
+    refresh_memory_projections(engine)
+    return memory_payload(engine, node.artha_id)
+
+
+def create_collection(
+    engine: ArthaEngine,
+    *,
+    name: str,
+    summary: str,
+    scope: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    payload = {"name": name, "summary": summary}
+    return create_rich_node(
+        engine,
+        content=summary,
+        node_type="collection",
+        payload=payload,
+        perception=summary,
+        encoding="collection_summary",
+        metadata=metadata,
+        scope=scope,
+        event_metadata=event_metadata,
+    )
+
+
+def ingest_document_source(
+    engine: ArthaEngine,
+    *,
+    file_name: str,
+    content_type: str | None,
+    file_bytes: bytes,
+    scope: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    external_identity: dict[str, str] | None = None,
+    source_metadata: dict[str, Any] | None = None,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    """Parse a source file and append document/collection/chunk semantic events."""
+
+    external_identity = {
+        **_external_identity_from_metadata(metadata),
+        **external_identity_from_values(**(external_identity or {})),
+    }
+    parsed = parse_source(
+        file_name=file_name,
+        content_type=content_type,
+        file_bytes=file_bytes,
+        describe_images=settings.describe_images,
+        vlm_api_key=settings.openrouter_api_key,
+        vlm_model=settings.image_vlm_model,
+        vlm_timeout_seconds=settings.image_vlm_timeout_seconds,
+    )
+    if source_metadata:
+        parsed = replace(
+            parsed,
+            source_metadata={**parsed.source_metadata, **source_metadata},
+        )
+    document_key = str(uuid4())
+    source_object = maybe_store_source_file(
+        org_id=_tenant_id_from_metadata(event_metadata),
+        document_key=document_key,
+        file_name=parsed.file_name,
+        content_type=content_type or parsed.media_type,
+        file_bytes=file_bytes,
+    )
+    source_object_ref = {"document_key": document_key}
+    base_scope = list(scope or [])
+    document_scope = _document_scope(base_scope, document_key)
+    user_metadata = _metadata_with_external_identity(metadata, external_identity)
+    common_event_metadata = {
+        **(event_metadata or {}),
+        **external_identity,
+        "document_key": document_key,
+        "parser": "memuron.documents.parser",
+        "source_type": parsed.source_type,
+    }
+    graph_images = [image for image in parsed.images if image.include_in_graph]
+    skipped_image_count = len(parsed.images) - len(graph_images)
+
+    summary = _document_summary(parsed)
+    collection = _encode_memory(
+        engine,
+        content=summary,
+        scope=document_scope,
+        node_type="collection",
+        payload={
+            "name": parsed.file_name,
+            "summary": summary,
+            "document_key": document_key,
+            "source_type": parsed.source_type,
+            "chunk_count": len(parsed.chunks),
+            "image_count": len(parsed.images),
+            "graph_image_count": len(graph_images),
+            "skipped_image_count": skipped_image_count,
+            "source_object_ref": source_object_ref,
+            "source_identity": external_identity,
+        },
+        perception=summary,
+        encoding="document_collection",
+        metadata=_document_metadata(
+            user_metadata,
+            document_key=document_key,
+            role="document_collection",
+            parsed=parsed,
+        ),
+        persist=False,
+    )
+    _append_memory_event(
+        engine,
+        event_type="collection.created",
+        memory=collection,
+        component="memuron.documents",
+        event_metadata=common_event_metadata,
+    )
+
+    source_node_type = "image" if parsed.source_type == "image" else "document"
+    document = _encode_memory(
+        engine,
+        content=summary,
+        scope=document_scope,
+        node_type=source_node_type,
+        payload={
+            "file_name": parsed.file_name,
+            "media_type": parsed.media_type,
+            "source_type": parsed.source_type,
+            "size_bytes": len(file_bytes),
+            "document_key": document_key,
+            "collection_id": collection.artha_id,
+            "chunk_count": len(parsed.chunks),
+            "image_count": len(parsed.images),
+            "graph_image_count": len(graph_images),
+            "skipped_image_count": skipped_image_count,
+            "page_count": parsed.page_count,
+            "unreadable_pages": parsed.unreadable_pages,
+            "source_metadata": parsed.source_metadata,
+            "markdown_preview": parsed.markdown[:DOCUMENT_MARKDOWN_PREVIEW_CHARS],
+            "markdown_truncated": len(parsed.markdown) > DOCUMENT_MARKDOWN_PREVIEW_CHARS,
+            "source_object": source_object,
+            "source_identity": external_identity,
+        },
+        perception=summary,
+        encoding=f"{parsed.source_type}_source",
+        metadata=_document_metadata(
+            user_metadata,
+            document_key=document_key,
+            role="source",
+            parsed=parsed,
+        ),
+        persist=False,
+    )
+    _append_memory_event(
+        engine,
+        event_type="memory.created",
+        memory=document,
+        component="memuron.documents",
+        event_metadata=common_event_metadata,
+    )
+
+    collection_payload = {
+        **dict(collection.value.payload),
+        "collection_kind": "document",
+        "document_id": document.artha_id,
+        "document": {
+            "id": document.artha_id,
+            "file_name": parsed.file_name,
+            "source_type": parsed.source_type,
+            "media_type": parsed.media_type,
+            "chunk_count": len(parsed.chunks),
+            "image_count": len(parsed.images),
+            "graph_image_count": len(graph_images),
+            "source_object_ref": {
+                "document_id": document.artha_id,
+                "document_key": document_key,
+            },
+            "source_identity": external_identity,
+        },
+    }
+    collection_metadata = _document_metadata(
+        {
+            **user_metadata,
+            "document_id": document.artha_id,
+            "collection_kind": "document",
+        },
+        document_key=document_key,
+        role="document_collection",
+        parsed=parsed,
+    )
+    collection_update = _encode_memory(
+        engine,
+        content=summary,
+        scope=document_scope,
+        node_type="collection",
+        payload=collection_payload,
+        perception=summary,
+        encoding="document_collection",
+        metadata=collection_metadata,
+        artha_id=collection.artha_id,
+        persist=False,
+    )
+    _append_memory_event(
+        engine,
+        event_type="memory.updated",
+        memory=collection_update,
+        component="memuron.documents",
+        extra_payload={"reason": "document_container_source_link"},
+        event_metadata=common_event_metadata,
+    )
+
+    placements: list[dict[str, Any]] = [
+        _append_placement(
+            engine,
+            parent_id=collection.artha_id,
+            child_id=document.artha_id,
+            name=f"source:{parsed.file_name}",
+            scope=document_scope,
+            metadata={"role": "source", "document_key": document_key, **external_identity},
+            event_metadata=common_event_metadata,
+        )
+    ]
+
+    image_ids: list[str] = []
+    image_attachments: list[dict[str, Any]] = []
+    if parsed.source_type != "image":
+        for image in graph_images:
+            image_node = _encode_memory(
+                engine,
+                content=image.description,
+                scope=[*document_scope, "kind:document_image"],
+                node_type="image",
+                payload={
+                    "document_key": document_key,
+                    "document_id": document.artha_id,
+                    "collection_id": collection.artha_id,
+                    "source_object_ref": {
+                        "document_id": document.artha_id,
+                        "document_key": document_key,
+                    },
+                    "source_identity": external_identity,
+                    "file_name": image.file_name,
+                    "media_type": image.media_type,
+                    "source": image.source,
+                    "page_number": image.page_number,
+                    "image_index": image.index,
+                    "size_bytes": image.size_bytes,
+                    "description": image.description,
+                    "include_in_graph": image.include_in_graph,
+                    "image_kind": image.image_kind,
+                    "reason": image.reason,
+                    "metadata": image.metadata,
+                },
+                perception=image.description,
+                encoding="image_vlm" if image.metadata.get("parser") == "openrouter_vlm" else "image_metadata",
+                metadata=_document_metadata(
+                    {
+                        **user_metadata,
+                        "image": {
+                            "file_name": image.file_name,
+                            "media_type": image.media_type,
+                            "page_number": image.page_number,
+                            "image_index": image.index,
+                            "source": image.source,
+                            "include_in_graph": image.include_in_graph,
+                            "image_kind": image.image_kind,
+                            "reason": image.reason,
+                            **image.metadata,
+                        },
+                    },
+                    document_key=document_key,
+                    role="image",
+                    parsed=parsed,
+                ),
+                persist=False,
+            )
+            image_event_metadata = {
+                **common_event_metadata,
+                "image_index": image.index,
+                "page_number": image.page_number,
+            }
+            _append_memory_event(
+                engine,
+                event_type="memory.created",
+                memory=image_node,
+                component="memuron.documents",
+                event_metadata=image_event_metadata,
+            )
+            image_ids.append(image_node.artha_id)
+            if image.raw_bytes:
+                image_attachments.append(
+                    {
+                        "memory_id": image_node.artha_id,
+                        "media_type": image.media_type,
+                        "bytes": image.raw_bytes,
+                    }
+                )
+            placements.append(
+                _append_placement(
+                    engine,
+                    parent_id=collection.artha_id,
+                    child_id=image_node.artha_id,
+                    name=f"image-{image.index + 1:04d}:{image.file_name}",
+                    scope=document_scope,
+                    metadata={
+                        "role": "image",
+                        "document_key": document_key,
+                        **external_identity,
+                        "image_index": image.index,
+                        "page_number": image.page_number,
+                    },
+                    event_metadata=image_event_metadata,
+                )
+            )
+
+    chunk_ids: list[str] = []
+    for chunk in parsed.chunks:
+        chunk_node = _encode_memory(
+            engine,
+            content=chunk.text,
+            scope=[*document_scope, "kind:document_chunk"],
+            node_type="text",
+            payload={
+                "document_key": document_key,
+                "document_id": document.artha_id,
+                "collection_id": collection.artha_id,
+                "source_object_ref": {
+                    "document_id": document.artha_id,
+                    "document_key": document_key,
+                },
+                "source_identity": external_identity,
+                "file_name": parsed.file_name,
+                "source_type": parsed.source_type,
+                "chunk_index": chunk.index,
+                "chunk_count": len(parsed.chunks),
+                "location": chunk.to_location(),
+            },
+            perception=chunk.text[:2_000],
+            encoding="document_chunk",
+            metadata=_document_metadata(
+                user_metadata,
+                document_key=document_key,
+                role="chunk",
+                parsed=parsed,
+                chunk_index=chunk.index,
+                chunk_count=len(parsed.chunks),
+                location=chunk.to_location(),
+            ),
+            persist=False,
+        )
+        chunk_event_metadata = {
+            **common_event_metadata,
+            "chunk_index": chunk.index,
+        }
+        _append_memory_event(
+            engine,
+            event_type="memory.created",
+            memory=chunk_node,
+            component="memuron.documents",
+            event_metadata=chunk_event_metadata,
+        )
+        chunk_ids.append(chunk_node.artha_id)
+        placements.append(
+            _append_placement(
+                engine,
+                parent_id=collection.artha_id,
+                child_id=chunk_node.artha_id,
+                name=f"chunk-{chunk.index + 1:04d}",
+                scope=document_scope,
+                metadata={
+                    "role": "chunk",
+                    "document_key": document_key,
+                    **external_identity,
+                    "chunk_index": chunk.index,
+                    "location": chunk.to_location(),
+                },
+                event_metadata=chunk_event_metadata,
+            )
+        )
+
+    refresh_memory_projections(engine)
+    return {
+        "status": "success",
+        "document_key": document_key,
+        **{key: external_identity.get(key) for key in EXTERNAL_ID_FIELDS},
+        "source_type": parsed.source_type,
+        "media_type": parsed.media_type,
+        "file_name": parsed.file_name,
+        "source_object": source_object,
+        "page_count": parsed.page_count,
+        "unreadable_pages": parsed.unreadable_pages,
+        "image_count": len(parsed.images),
+        "graph_image_count": len(graph_images),
+        "skipped_image_count": skipped_image_count,
+        "image_ids": image_ids,
+        "chunk_count": len(parsed.chunks),
+        "chunk_ids": chunk_ids,
+        "collection": memory_payload(engine, collection.artha_id),
+        "document": memory_payload(engine, document.artha_id),
+        "images": [memory_payload(engine, image_id) for image_id in image_ids],
+        "chunks": [memory_payload(engine, chunk_id) for chunk_id in chunk_ids],
+        "placements": [placement_payload(engine, item["id"]) for item in placements],
+        "image_attachments": image_attachments,
+    }
+
+
+def document_source_payload(engine: ArthaEngine, node_id: str) -> dict[str, Any]:
+    """Resolve any document-related node to its original source object."""
+    requested = get_memory(engine, node_id)
+    requested_payload = requested.get("payload") if isinstance(requested.get("payload"), dict) else {}
+    source_object_ref = requested_payload.get("source_object_ref")
+    if not isinstance(source_object_ref, dict):
+        source_object_ref = {}
+    document_descriptor = requested_payload.get("document")
+    if not isinstance(document_descriptor, dict):
+        document_descriptor = {}
+    document_id = (
+        requested_payload.get("document_id")
+        or source_object_ref.get("document_id")
+        or document_descriptor.get("id")
+        or (node_id if requested_payload.get("source_object") else None)
+    )
+    if not document_id:
+        raise KeyError(f"Document source not found for node: {node_id}")
+    document = requested if document_id == node_id else get_memory(engine, str(document_id))
+    document_payload = document.get("payload") if isinstance(document.get("payload"), dict) else {}
+    source_object = document_payload.get("source_object")
+    if not isinstance(source_object, dict) or not source_object:
+        raise KeyError(f"Document source object not found for node: {node_id}")
+    download_url = presign_source_object(source_object)
+    return {
+        "status": "success",
+        "requested_node_id": node_id,
+        "document_id": str(document["id"]),
+        "document_key": str(document_payload.get("document_key") or source_object.get("document_key") or ""),
+        "file_name": str(source_object.get("file_name") or document_payload.get("file_name") or ""),
+        "content_type": str(
+            source_object.get("content_type")
+            or document_payload.get("media_type")
+            or "application/octet-stream"
+        ),
+        "size_bytes": int(source_object.get("size_bytes") or document_payload.get("size_bytes") or 0),
+        "sha256": str(source_object.get("sha256") or ""),
+        "source_object": source_object,
+        "download_url": download_url,
+        "expires_in_seconds": settings.object_storage_presign_seconds if download_url else None,
+    }
+
+
+def _document_scope(scope: list[str], document_key: str) -> list[str]:
+    output = list(scope)
+    token = f"{DOCUMENT_CHUNK_SCOPE_PREFIX}{document_key}"
+    if token not in output:
+        output.append(token)
+    return output
+
+
+def _document_summary(parsed: ParsedDocument) -> str:
+    first_chunk = parsed.chunks[0].text if parsed.chunks else parsed.markdown
+    summary = first_chunk.strip().replace("\n\n", "\n")
+    if len(summary) > 2_000:
+        summary = summary[:1_997].rstrip() + "..."
+    return f"{parsed.file_name}\n\n{summary}"
+
+
+def _document_metadata(
+    metadata: dict[str, Any],
+    *,
+    document_key: str,
+    role: str,
+    parsed: ParsedDocument,
+    chunk_index: int | None = None,
+    chunk_count: int | None = None,
+    location: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    output = dict(metadata)
+    system = dict(output.get("system") or {})
+    document_meta: dict[str, Any] = {
+        "document_key": document_key,
+        "role": role,
+        "file_name": parsed.file_name,
+        "source_type": parsed.source_type,
+        "media_type": parsed.media_type,
+        "page_count": parsed.page_count,
+        "unreadable_pages": list(parsed.unreadable_pages),
+        "source_metadata": dict(parsed.source_metadata),
+    }
+    if chunk_index is not None:
+        document_meta["chunk_index"] = chunk_index
+    if chunk_count is not None:
+        document_meta["chunk_count"] = chunk_count
+    if location is not None:
+        document_meta["location"] = location
+    system["document"] = document_meta
+    output["system"] = system
+    return output
+
+
+def _append_placement(
+    engine: ArthaEngine,
+    *,
+    parent_id: str,
+    child_id: str,
+    name: str,
+    scope: list[str],
+    metadata: dict[str, Any],
+    inherit_parent_scope: bool = True,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    placement = engine.encode(
+        "memory_placement",
+        {
+            "parent_id": parent_id,
+            "child_id": child_id,
+            "name": name,
+            "scope": scope,
+            "metadata": metadata,
+            "inherit_parent_scope": inherit_parent_scope,
+        },
+        persist=False,
+    )
+    engine.store.append_event(
+        event_type="placement.created",
+        arthaanu=placement,
+        component="memuron.documents",
+        payload=event_metadata or {},
+    )
+    return {
+        "id": placement.artha_id,
+        "parent_id": parent_id,
+        "child_id": child_id,
+        "name": name,
+        "scope": scope,
+        "metadata": metadata,
+        "inherit_parent_scope": inherit_parent_scope,
+    }
+
+
+def place_node_in_collection(
+    engine: ArthaEngine,
+    *,
+    parent_id: str,
+    child_id: str,
+    name: str,
+    scope: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    inherit_parent_scope: bool = True,
+    event_metadata: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    parent = get_memory(engine, parent_id)
+    if parent.get("node_type") != "collection":
+        raise ValueError("parent_id must be a collection node")
+    get_memory(engine, child_id)
+    if parent_id == child_id:
+        raise ValueError("collection cannot contain itself")
+    if _placement_would_create_cycle(engine, parent_id=parent_id, child_id=child_id):
+        raise ValueError("placement would create a collection cycle")
+    placement_scope = list(scope or [])
+    if inherit_parent_scope:
+        placement_scope = _merge_inherited_scope(
+            placement_scope,
+            list(parent.get("scope") or []),
+        )
+    placement = engine.encode(
+        "memory_placement",
+        {
+            "parent_id": parent_id,
+            "child_id": child_id,
+            "name": name,
+            "scope": placement_scope,
+            "metadata": metadata or {},
+            "inherit_parent_scope": inherit_parent_scope,
+        },
+        persist=False,
+    )
+    engine.store.append_event(
+        event_type="placement.created",
+        arthaanu=placement,
+        component="memuron.collections",
+        payload=event_metadata or {},
+    )
+    if inherit_parent_scope:
+        _propagate_scope_to_node_and_descendants(
+            engine,
+            node_id=child_id,
+            parent_scope=list(parent.get("scope") or []),
+            event_metadata=event_metadata,
+        )
+    refresh_memory_projections(engine)
+    return placement_payload(engine, placement.artha_id)
+
+
+def _placement_would_create_cycle(engine: ArthaEngine, *, parent_id: str, child_id: str) -> bool:
+    """Return true when adding parent -> child would make child an ancestor of parent."""
+    children_by_parent: dict[str, list[str]] = {}
+    for row in _list_placement_rows(engine):
+        placement = _placement_row_to_dict(row)
+        children_by_parent.setdefault(str(placement["parent_id"]), []).append(str(placement["child_id"]))
+
+    stack = [child_id]
+    seen: set[str] = set()
+    while stack:
+        current = stack.pop()
+        if current == parent_id:
+            return True
+        if current in seen:
+            continue
+        seen.add(current)
+        stack.extend(children_by_parent.get(current, []))
+    return False
+
+
+def _placement_row_to_dict(row: dict[str, Any]) -> dict[str, Any]:
+    scope = _parse_json_field(row.get("scope_json"), [])
+    metadata = _parse_json_field(row.get("metadata_json"), {})
+    return {
+        "id": str(row["placement_id"]),
+        "parent_id": str(row["parent_id"]),
+        "child_id": str(row["child_id"]),
+        "name": str(row["name"]),
+        "scope": scope if isinstance(scope, list) else [],
+        "metadata": metadata if isinstance(metadata, dict) else {},
+        "inherit_parent_scope": bool(row.get("inherit_parent_scope", True)),
+    }
+
+
+def placement_payload(engine: ArthaEngine, placement_id: str) -> dict[str, Any]:
+    for row in _list_placement_rows(engine):
+        if str(row["placement_id"]) == placement_id:
+            return _placement_row_to_dict(row)
+    raise KeyError(f"Placement not found: {placement_id}")
+
+
+def collection_members(engine: ArthaEngine, collection_id: str) -> list[dict[str, Any]]:
+    get_memory(engine, collection_id)
+    members: list[dict[str, Any]] = []
+    for row in _list_placement_rows(engine):
+        if str(row["parent_id"]) != collection_id:
+            continue
+        placement = _placement_row_to_dict(row)
+        try:
+            child = memory_payload(engine, placement["child_id"])
+        except KeyError:
+            continue
+        members.append({"placement": placement, "node": child})
+    return members
+
+
+def _graph_scope_patterns(scope: str | list[str] | None) -> list[str]:
+    if scope is None:
+        return []
+    if isinstance(scope, str):
+        return [part.strip() for part in scope.split(",") if part.strip()]
+    return [str(part).strip() for part in scope if str(part).strip()]
+
+
+def _graph_node_from_memory(
+    memory: dict[str, Any],
+    degree: int = 0,
+    self_loop_count: int = 0,
+) -> dict[str, Any]:
+    content = str(memory.get("content") or "")
+    label = content[:50] + ("..." if len(content) > 50 else "")
+    return {
+        "id": str(memory["id"]),
+        "label": label,
+        "content": content,
+        "node_type": memory.get("node_type") or "text",
+        "payload": memory.get("payload") or {},
+        "perception": memory.get("perception") or content,
+        "encoding": memory.get("encoding") or "memory",
+        "metadata": memory.get("metadata") or {},
+        "scope": list(memory.get("scope") or []),
+        "importance": degree,
+        "degree": degree,
+        "self_loop_count": self_loop_count,
+        "type": memory.get("node_type") or "text",
+        "timestamp": memory.get("timestamp"),
+    }
+
+
+def _graph_edge_from_link(link: dict[str, Any]) -> dict[str, Any]:
+    source_id = str(link["source_id"])
+    target_id = str(link["target_id"])
+    metadata = link.get("metadata") if isinstance(link.get("metadata"), dict) else {}
+    return {
+        "id": str(link["link_id"]),
+        "link_id": str(link["link_id"]),
+        "source": source_id,
+        "target": target_id,
+        "description": str(link.get("description") or ""),
+        "metadata": metadata,
+        "type": "semantic_link",
+        "edge_type": "semantic_link",
+        "directed": False,
+        "is_self_loop": source_id == target_id,
+        "parallel_key": str(link["link_id"]),
+    }
+
+
+def _graph_edge_from_placement(placement: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": str(placement["id"]),
+        "source": str(placement["parent_id"]),
+        "target": str(placement["child_id"]),
+        "description": str(placement["name"]),
+        "type": "placement",
+        "name": str(placement["name"]),
+        "scope": list(placement.get("scope") or []),
+        "metadata": placement.get("metadata") or {},
+    }
+
+
+def export_graph(
+    engine: ArthaEngine,
+    *,
+    scope: str | list[str] | None = None,
+    limit: int = 1000,
+) -> dict[str, Any]:
+    _require_memory_projections(engine)
+    scope_patterns = _graph_scope_patterns(scope)
+    rows = _filtered_memory_rows(engine, scope=scope_patterns or None)[:limit]
+    memories = [_row_to_memory_dict(row) for row in rows]
+    memory_ids = {memory["id"] for memory in memories}
+
+    link_rows: list[dict[str, Any]] = []
+    extra_memory_ids: set[str] = set()
+    for row in _list_link_rows(engine):
+        source_id = str(row["source_id"])
+        target_id = str(row["target_id"])
+        if source_id in memory_ids or target_id in memory_ids:
+            link_rows.append(row)
+            if source_id not in memory_ids:
+                extra_memory_ids.add(source_id)
+            if target_id not in memory_ids:
+                extra_memory_ids.add(target_id)
+
+    if extra_memory_ids:
+        extra_rows = _fetch_memory_rows_by_ids(engine, list(extra_memory_ids))
+        for memory_id, row in extra_rows.items():
+            memories.append(_row_to_memory_dict(row))
+            memory_ids.add(memory_id)
+
+    degree: dict[str, int] = {memory_id: 0 for memory_id in memory_ids}
+    self_loop_count: dict[str, int] = {memory_id: 0 for memory_id in memory_ids}
+    edges: list[dict[str, Any]] = []
+    for row in link_rows:
+        source_id = str(row["source_id"])
+        target_id = str(row["target_id"])
+        if source_id == target_id:
+            self_loop_count[source_id] = self_loop_count.get(source_id, 0) + 1
+        else:
+            degree[source_id] = degree.get(source_id, 0) + 1
+            degree[target_id] = degree.get(target_id, 0) + 1
+        edges.append(_graph_edge_from_link(_link_row_to_dict(row)))
+
+    for row in _list_placement_rows(engine):
+        placement = _placement_row_to_dict(row)
+        parent_id = str(placement["parent_id"])
+        child_id = str(placement["child_id"])
+        if parent_id not in memory_ids or child_id not in memory_ids:
+            continue
+        degree[parent_id] = degree.get(parent_id, 0) + 1
+        degree[child_id] = degree.get(child_id, 0) + 1
+        edges.append(_graph_edge_from_placement(placement))
+
+    nodes = [
+        _graph_node_from_memory(
+            memory,
+            degree=degree.get(str(memory["id"]), 0),
+            self_loop_count=self_loop_count.get(str(memory["id"]), 0),
+        )
+        for memory in memories
+    ]
+    return {
+        "nodes": nodes,
+        "edges": edges,
+        "metadata": {
+            "node_count": len(nodes),
+            "edge_count": len(edges),
+            "scope": scope_patterns,
+            "projection_sources": ["memuron_memories", "memuron_links", "memuron_placements"],
+        },
+    }
+
+
+def graph_hubs(
+    engine: ArthaEngine,
+    *,
+    scope: str | list[str] | None = None,
+    limit: int = 10,
+) -> tuple[list[dict[str, Any]], int]:
+    graph = export_graph(engine, scope=scope)
+    nodes = sorted(
+        graph["nodes"],
+        key=lambda item: (-int(item.get("degree") or 0), str(item.get("id"))),
+    )
+    hubs = [
+        {
+            "id": node["id"],
+            "content": node["content"],
+            "scope": node["scope"],
+            "degree": node["degree"],
+            "hub_score": node["degree"],
+        }
+        for node in nodes[:limit]
+    ]
+    return hubs, len(nodes)
+
+
+def graph_neighborhood(
+    engine: ArthaEngine,
+    *,
+    memory_id: str,
+    hops: int = 2,
+    scope: str | list[str] | None = None,
+) -> dict[str, Any]:
+    graph = export_graph(engine, scope=scope)
+    nodes_by_id = {str(node["id"]): node for node in graph["nodes"]}
+    if memory_id not in nodes_by_id:
+        raise KeyError(f"Memory not found: {memory_id}")
+    adjacency: dict[str, set[str]] = {node_id: set() for node_id in nodes_by_id}
+    for edge in graph["edges"]:
+        source = str(edge["source"])
+        target = str(edge["target"])
+        if source == target:
+            continue
+        adjacency.setdefault(source, set()).add(target)
+        adjacency.setdefault(target, set()).add(source)
+
+    visited = {memory_id: 0}
+    queue: list[tuple[str, int]] = [(memory_id, 0)]
+    while queue:
+        current_id, current_hop = queue.pop(0)
+        if current_hop >= hops:
+            continue
+        for neighbor_id in sorted(adjacency.get(current_id, set())):
+            if neighbor_id in visited:
+                continue
+            visited[neighbor_id] = current_hop + 1
+            queue.append((neighbor_id, current_hop + 1))
+
+    neighborhood = []
+    for node_id, hop_distance in sorted(visited.items(), key=lambda item: (item[1], item[0])):
+        node = nodes_by_id[node_id]
+        neighborhood.append(
+            {
+                "id": node["id"],
+                "content": node["content"],
+                "scope": node["scope"],
+                "hop_distance": hop_distance,
+                "is_center": node_id == memory_id,
+            }
+        )
+    return {
+        "center_memory_id": memory_id,
+        "hops": hops,
+        "neighborhood": neighborhood,
+        "total_in_neighborhood": len(neighborhood),
+    }
+
+
+def graph_path(
+    engine: ArthaEngine,
+    *,
+    from_id: str,
+    to_id: str,
+    scope: str | list[str] | None = None,
+) -> dict[str, Any]:
+    graph = export_graph(engine, scope=scope)
+    nodes_by_id = {str(node["id"]): node for node in graph["nodes"]}
+    if from_id not in nodes_by_id or to_id not in nodes_by_id:
+        raise KeyError("One or both memories not found")
+    if from_id == to_id:
+        return {
+            "status": "success",
+            "path": [from_id],
+            "length": 0,
+            "memories": [{"id": from_id, "content": nodes_by_id[from_id]["content"][:100]}],
+        }
+    adjacency: dict[str, set[str]] = {node_id: set() for node_id in nodes_by_id}
+    for edge in graph["edges"]:
+        source = str(edge["source"])
+        target = str(edge["target"])
+        if source == target:
+            continue
+        adjacency.setdefault(source, set()).add(target)
+        adjacency.setdefault(target, set()).add(source)
+
+    queue: list[tuple[str, list[str]]] = [(from_id, [from_id])]
+    visited = {from_id}
+    while queue:
+        current_id, path = queue.pop(0)
+        for neighbor_id in sorted(adjacency.get(current_id, set())):
+            if neighbor_id == to_id:
+                full_path = [*path, neighbor_id]
+                return {
+                    "status": "success",
+                    "path": full_path,
+                    "length": len(full_path) - 1,
+                    "memories": [
+                        {"id": node_id, "content": nodes_by_id[node_id]["content"][:100]}
+                        for node_id in full_path
+                    ],
+                }
+            if neighbor_id not in visited:
+                visited.add(neighbor_id)
+                queue.append((neighbor_id, [*path, neighbor_id]))
+    return {
+        "status": "no_path",
+        "message": f"No path found between {from_id[:8]}... and {to_id[:8]}...",
+    }
+
+
+def semantic_traverse_graph(
+    engine: ArthaEngine,
+    *,
+    start_memory_id: str,
+    query: str,
+    max_hops: int = 2,
+    edge_similarity_threshold: float = 0.7,
+    scope: str | list[str] | None = None,
+) -> dict[str, Any]:
+    graph = export_graph(engine, scope=scope)
+    nodes_by_id = {str(node["id"]): node for node in graph["nodes"]}
+    if start_memory_id not in nodes_by_id:
+        raise KeyError(f"Memory not found: {start_memory_id}")
+
+    query_vector = _embed_query_vector(engine, query)
+    rows_by_id = {_link_row_to_dict(row)["link_id"]: row for row in _list_link_rows(engine)}
+    adjacency: dict[str, list[dict[str, Any]]] = {node_id: [] for node_id in nodes_by_id}
+    for edge in graph["edges"]:
+        source = str(edge["source"])
+        target = str(edge["target"])
+        row = rows_by_id.get(str(edge["id"]))
+        embedding = _parse_json_field(row.get("embedding_json") if row else None, [])
+        similarity = _cosine_score(
+            query_vector,
+            [float(value) for value in embedding] if isinstance(embedding, list) else [],
+        )
+        edge_with_similarity = {**edge, "similarity": similarity}
+        adjacency.setdefault(source, []).append(edge_with_similarity)
+        if target != source:
+            adjacency.setdefault(target, []).append(edge_with_similarity)
+
+    visited = {start_memory_id: 0}
+    queue: list[tuple[str, int]] = [(start_memory_id, 0)]
+    traversed_edges: list[dict[str, Any]] = []
+    traversed_edge_ids: set[str] = set()
+    while queue:
+        current_id, current_hop = queue.pop(0)
+        if current_hop >= max_hops:
+            continue
+        for edge in sorted(
+            adjacency.get(current_id, []),
+            key=lambda item: (-float(item.get("similarity") or 0), str(item.get("id"))),
+        ):
+            similarity = float(edge.get("similarity") or 0)
+            if similarity < edge_similarity_threshold:
+                continue
+            source = str(edge["source"])
+            target = str(edge["target"])
+            neighbor_id = target if source == current_id else source
+            is_self_loop = source == target
+            if neighbor_id not in nodes_by_id:
+                continue
+            edge_id = str(edge.get("id") or f"{source}:{target}")
+            if edge_id not in traversed_edge_ids:
+                traversed_edge_ids.add(edge_id)
+                traversed_edges.append(
+                    {
+                        "id": edge_id,
+                        "source_id": source,
+                        "target_id": target,
+                        "description": edge.get("description") or "",
+                        "similarity": similarity,
+                        "from_memory_id": current_id,
+                        "to_memory_id": neighbor_id,
+                        "is_self_loop": is_self_loop,
+                    }
+                )
+            if is_self_loop:
+                continue
+            next_hop = current_hop + 1
+            previous_hop = visited.get(neighbor_id)
+            if previous_hop is None or next_hop < previous_hop:
+                visited[neighbor_id] = next_hop
+                queue.append((neighbor_id, next_hop))
+
+    memories = []
+    for memory_id, hop_distance in sorted(visited.items(), key=lambda item: (item[1], item[0])):
+        node = nodes_by_id[memory_id]
+        memories.append(
+            {
+                "id": node["id"],
+                "content": node["content"],
+                "scope": node["scope"],
+                "hop_distance": hop_distance,
+                "is_start": memory_id == start_memory_id,
+            }
+        )
+    traversed_edges.sort(key=lambda edge: float(edge["similarity"]), reverse=True)
+    return {
+        "start_memory_id": start_memory_id,
+        "query": query,
+        "max_hops": max_hops,
+        "edge_similarity_threshold": edge_similarity_threshold,
+        "scope": _graph_scope_patterns(scope),
+        "memories": memories,
+        "traversed_edges": traversed_edges,
+        "total_memories": len(memories),
+        "total_edges": len(traversed_edges),
+    }
+
+
+def _link_row_to_dict(row: dict[str, Any]) -> dict[str, Any]:
+    embedding = row.get("embedding_json")
+    if isinstance(embedding, str):
+        embedding = json.loads(embedding)
+    metadata = _parse_json_field(row.get("metadata_json"), {})
+    return {
+        "link_id": row["link_id"],
+        "source_id": row["source_id"],
+        "target_id": row["target_id"],
+        "description": row["description"],
+        "metadata": metadata if isinstance(metadata, dict) else {},
+        "embedding": embedding if isinstance(embedding, list) else [],
+    }
+
+
+def _memory_endpoint_payload(row: dict[str, Any]) -> dict[str, Any]:
+    memory = _row_to_memory_dict(row)
+    return {
+        "id": memory["id"],
+        "content": memory["content"],
+        "scope": memory.get("scope") or [],
+        "source_metadata": source_identity_from_metadata(memory.get("metadata") or {}),
+    }
+
+
+def _relationship_edge_result(
+    link: dict[str, Any],
+    *,
+    score: float,
+    source_row: dict[str, Any] | None,
+    target_row: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    if not source_row or not target_row:
+        return None
+    link_id = str(link["link_id"])
+    metadata = link.get("metadata") if isinstance(link.get("metadata"), dict) else {}
+    return {
+        "type": "relationship_edge",
+        "id": link_id,
+        "link_id": link_id,
+        "description": str(link.get("description") or ""),
+        "metadata": metadata,
+        "semantic_score": score,
+        "matched_via": "link",
+        "matched_via_link_id": link_id,
+        "is_self_loop": str(link["source_id"]) == str(link["target_id"]),
+        "parallel_key": link_id,
+        "source": _memory_endpoint_payload(source_row),
+        "target": _memory_endpoint_payload(target_row),
+    }
+
+
+def _self_loop_link_result(
+    link: dict[str, Any],
+    *,
+    score: float,
+    memory_row: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    if not memory_row:
+        return None
+    memory = _row_to_memory_dict(memory_row)
+    return {
+        "type": "memory_node",
+        "id": memory["id"],
+        "content": memory["content"],
+        "scope": memory.get("scope") or [],
+        "semantic_score": score,
+        "matched_via": "semantic_link",
+        "matched_via_link_id": str(link["link_id"]),
+        "matched_link_description": str(link.get("description") or ""),
+    }
+
+
+def _filter_links_by_endpoint_scope(
+    link_rows: list[dict[str, Any]],
+    scope_index: dict[str, list[str]],
+    scope: list[str],
+) -> list[dict[str, Any]]:
+    """MemBrain-style: both link endpoints must match every scope pattern."""
+    filtered: list[dict[str, Any]] = []
+    for row in link_rows:
+        source_scope = scope_index.get(str(row["source_id"]), [])
+        target_scope = scope_index.get(str(row["target_id"]), [])
+        if _scope_matches_filter(source_scope, scope) and _scope_matches_filter(
+            target_scope, scope
+        ):
+            filtered.append(row)
+    return filtered
+
+
+def search_memories(
+    engine: ArthaEngine,
+    query: str,
+    *,
+    k: int = 5,
+    scope: list[str] | None = None,
+    include_links: bool | None = None,
+) -> tuple[list[dict[str, Any]], list[str] | None]:
+    from memuron.application.config import settings
+    from memuron.search.hybrid import hybrid_memory_search, retrieve_pool_size
+
+    _require_memory_projections(engine)
+    if include_links is None:
+        include_links = settings.search_include_links
+
+    query_vector = _embed_query_vector(engine, query)
+    store = engine.store
+    memory_pool = retrieve_pool_size(k * 2 if include_links else k)
+    unified: list[tuple[str, dict[str, Any], float]] = []
+
+    if settings.search_hybrid:
+        for kind, payload, score in hybrid_memory_search(
+            engine,
+            query,
+            query_vector,
+            k=memory_pool,
+            scope=scope,
+        ):
+            unified.append((kind, payload, score))
+    elif pgvector_is_ready(store):
+        for row in pgvector_memory_search(
+            store,
+            query_vector,
+            top_k=memory_pool,
+            scope=scope,
+            include_content=True,
+        ):
+            scope_tokens = _parse_json_field(row.get("scope_json"), [])
+            unified.append(
+                (
+                    "memory_node",
+                    {
+                        "type": "memory_node",
+                        "id": row["artha_id"],
+                        "content": str(row.get("content") or ""),
+                        "scope": scope_tokens if isinstance(scope_tokens, list) else [],
+                        "source_metadata": source_identity_from_metadata(
+                            _parse_json_field(row.get("metadata_json"), {})
+                        ),
+                        "matched_via": "memory",
+                        "matched_via_link_id": None,
+                    },
+                    float(row["semantic_score"]),
+                )
+            )
+    else:
+        memory_hits = _memory_similarity_hits(
+            engine,
+            query_vector,
+            scope=scope,
+            top_k=memory_pool,
+        )
+        memory_details = _fetch_memory_rows_by_ids(
+            engine,
+            [memory_id for memory_id, _score in memory_hits],
+        )
+        for memory_id, score in memory_hits:
+            row = memory_details.get(memory_id)
+            if not row:
+                continue
+            memory = _row_to_memory_dict(row)
+            unified.append(
+                (
+                    "memory_node",
+                    {
+                        "type": "memory_node",
+                        "id": memory_id,
+                        "content": memory["content"],
+                        "scope": memory.get("scope") or [],
+                        "source_metadata": source_identity_from_metadata(
+                            memory.get("metadata") if isinstance(memory.get("metadata"), dict) else {}
+                        ),
+                        "matched_via": "memory",
+                        "matched_via_link_id": None,
+                    },
+                    score,
+                )
+            )
+
+    if include_links:
+        link_limit = k
+        self_loop_memory_ids: set[str] = set()
+        pending_link_hits: list[tuple[dict[str, Any], float]] = []
+        if pgvector_is_ready(store):
+            for row in pgvector_link_search(store, query_vector, top_k=link_limit, scope=scope):
+                link = {
+                    "link_id": row["link_id"],
+                    "source_id": row["source_id"],
+                    "target_id": row["target_id"],
+                    "description": row["description"],
+                    "metadata": _parse_json_field(row.get("metadata_json"), {}),
+                }
+                pending_link_hits.append((link, float(row["semantic_score"])))
+                if str(link["source_id"]) == str(link["target_id"]):
+                    self_loop_memory_ids.add(str(link["source_id"]))
+        else:
+            link_rows = _list_link_search_rows(engine)
+            if link_rows:
+                filtered_links = link_rows
+                if scope:
+                    memory_rows = _list_memory_search_rows(engine)
+                    scope_index = {
+                        str(row["artha_id"]): _parse_json_field(row.get("scope_json"), [])
+                        for row in memory_rows
+                    }
+                    filtered_links = _filter_links_by_endpoint_scope(
+                        link_rows, scope_index, scope
+                    )
+                link_hits = _cosine_similarity_hits(
+                    engine,
+                    query_vector,
+                    filtered_links,
+                    top_k=link_limit,
+                    id_key="link_id",
+                    scope_key=None,
+                )
+                link_meta = {str(row["link_id"]): _link_row_to_dict(row) for row in link_rows}
+                for link_id, score in link_hits:
+                    link = link_meta.get(link_id)
+                    if not link:
+                        continue
+                    pending_link_hits.append(
+                        (
+                            {
+                                "link_id": link["link_id"],
+                                "source_id": link["source_id"],
+                                "target_id": link["target_id"],
+                                "description": link["description"],
+                                "metadata": link.get("metadata") or {},
+                            },
+                            score,
+                        )
+                    )
+                    if str(link["source_id"]) == str(link["target_id"]):
+                        self_loop_memory_ids.add(str(link["source_id"]))
+        self_loop_rows = _fetch_memory_rows_by_ids(engine, list(self_loop_memory_ids))
+        for link, score in pending_link_hits:
+            if str(link["source_id"]) == str(link["target_id"]):
+                result = _self_loop_link_result(
+                    link,
+                    score=score,
+                    memory_row=self_loop_rows.get(str(link["source_id"])),
+                )
+                if result:
+                    unified.append(("memory_node", result, score))
+                continue
+            unified.append(("relationship_edge", link, score))
+
+    min_score = settings.search_min_semantic_score
+    if not settings.search_hybrid:
+        unified = [item for item in unified if item[2] >= min_score]
+    else:
+        unified = [
+            item
+            for item in unified
+            if item[0] != "relationship_edge" or item[2] >= min_score
+        ]
+
+    seen_content: dict[str, int] = {}
+    deduped: list[tuple[str, dict[str, Any], float]] = []
+    for kind, payload, score in sorted(unified, key=lambda item: item[2], reverse=True):
+        if kind != "memory_node":
+            deduped.append((kind, payload, score))
+            continue
+        content_key = str(payload.get("content") or "").strip().lower()[:500]
+        if content_key and content_key in seen_content:
+            existing_index = seen_content[content_key]
+            existing_kind, existing_payload, existing_score = deduped[existing_index]
+            incoming_match = payload.get("matched_via")
+            existing_match = existing_payload.get("matched_via")
+            if incoming_match and incoming_match != "memory" and existing_match == "memory":
+                deduped[existing_index] = (
+                    existing_kind,
+                    {
+                        **existing_payload,
+                        "matched_via": payload.get("matched_via"),
+                        "matched_via_link_id": payload.get("matched_via_link_id"),
+                        "matched_link_description": payload.get("matched_link_description"),
+                    },
+                    existing_score,
+                )
+            continue
+        if content_key:
+            seen_content[content_key] = len(deduped)
+        deduped.append((kind, payload, score))
+
+    top = deduped[:k]
+
+    endpoint_ids = {
+        str(item["source_id"])
+        for kind, item, _score in top
+        if kind == "relationship_edge"
+    } | {
+        str(item["target_id"])
+        for kind, item, _score in top
+        if kind == "relationship_edge"
+    }
+    endpoint_rows = _fetch_memory_rows_by_ids(engine, list(endpoint_ids))
+
+    results: list[dict[str, Any]] = []
+    for kind, payload, score in top:
+        if kind == "memory_node":
+            results.append({**payload, "semantic_score": payload.get("semantic_score", score)})
+            continue
+        edge = _relationship_edge_result(
+            payload,
+            score=score,
+            source_row=endpoint_rows.get(str(payload["source_id"])),
+            target_row=endpoint_rows.get(str(payload["target_id"])),
+        )
+        if edge:
+            results.append(edge)
+
+    return results, scope
+
+
+def unlink_memories(
+    engine: ArthaEngine,
+    memory_id_1: str,
+    memory_id_2: str,
+    *,
+    event_metadata: dict[str, object] | None = None,
+) -> int:
+    removed = 0
+    for link_id in _find_link_ids_between(engine, memory_id_1, memory_id_2):
+        _remove_link(engine, link_id, event_metadata=event_metadata)
+        removed += 1
+    if removed:
+        refresh_memory_projections(engine)
+    return removed