---
id: KONT-WP-0017
type: workplan
title: "Agentic Memory Graph Runtime And Operational State"
domain: markitect
repo: kontextual-engine
status: completed
owner: codex
topic_slug: markitect
planning_priority: medium
planning_order: 17
created: "2026-05-15"
updated: "2026-05-15"
depends_on_workplans:
  - KONT-WP-0007
  - KONT-WP-0008
  - KONT-WP-0009
  - KONT-WP-0010
related_workplans:
  - MKTT-WP-0016
  - IB-WP-0017
state_hub_workstream_id: "18b51fcd-6a32-49f7-8d02-549a2768d0eb"
---

# KONT-WP-0017: Agentic Memory Graph Runtime And Operational State

## Purpose

Implement the durable runtime side of the agentic memory architecture described
by the `markitect-tool` memory graph/profile contracts.

`markitect-tool` should define schemas, validation, fixtures, adapter
descriptors, and deterministic graph-to-context-package compilation.
`kontextual-engine` should own the durable operational layer: graph/event
persistence, permission-aware retrieval, lifecycle state, auditability,
retention, compaction, and agent-safe APIs.

## Architecture Boundary

This workplan belongs in `kontextual-engine` because it is about persistent,
governed, operational memory state.

Allowed responsibilities:

- Persist memory graph nodes, edges, events, packages, and activations.
- Attach stable asset identity, provenance, policy metadata, lifecycle state,
  and audit records.
- Execute retention, deletion, refresh, compaction, and reauthorization rules.
- Expose permission-aware retrieval and context assembly APIs.
- Import and validate `markitect-tool` memory profiles without redefining the
  syntax-layer contract.

Disallowed responsibilities:

- Do not redefine Markitect's graph/profile schema vocabulary.
- Do not implement a document syntax parser or context package compiler that
  competes with `markitect-tool`.
- Do not hard-code application-specific infospace evaluation logic.
- Do not require any one graph database, vector store, LLM provider, or
  enterprise policy system in the core implementation.

## Implementation Update - 2026-05-15

The first runtime-contract slice is implemented. `kontextual-engine` can now
map `markitect.memory.graph.v1` and `markitect.memory.profile.v1` envelopes
into stable runtime records, persist them through a `MemoryGraphRepository`
port, and use `InMemoryMemoryGraphRepository` as the deterministic local
implementation for tests.

The implementation deliberately does not validate Markitect's node/edge
vocabulary. It checks runtime compatibility concerns only: schema version,
required ids, edge endpoint integrity, stable runtime id mapping, source-span
preservation, and append-only event identity.

Primary files:

- `src/kontextual_engine/core/memory.py`
- `src/kontextual_engine/ports/memory.py`
- `src/kontextual_engine/adapters/memory/graph_store.py`
- `src/kontextual_engine/services/memory_service.py`
- `docs/memory-graph-runtime.md`

The permission-aware retrieval slice is also implemented in
`MemoryRuntimeService.query_memory()`. It performs a scope policy check,
per-node policy checks, returns source-grounded context items, preserves denied
diagnostics without leaking denied node text, and emits an audit event in the
result envelope.

The lifecycle slice is implemented with deterministic local operations:
`apply_retention()` marks stale memories for review or transitions old memories
to `delete_requested`; `refresh_memory()` clears stale markers; and
`compact_memory()` creates a provenance/source-span preserving summary node,
optionally retiring the source nodes. Each mutating operation appends a memory
event and returns audit metadata.

The agent-safe API slice is implemented with dry-run update plans, explicit
review gates for durable writes, source/policy explanations on planned node
updates, and Markitect-compatible context package input export. The export
method emits package inputs only; Markitect remains the package compiler.

The observability/export slice is implemented. Memory audit events are now
persisted through the memory graph repository, queryable by graph, correlation,
and operation. Runtime export envelopes include graph nodes, edges, memory
events, audit traces, operation id, actor metadata, policy decisions, and
filter metadata for portable inspection or handoff.

The external adapter boundary slice is implemented. Optional semantic indexes,
audit sinks, and runtime registries are defined as ports with capability
metadata, while graph databases continue to implement `MemoryGraphRepository`
and enterprise policy systems continue to implement `PolicyGateway`.

