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 can attach 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 emits 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.

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
• permission-aware retrieval and context assembly
• retention, refresh, compaction, review gates, and audit behavior

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