ltcai 3.6.0 → 4.0.1

package/latticeai/services/agent_runtime.py

@@ -21,6 +21,7 @@ it, the frontend) now depends on this boundary instead of internal paths.
 
 from __future__ import annotations
 
+from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 from latticeai.core.multi_agent import (
@@ -41,8 +42,12 @@ ROLE_DESCRIPTIONS = {
 # Run statuses the orchestrator can emit that mean "still working". The default
 # orchestrator runs synchronously, so persisted runs are always terminal; this
 # set lets the runtime report live work if a future async runner lands.
-_ACTIVE_STATUSES = {"running", "in_progress", "queued", "retrying"}
-_TERMINAL_STATUSES = {"ok", "retried_ok", "failed", "rejected", "cancelled"}
+_ACTIVE_STATUSES = {"running", "in_progress", "queued", "retrying", "cancelling"}
+_TERMINAL_STATUSES = {"ok", "retried_ok", "failed", "rejected", "cancelled", "interrupted", "partial"}
+
+
+def _now() -> str:
+    return datetime.now().isoformat(timespec="seconds")
 
 
 class AgentRuntime:
@@ -64,6 +69,13 @@ class AgentRuntime:
         # Lifecycle hooks registry (optional). When present, ``start`` fires the
         # ``pre_run`` / ``post_run`` hooks; a blocking ``pre_run`` aborts the run.
         self._hooks = hooks
+        self._run_executor: Any = None
+
+    def attach_executor(self, executor: Any) -> None:
+        self._run_executor = executor
+
+    def _execution_mode(self) -> str:
+        return "async" if self._run_executor is not None else "synchronous"
 
     # ── configuration ─────────────────────────────────────────────────────
     def config(self) -> Dict[str, Any]:
@@ -72,7 +84,12 @@ class AgentRuntime:
             "roles": list(AGENT_ROLES),
             "default_pipeline": list(CORE_PIPELINE),
             "max_retries_cap": self._max_retries_cap,
-            "execution_mode": "synchronous",
+            "execution_mode": self._execution_mode(),
+            "cancellation": (
+                "cooperative; running synchronous model/tool calls finish their current step before a cancelled status is persisted"
+                if self._run_executor is not None else
+                "not supported for the synchronous runtime"
+            ),
         }
 
     def roles(self) -> List[Dict[str, Any]]:
@@ -150,7 +167,7 @@ class AgentRuntime:
             "runtime": {
                 "ready": True,
                 "version": MULTI_AGENT_VERSION,
-                "execution_mode": "synchronous",
+                "execution_mode": self._execution_mode(),
                 "default_pipeline": list(CORE_PIPELINE),
                 "total_runs": len(runs),
                 "active_runs": active,
@@ -184,6 +201,225 @@ class AgentRuntime:
         }
 
     # ── execution ─────────────────────────────────────────────────────────
+    def _fire_pre_run(
+        self,
+        *,
+        goal: str,
+        roles: Optional[List[str]],
+        max_retries: int,
+        user_email: Optional[str],
+        scope: Optional[str],
+    ) -> Optional[Dict[str, Any]]:
+        pre_dispatch: Optional[Dict[str, Any]] = None
+        if self._hooks is not None:
+            pre_dispatch = self._hooks.fire_hook(
+                "pre_run", "agent.run",
+                payload={"goal": goal, "roles": roles or None, "max_retries": max_retries},
+                user_email=user_email, workspace_id=scope,
+            )
+            if pre_dispatch.get("blocked"):
+                self._append_audit_event(
+                    "multi_agent_run_blocked",
+                    user_email=user_email,
+                    reason=pre_dispatch.get("block_reason"),
+                )
+                raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
+        return pre_dispatch
+
+    @staticmethod
+    def _result_patch(result: Any, goal: str) -> Dict[str, Any]:
+        return {
+            "agent_id": result.agent_id,
+            "status": result.status,
+            "input": goal,
+            "output_text": result.output,
+            "timeline": result.timeline,
+            "relationships": [ROLE_AGENT_IDS.get(r, f"agent:{r}") for r in result.roles_run],
+            "handoffs": result.handoffs,
+            "context_packets": result.context_packets,
+            "plan": result.plan,
+            "plan_review": result.plan_review,
+            "review_history": result.review_history,
+            "retry_history": result.retry_history,
+            "memory_snapshots": result.memory_snapshots,
+            "mode": getattr(result, "mode", "simulation"),
+            "current_role": None,
+        }
+
+    def _post_run_hooks(
+        self,
+        *,
+        run_id: Optional[str],
+        result: Any,
+        user_email: Optional[str],
+        scope: Optional[str],
+        status: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if self._hooks is None:
+            return None
+        return self._hooks.fire_hook(
+            "post_run", "agent.run",
+            payload={
+                "run_id": run_id,
+                "agent_id": result.agent_id,
+                "status": status or result.status,
+                "retries": result.retries,
+            },
+            user_email=user_email, workspace_id=scope,
+        )
+
+    def reserve_run(
+        self,
+        goal: str,
+        *,
+        user_email: Optional[str],
+        scope: Optional[str],
+        roles: Optional[List[str]] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        max_retries: int = 2,
+    ) -> Dict[str, Any]:
+        """Create the durable queued row used by the async executor."""
+        if not str(goal or "").strip():
+            raise ValueError("goal is required")
+        pre_dispatch = self._fire_pre_run(
+            goal=goal,
+            roles=roles,
+            max_retries=max_retries,
+            user_email=user_email,
+            scope=scope,
+        )
+        try:
+            orchestrator = self._orchestrator_factory(user_email or None, scope)
+            mode = getattr(orchestrator, "mode", "simulation")
+        except Exception:
+            mode = "simulation"
+        run = self._store.record_agent_run(
+            agent_id=ROLE_AGENT_IDS.get("executor", "agent:executor"),
+            status="queued",
+            input_text=goal,
+            output_text="",
+            timeline=[{"event": "agent_started", "status": "queued", "timestamp": _now()}],
+            relationships=[],
+            handoffs=[],
+            context_packets=[],
+            plan=[],
+            plan_review={},
+            review_history=[],
+            retry_history=[],
+            memory_snapshots=[],
+            user_email=user_email or None,
+            graph=None,
+            workspace_id=scope,
+            mode=mode,
+        )
+        run = self._store.update_agent_run(
+            run.get("id"),
+            workspace_id=scope,
+            execution_mode="async",
+            requested_roles=roles or None,
+            inputs=inputs or {},
+            max_retries=max_retries,
+        )
+        payload: Dict[str, Any] = {"run": run}
+        if pre_dispatch is not None:
+            payload["pre_run_hooks"] = pre_dispatch
+        return payload
+
+    def complete_reserved_run(
+        self,
+        run_id: str,
+        goal: str,
+        *,
+        user_email: Optional[str],
+        scope: Optional[str],
+        roles: Optional[List[str]] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        max_retries: int = 2,
+        pre_dispatch: Optional[Dict[str, Any]] = None,
+        cancel_requested: Optional[Callable[[], bool]] = None,
+    ) -> Dict[str, Any]:
+        """Execute orchestration and update an existing durable async row."""
+        run = self._store.get_agent_run(run_id, workspace_id=scope)
+        base_timeline = list(run.get("timeline") or [])
+        self._store.update_agent_run(
+            run_id,
+            workspace_id=scope,
+            status="running",
+            current_role=(roles or list(CORE_PIPELINE))[0] if (roles or CORE_PIPELINE) else None,
+            started_at=run.get("started_at") or _now(),
+        )
+        try:
+            orchestrator = self._orchestrator_factory(user_email or None, scope)
+            result = orchestrator.run(
+                goal,
+                user_email=user_email or None,
+                workspace_id=scope,
+                inputs=inputs or {},
+                roles=roles or None,
+                max_retries=max(0, min(int(max_retries or 0), self._max_retries_cap)),
+            )
+        except Exception as exc:
+            failed = self._store.update_agent_run(
+                run_id,
+                workspace_id=scope,
+                graph=self._workspace_graph(),
+                status="failed",
+                current_role=None,
+                error=str(exc),
+                output_text=str(exc),
+                timeline=base_timeline + [{
+                    "event": "execution_failed",
+                    "status": "failed",
+                    "detail": str(exc),
+                    "timestamp": _now(),
+                }],
+            )
+            self._append_audit_event("multi_agent_run", user_email=user_email, agent_id=failed.get("agent_id"), status="failed", retries=0)
+            return {"run": failed, "result": {"status": "failed", "error": str(exc)}}
+
+        patch = self._result_patch(result, goal)
+        patch["timeline"] = base_timeline + list(result.timeline or [])
+        if cancel_requested is not None and cancel_requested():
+            patch["status"] = "cancelled"
+            patch["current_role"] = None
+            patch["cancel_reason"] = "cancelled after the current synchronous step completed"
+            patch["cancelled_at"] = _now()
+            patch["timeline"] = patch["timeline"] + [{
+                "event": "execution_cancelled",
+                "status": "cancelled",
+                "reason": patch["cancel_reason"],
+                "timestamp": _now(),
+            }]
+        updated = self._store.update_agent_run(
+            run_id,
+            workspace_id=scope,
+            graph=self._workspace_graph(),
+            patch=patch,
+        )
+        self._append_audit_event(
+            "multi_agent_run",
+            user_email=user_email,
+            agent_id=result.agent_id,
+            status=updated.get("status") or result.status,
+            retries=result.retries,
+        )
+        post_dispatch = self._post_run_hooks(
+            run_id=run_id,
+            result=result,
+            user_email=user_email,
+            scope=scope,
+            status=updated.get("status") or result.status,
+        )
+        result_payload = result.as_dict()
+        if updated.get("status") == "cancelled":
+            result_payload = {"status": "cancelled", "reason": updated.get("cancel_reason"), "completed_result": result_payload}
+        payload = {"run": updated, "result": result_payload}
+        if pre_dispatch is not None:
+            payload["pre_run_hooks"] = pre_dispatch
+        if post_dispatch is not None:
+            payload["post_run_hooks"] = post_dispatch
+        return payload
+
     def start(
         self,
         goal: str,
@@ -242,6 +478,7 @@ class AgentRuntime:
             user_email=user_email or None,
             graph=self._workspace_graph(),
             workspace_id=scope,
+            mode=getattr(result, "mode", "simulation"),
         )
         self._append_audit_event(
             "multi_agent_run",
@@ -280,6 +517,8 @@ class AgentRuntime:
         exists the run has already completed. Report that honestly rather than
         pretending a cancellation occurred.
         """
+        if self._run_executor is not None:
+            return self._run_executor.cancel(run_id, kind="agent", scope=scope)
         try:
             run = self._store.get_agent_run(run_id, workspace_id=scope)
         except FileNotFoundError:

package/latticeai/services/app_context.py

@@ -1,27 +1,88 @@
 """Application dependency context for router assembly.
 
-The concrete FastAPI app is still assembled in ``server_app``. This dataclass
-documents the shared dependency boundary for routers and services so future
-extractions can receive a typed context instead of importing the app module.
+``latticeai.app_factory.create_app`` builds one ``AppContext`` per app and
+hands it to router factories, replacing the historical 25-30-kwarg closure
+wiring. Every field defaults to ``None``-ish so tests can construct a context
+carrying only the dependencies a router actually touches.
+
+Fields are grouped by the consumer that motivated them; routers must treat the
+context as read-only.
 """
 
 from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Optional
 
 
 @dataclass(frozen=True)
 class AppContext:
-    config: Any
-    data_dir: Path
-    static_dir: Path
-    model_router: Any
-    workspace_store: Any
-    workspace_service: Any
-    knowledge_graph: Any
-    local_kg_watcher: Any
-    require_user: Callable[..., str]
-    require_admin: Callable[..., tuple]
+    # ── core configuration / paths ────────────────────────────────────────
+    config: Any = None
+    data_dir: Optional[Path] = None
+    static_dir: Optional[Path] = None
+    base_dir: Optional[Path] = None
+    skills_dir: Optional[Path] = None
+
+    # ── singletons ────────────────────────────────────────────────────────
+    model_router: Any = None
+    workspace_store: Any = None
+    workspace_service: Any = None
+    knowledge_graph: Any = None
+    local_kg_watcher: Any = None
+    chat_service: Any = None
+    context_assembler: Any = None
+    brain_memory: Any = None
+    gardener: Any = None
+    hooks: Any = None
+    realtime_bus: Any = None
+    capability_registry: Any = None
+
+    # ── auth / session callables ──────────────────────────────────────────
+    require_user: Optional[Callable[..., str]] = None
+    require_admin: Optional[Callable[..., tuple]] = None
+    get_current_user: Optional[Callable[..., Optional[str]]] = None
+    load_users: Optional[Callable[[], dict]] = None
+    get_user_role: Optional[Callable[..., str]] = None
+    enforce_rate_limit: Optional[Callable[..., None]] = None
+
+    # ── audit / history callables ─────────────────────────────────────────
+    append_audit_event: Optional[Callable[..., None]] = None
+    get_audit_log: Optional[Callable[[], list]] = None
+    get_history: Optional[Callable[[], list]] = None
+    get_history_user: Optional[Callable[..., dict]] = None
+    save_to_history: Optional[Callable[..., None]] = None
+    clear_history: Optional[Callable[..., dict]] = None
+    clear_conversation: Optional[Callable[..., dict]] = None
+    group_history_conversations: Optional[Callable[..., list]] = None
+    get_conversation_messages: Optional[Callable[..., list]] = None
+    conversation_title: Optional[Callable[..., str]] = None
+
+    # ── knowledge graph access ────────────────────────────────────────────
+    enable_graph: bool = False
+    require_graph: Optional[Callable[[], None]] = None
+    workspace_graph: Optional[Callable[[], Any]] = None
+    graph_stats: Optional[Callable[[], dict]] = None
+
+    # ── workspace payload providers / skills ──────────────────────────────
+    workspace_models: Optional[Callable[[], dict]] = None
+    workspace_settings: Optional[Callable[[], dict]] = None
+    scan_environment: Optional[Callable[[], Any]] = None
+    local_sysinfo: Optional[Callable[..., Any]] = None
+    get_recommendations: Optional[Callable[..., Any]] = None
+    fetch_skills_marketplace: Optional[Callable[..., Any]] = None
+    install_skill: Optional[Callable[..., Any]] = None
+    remove_skill_directory: Optional[Callable[..., dict]] = None
+    redact_secret_text: Optional[Callable[[str], str]] = None
+    ui_file_response: Optional[Callable[..., Any]] = None
+
+    # ── models ────────────────────────────────────────────────────────────
+    public_model: str = ""
+    local_model: str = ""
 
+    # ── integrations ──────────────────────────────────────────────────────
+    # Fired as on_chat_message(role, text, source) after a chat exchange is
+    # persisted; ``None`` means no external chat mirror is registered. The
+    # telegram bridge subscribes here only when ENABLE_TELEGRAM is truthy.
+    on_chat_message: Optional[Callable[..., None]] = None

package/latticeai/services/ingestion.py

@@ -33,6 +33,15 @@ FILE_SOURCE_TYPES = frozenset({"file", "local_file", "upload", "pdf"})
 TEXT_SOURCE_TYPES = frozenset(
     {"web_url", "browser_tab", "text", "markdown", "note", "code", "clipboard"}
 )
+# Conversational exchanges (read via ingest_message — role/content semantics,
+# conversation chaining). v4: chat and MCP messages stop bypassing the
+# pipeline, so they carry provenance and fire the hook lifecycle like every
+# other source.
+CHAT_SOURCE_TYPES = frozenset({"chat_message", "mcp_message"})
+# Typed memory records (read via ingest_event → Decision/Experience/Event
+# nodes). The Memory System writes through the same door as everything else.
+MEMORY_SOURCE_TYPES = frozenset({"decision", "experience", "workspace_event"})
+_MEMORY_NODE_TYPES = {"decision": "Decision", "experience": "Experience", "workspace_event": "Event"}
 
 DEFAULT_MAX_TEXT_BYTES = 5 * 1024 * 1024  # 5 MB of extracted text per item
 
@@ -143,6 +152,10 @@ class IngestionPipeline:
         }
 
         def _run() -> Dict[str, Any]:
+            if source_type in CHAT_SOURCE_TYPES:
+                return self._ingest_chat(item, source_type=source_type, owner=owner)
+            if source_type in MEMORY_SOURCE_TYPES:
+                return self._ingest_memory_record(item, source_type=source_type, owner=owner)
             if source_type in FILE_SOURCE_TYPES or (item.path and not item.text):
                 return self._ingest_file(item, source_type=source_type, owner=owner, captured_at=captured_at)
             return self._ingest_text(item, source_type=source_type, owner=owner, captured_at=captured_at)
@@ -243,6 +256,40 @@ class IngestionPipeline:
             metadata={"mime_type": item.mime_type, **(item.metadata or {})},
         )
 
+    def _ingest_chat(self, item, *, source_type, owner) -> Dict[str, Any]:
+        text = item.text or ""
+        meta = item.metadata or {}
+        role = str(meta.get("role") or "user")
+        result = self._kg.ingest_message(
+            role,
+            text,
+            user_email=owner,
+            user_nickname=meta.get("user_nickname"),
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            raw=meta.get("raw"),
+        )
+        # ingest_message reports message/response node ids; normalize the keys
+        # the provenance step expects.
+        result.setdefault("node_id", result.get("node_id") or result.get("message_node_id") or result.get("id"))
+        result.setdefault("title", item.title or text[:80])
+        return result
+
+    def _ingest_memory_record(self, item, *, source_type, owner) -> Dict[str, Any]:
+        node_type = _MEMORY_NODE_TYPES[source_type]
+        meta = item.metadata or {}
+        result = self._kg.ingest_event(
+            node_type,
+            item.title or (item.text or node_type)[:120],
+            user_email=owner,
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            metadata={**meta, "detail": (item.text or "")[:2000]},
+        )
+        result.setdefault("node_id", result.get("node_id") or result.get("id"))
+        result.setdefault("title", item.title)
+        return result
+
     def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
         if not item.path:
             raise ValueError("File ingestion requires a path.")

package/latticeai/services/kg_portability.py

@@ -44,11 +44,16 @@ def _sha256_file(path: Path) -> str:
 
 
 class KGPortabilityService:
-    def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True) -> None:
+    def __init__(self, *, knowledge_graph: Any, data_dir, enable_graph: bool = True, device_identity: Any = None) -> None:
         self._kg = knowledge_graph
         self._data_dir = Path(data_dir)
         self._enable = bool(enable_graph)
         self._exports_dir = self._data_dir / "workspace_exports"
+        # v4 sovereignty: when a DeviceIdentity is wired, exports are signed
+        # and imports record origin provenance. Pre-v4 unsigned bundles stay
+        # importable locally (origin='unsigned-legacy') — signatures are
+        # mandatory only on the Brain Network peer path.
+        self._identity = device_identity
 
     def available(self) -> bool:
         return self._enable and self._kg is not None
@@ -60,7 +65,7 @@ class KGPortabilityService:
     # ── logical export / import ──────────────────────────────────────────────
     def export(self, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
         self._require()
-        data = self._kg.export_graph_data()
+        data = self._kg.export_graph_data(workspace_id=workspace_id)
         header = {
             "format": FORMAT,
             "format_version": FORMAT_VERSION,
@@ -69,7 +74,10 @@ class KGPortabilityService:
             "workspace_id": workspace_id,
             "counts": data.get("counts"),
         }
-        return {"header": header, **data}
+        artifact = {"header": header, **data}
+        if self._identity is not None:
+            artifact["signature"] = self._identity.sign_manifest(header)
+        return artifact
 
     def export_to_file(self, path=None, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
         artifact = self.export(workspace_id=workspace_id)
@@ -84,8 +92,30 @@ class KGPortabilityService:
             raise ValueError("Invalid Knowledge Graph export artifact.")
         if mode not in ("merge", "replace"):
             raise ValueError("mode must be 'merge' or 'replace'.")
+        origin = "unsigned-legacy"
+        signature = artifact.get("signature")
+        if signature:
+            from latticeai.brain.identity import verify_manifest
+
+            if not verify_manifest(artifact.get("header") or {}, signature):
+                raise ValueError("Bundle signature verification failed — refusing to import.")
+            origin = f"device:{signature.get('fingerprint') or 'unknown'}"
         result = self._kg.import_graph_data(artifact, mode=mode, dry_run=dry_run)
         result["header"] = artifact.get("header")
+        result["origin"] = origin
+        result["signed"] = bool(signature)
+        if not dry_run:
+            try:
+                self._kg.record_provenance(
+                    node_id="import:" + str((artifact.get("header") or {}).get("exported_at") or _now_iso()),
+                    source_type="bundle_import",
+                    pipeline="kg-portability",
+                    owner=None,
+                    metadata={"origin": origin, "mode": mode,
+                              "counts": (artifact.get("header") or {}).get("counts")},
+                )
+            except Exception:
+                pass
         return result
 
     def import_from_file(self, path, *, mode: str = "merge", dry_run: bool = False) -> Dict[str, Any]:

package/latticeai/services/memory_service.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 import json
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 # Personal workspace memory kinds (from WorkspaceOS.MEMORY_KINDS).
 WORKSPACE_KINDS = (
@@ -60,12 +60,16 @@ class MemoryService:
         knowledge_graph: Any = None,
         enable_graph: bool = True,
         history_file: Optional[Path] = None,
+        conversation_store: Any = None,
     ):
         self._store = store
         self._kg = knowledge_graph
         self._enable_graph = bool(enable_graph and knowledge_graph is not None)
         self._data_dir = Path(data_dir)
         self._history_file = Path(history_file) if history_file else (self._data_dir / "chat_history.json")
+        # v4: the durable SQLite conversation store supersedes the JSON file
+        # as the conversation tier's backing store when provided.
+        self._conversation_store = conversation_store
 
     # ── helpers over the underlying stores ────────────────────────────────
     def _workspace_memories(self, *, user_email: Optional[str], workspace_id: Optional[str]) -> List[Dict[str, Any]]:
@@ -87,6 +91,14 @@ class MemoryService:
             return []
 
     def _conversations(self) -> List[Dict[str, Any]]:
+        if self._conversation_store is not None:
+            try:
+                grouped: Dict[str, List[Dict[str, Any]]] = {}
+                for item in self._conversation_store.history():
+                    grouped.setdefault(item.get("conversation_id") or "legacy-previous-history", []).append(item)
+                return [{"id": conv_id, "messages": msgs} for conv_id, msgs in grouped.items()]
+            except Exception:
+                return []
         if not self._history_file.exists():
             return []
         try:
@@ -130,7 +142,10 @@ class MemoryService:
 
         ws_bytes = _file_size(self._data_dir / "workspace_os.json")
         kg_bytes = _file_size(self._data_dir / "knowledge_graph.sqlite")
-        conv_bytes = _file_size(self._history_file)
+        if self._conversation_store is not None:
+            conv_bytes = int(getattr(self._conversation_store, "size_bytes", lambda: 0)())
+        else:
+            conv_bytes = _file_size(self._history_file)
 
         node_total = sum((kg_stats or {}).get("nodes", {}).values()) if kg_stats else None
         edge_total = sum((kg_stats or {}).get("edges", {}).values()) if kg_stats else None
@@ -159,7 +174,7 @@ class MemoryService:
             {
                 "id": "conversation", "type": "conversation", "label": "Conversation Memory",
                 "count": len(convs), "size_bytes": conv_bytes,
-                "health": "ok" if self._history_file.exists() else "empty",
+                "health": "ok" if (self._conversation_store is not None or self._history_file.exists()) else "empty",
                 "detail": "Historical interaction memory from chat.",
             },
             {
@@ -202,6 +217,18 @@ class MemoryService:
         limit: int = 20,
     ) -> Dict[str, Any]:
         q = str(query or "").strip()
+        query_tokens = [tok for tok in q.lower().split() if tok]
+
+        def _lexical_score(*texts: Any) -> float:
+            # Honest, comparable relevance: fraction of query tokens present.
+            # Both tiers share this scorer so the cross-tier ranking is real,
+            # not an artifact of per-tier constants.
+            if not query_tokens:
+                return 0.0
+            haystack = " ".join(str(t or "") for t in texts).lower()
+            hits = sum(1 for tok in query_tokens if tok in haystack)
+            return round(hits / len(query_tokens), 4)
+
         results: List[Dict[str, Any]] = []
 
         try:
@@ -215,23 +242,24 @@ class MemoryService:
                 "title": (m.get("kind") or "memory"),
                 "snippet": str(m.get("content") or "")[:240],
                 "kind": m.get("kind"),
-                "score": 0.6,
+                "score": _lexical_score(m.get("content"), " ".join(m.get("tags") or []), m.get("kind")),
                 "tags": m.get("tags") or [],
             })
 
         if self._enable_graph and q:
             try:
-                hits = self._kg.search(q, limit).get("results", [])
+                # KnowledgeGraph.search returns {"query": ..., "matches": [...]}.
+                hits = self._kg.search(q, limit).get("matches", [])
             except Exception:
                 hits = []
-            for hsit in hits[:limit]:
+            for hit in hits[:limit]:
                 results.append({
                     "source": "graph",
-                    "id": hsit.get("id") or hsit.get("node_id"),
-                    "title": hsit.get("title") or hsit.get("name") or "node",
-                    "snippet": str(hsit.get("summary") or hsit.get("content") or "")[:240],
-                    "kind": hsit.get("type") or "node",
-                    "score": float(hsit.get("score") or 0.5),
+                    "id": hit.get("id") or hit.get("node_id"),
+                    "title": hit.get("title") or hit.get("name") or "node",
+                    "snippet": str(hit.get("summary") or hit.get("content") or "")[:240],
+                    "kind": hit.get("type") or "node",
+                    "score": _lexical_score(hit.get("title"), hit.get("name"), hit.get("summary"), hit.get("content")),
                 })
 
         results.sort(key=lambda r: r.get("score", 0), reverse=True)