feat(memory): define external adapter boundaries

src/kontextual_engine/__init__.py

@@ -116,7 +116,11 @@ from .ports import (
     BlobWriteResult,
     DirectorySourceConnector,
     FormatExtractor,
+    MemoryAuditPublisher,
     MemoryGraphRepository,
+    MemoryRuntimeAdapterCapability,
+    MemoryRuntimeRegistry,
+    MemorySemanticIndex,
     PolicyGateway,
     SourceConnector,
 )
@@ -271,6 +275,7 @@ __all__ = [
     "MetadataSchemaAssignment",
     "MetadataValidationIssue",
     "MetadataValueType",
+    "MemoryAuditPublisher",
     "MemoryCompactionRequest",
     "MemoryEdgeRecord",
     "MemoryEventRecord",
@@ -292,7 +297,10 @@ __all__ = [
     "MemoryRetentionRequest",
     "MemoryRuntimeExportRequest",
     "MemoryRuntimeExportResult",
+    "MemoryRuntimeAdapterCapability",
+    "MemoryRuntimeRegistry",
     "MemoryRuntimeService",
+    "MemorySemanticIndex",
     "MemorySourceSpan",
     "MemoryUpdatePlan",
     "MemoryUpdateRequest",

src/kontextual_engine/ports/__init__.py

@@ -9,7 +9,13 @@ from .blob_storage import (
     digest_storage_key,
 )
 from .ingestion import DirectorySourceConnector, FormatExtractor, SourceConnector
-from .memory import MemoryGraphRepository
+from .memory import (
+    MemoryAuditPublisher,
+    MemoryGraphRepository,
+    MemoryRuntimeAdapterCapability,
+    MemoryRuntimeRegistry,
+    MemorySemanticIndex,
+)
 from .policy import AllowAllPolicyGateway, PolicyGateway
 from .repositories import AssetRegistryRepository
 
@@ -24,7 +30,11 @@ __all__ = [
     "digest_storage_key",
     "DirectorySourceConnector",
     "FormatExtractor",
+    "MemoryAuditPublisher",
     "MemoryGraphRepository",
+    "MemoryRuntimeAdapterCapability",
+    "MemoryRuntimeRegistry",
+    "MemorySemanticIndex",
     "PolicyGateway",
     "SourceConnector",
 ]

src/kontextual_engine/ports/memory.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Protocol
+from dataclasses import dataclass, field
+from typing import Any, Protocol
 
 from kontextual_engine.core import (
     AuditEvent,
@@ -14,6 +15,30 @@ from kontextual_engine.core import (
 )
 
 
+@dataclass(frozen=True)
+class MemoryRuntimeAdapterCapability:
+    adapter_name: str
+    adapter_kind: str
+    supported_operations: tuple[str, ...] = ()
+    required_dependencies: tuple[str, ...] = ()
+    deterministic_local: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "supported_operations", tuple(self.supported_operations))
+        object.__setattr__(self, "required_dependencies", tuple(self.required_dependencies))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "adapter_name": self.adapter_name,
+            "adapter_kind": self.adapter_kind,
+            "supported_operations": list(self.supported_operations),
+            "required_dependencies": list(self.required_dependencies),
+            "deterministic_local": self.deterministic_local,
+            "metadata": dict(self.metadata),
+        }
+
+
 class MemoryGraphRepository(Protocol):
     def save_memory_profile(self, profile: MemoryProfileRecord) -> MemoryProfileRecord: ...
     def get_memory_profile(self, profile_id: str) -> MemoryProfileRecord: ...
@@ -56,3 +81,38 @@ class MemoryGraphRepository(Protocol):
         correlation_id: str | None = None,
         operation: str | None = None,
     ) -> list[AuditEvent]: ...
+
+
+class MemorySemanticIndex(Protocol):
+    name: str
+
+    def capabilities(self) -> MemoryRuntimeAdapterCapability: ...
+
+    def upsert_memory_nodes(self, nodes: list[MemoryNodeRecord]) -> dict[str, Any]: ...
+
+    def query_memory_nodes(
+        self,
+        *,
+        graph_id: str,
+        query: str,
+        limit: int = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]: ...
+
+
+class MemoryAuditPublisher(Protocol):
+    name: str
+
+    def capabilities(self) -> MemoryRuntimeAdapterCapability: ...
+
+    def publish_memory_audit_event(self, event: AuditEvent) -> dict[str, Any]: ...
+
+
+class MemoryRuntimeRegistry(Protocol):
+    name: str
+
+    def capabilities(self) -> MemoryRuntimeAdapterCapability: ...
+
+    def publish_runtime_envelope(self, envelope: dict[str, Any]) -> dict[str, Any]: ...
+
+    def fetch_runtime_envelope(self, reference: str) -> dict[str, Any]: ...