# 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.