kontextual-engine/docs/memory-graph-runtime.md

Memory Graph Runtime

kontextual-engine owns the operational side of the Markitect memory graph contracts. The engine imports Markitect-compatible graph/profile envelopes, maps source contract ids to stable runtime ids, and stores graph nodes, edges, and append-only events for later governed retrieval and lifecycle operations.

This repository does not redefine the Markitect syntax vocabulary. The first runtime slice checks only schema compatibility, required ids, edge endpoint integrity, and append-only event identity. Node and edge kind validation remains with markitect-tool.

Implemented Slice

• MemoryGraphImportResult maps markitect.memory.graph.v1 contracts into runtime records.
• MemoryProfileRecord maps markitect.memory.profile.v1 profiles without enforcing runtime policy, latency, retention, or compaction declarations yet.
• MemoryGraphRepository defines the storage port for profile, node, edge, and event records.
• InMemoryMemoryGraphRepository provides deterministic local storage for tests and future service wiring.
• MemoryRuntimeService.import_markitect_graph() persists an imported graph and persists an audit event when an OperationContext is supplied.
• MemoryRuntimeService.query_memory() retrieves graph nodes through a scope policy check plus per-node policy checks, returns source-grounded context items, preserves safe denied diagnostics, and persists an audit event in the result envelope.
• MemoryRuntimeService.apply_retention() marks stale memories for review or transitions old memories to delete_requested without physical deletion.
• MemoryRuntimeService.refresh_memory() clears stale markers and records a refresh event.
• MemoryRuntimeService.compact_memory() creates a deterministic summary node, preserves source spans/provenance, optionally retires source nodes, and appends a compaction event.
• MemoryRuntimeService.plan_memory_update() creates dry-run update plans with source and policy explanations.
• MemoryRuntimeService.apply_memory_update() requires explicit approval for durable writes when a plan is review-gated.
• MemoryRuntimeService.export_context_package_inputs() emits Markitect-compatible context package input envelopes without invoking the Markitect compiler.
• MemoryGraphRepository persists memory audit events separately from Markitect memory events, allowing operations to be queried by graph, correlation id, and operation.
• MemoryRuntimeService.export_runtime_envelope() emits a portable runtime envelope containing graph nodes, edges, memory events, and audit traces with operation id, actor, policy decision, and filter metadata.
• MemoryRuntimeAdapterCapability, MemorySemanticIndex, MemoryAuditPublisher, and MemoryRuntimeRegistry define optional adapter boundaries for vector/semantic indexes, durable audit sinks, remote registries, and sibling memory runtimes.

Boundary

markitect-tool remains responsible for:

• profile and graph syntax validation
• graph selection compilation into context packages
• deterministic package summaries and source-span preservation

kontextual-engine is responsible for:

• runtime ids and persistence
• append-only event storage
• durable audit event storage
• permission-aware retrieval and context assembly
• retention, refresh, compaction, review gates, and audit behavior
• agent-safe update plans and Markitect-compatible export envelopes

External Adapter Boundaries

External graph databases should implement MemoryGraphRepository; they are storage adapters, not alternate memory domain models. Enterprise policy systems should implement PolicyGateway; policy decisions remain explicit inputs to runtime operations.

Optional advanced adapters use small dedicated ports:

• MemorySemanticIndex for vector or hybrid retrieval indexes.
• MemoryAuditPublisher for durable event sinks, webhooks, or SIEM pipelines.
• MemoryRuntimeRegistry for remote memory registries and sibling runtimes such as future phase-memory services.

Adapters advertise MemoryRuntimeAdapterCapability with adapter kind, supported operations, optional dependencies, and whether they are deterministic local adapters. Adapter payloads must be serializable dictionaries or core runtime records, so core tests can stay deterministic and dependency-free.

infospace-bench should consume these records and Markitect fixtures to measure retrieval quality, latency, budget pressure, and regression behavior.