## P17.1 - Import and map Markitect memory contracts

```task
id: KONT-WP-0017-T001
status: done
priority: high
state_hub_task_id: "1b1f8904-3a3b-4d23-9d00-176633578801"
```

Define how `kontextual-engine` consumes memory graph/profile contracts from
`markitect-tool`.

The mapping should cover:

- graph node, edge, event, and profile schema versions
- stable runtime IDs versus source contract IDs
- provenance and source-span preservation
- policy metadata and reauthorization hints
- context package and activation references
- schema compatibility and migration strategy

Output: contract import design, mapping tests, and compatibility fixtures.

## P17.2 - Add durable graph and event storage

```task
id: KONT-WP-0017-T002
status: done
priority: high
state_hub_task_id: "dc3557e3-d425-46b0-8acc-9ac0230a385c"
```

Implement runtime persistence for memory graph and event records.

The first slice should support:

- nodes and edges with typed relationships
- append-only memory events
- branch and merge metadata
- source-grounded provenance
- lifecycle state and timestamps
- deterministic local test storage

Output: storage interfaces, local implementation or test double, and CRUD/query
tests.

## P17.3 - Implement permission-aware retrieval and context assembly

```task
id: KONT-WP-0017-T003
status: done
priority: high
state_hub_task_id: "711b945e-19e6-4548-8ddb-6c2c364148ca"
```

Expose retrieval operations that can select graph neighborhoods, decision
paths, conversation episodes, and knowledge neighborhoods while respecting
engine policy decisions.

The retrieval layer should:

- apply existing policy gateways and fail-closed behavior
- preserve denied-item explanations without leaking content
- produce source-grounded snippets or Markitect-compatible package inputs
- record retrieval provenance and actor context

Output: service/domain API, permission tests, and denied-access diagnostics.

## P17.4 - Add retention, refresh, and compaction operations

```task
id: KONT-WP-0017-T004
status: done
priority: high
state_hub_task_id: "853807fe-53ac-440e-823f-8d9b0b7ce4b7"
```

Implement operational memory lifecycle behavior from declared profiles.

The engine should support:

- retention windows
- deletion rules
- refresh triggers
- compaction runs
- stale assumption and freshness markers
- review-required transitions

Output: lifecycle operations, workflow/job integration points, audit events,
and tests.

## P17.5 - Add agent-safe memory APIs

```task
id: KONT-WP-0017-T005
status: done
priority: medium
state_hub_task_id: "9e2ad830-c9e6-47a2-8eca-ffe895781fdf"
```

Expose bounded APIs for agents to inspect, retrieve, update, and package memory
state.

The API should support:

- dry-run update plans
- review gates for durable writes
- source and policy explanations
- package export to `markitect-tool` context packages
- explicit actor, namespace, thread, and task coordinates

Output: API contracts, tests, and agent-safe operation notes.

## P17.6 - Add observability, audit, and export surface

```task
id: KONT-WP-0017-T006
status: done
priority: medium
state_hub_task_id: "54f51f87-6420-4170-913f-f6dae098fe71"
```

Record memory operations as auditable engine events.

The runtime should expose:

- operation ids
- actor and policy decision metadata
- affected graph nodes, edges, events, and packages
- compaction and retention traces
- export/import envelopes for portability

Output: audit model, observability events, export fixtures, and tests.

## P17.7 - Define external runtime adapter boundaries

```task
id: KONT-WP-0017-T007
status: done
priority: medium
state_hub_task_id: "c3cf79d8-389c-4583-a02d-303d0ce75cc1"
```

Define optional adapters for advanced memory runtimes without making them core
dependencies.

Candidate adapters:

- external graph databases
- vector stores and embedding providers
- future `phased-memory` services
- enterprise policy decision points
- durable event sinks
- remote memory registries

Output: adapter interfaces and extension notes that preserve local deterministic
engine behavior.

## Exit Criteria

- The engine can persist and retrieve memory graph/event state using
  Markitect-compatible contracts.
- Permission-aware retrieval and context assembly are source-grounded and
  auditable.
- Retention, refresh, compaction, and review gates are modeled as operational
  engine behavior.
- Agents have bounded APIs for memory operations.
- Markitect remains the contract/compiler layer; infospace-bench remains the
  applied evaluation layer.