generated from coulomb/repo-seed
92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# 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.
|