kontextual-engine/workplans/KONT-WP-0017-agentic-memory-graph-runtime.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on_workplans, related_workplans, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on_workplans	related_workplans	state_hub_workstream_id
KONT-WP-0017	workplan	Agentic Memory Graph Runtime And Operational State	markitect	kontextual-engine	completed	codex	markitect	medium	17	2026-05-15	2026-05-15	KONT-WP-0007 KONT-WP-0008 KONT-WP-0009 KONT-WP-0010	MKTT-WP-0016 IB-WP-0017	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

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

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

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

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

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

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

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.