markitect-tool/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md

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

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0016	workplan	Memory Graph Profile Contract And Context Package Compiler	markitect	done	markitect-tool	markitect	P2	140	MKTT-WP-0008 MKTT-WP-0007 MKTT-WP-0009 MKTT-WP-0013	MKTT-WP-0011 MKTT-WP-0014 KONT-WP-0017 IB-WP-0017	2026-05-04	2026-05-15	850cbc13-71cb-422c-86ec-1cc7679095cf

MKTT-WP-0016: Memory Graph Profile Contract And Context Package Compiler

Preamble: Repository Boundary

This workplan is the Markitect contract slice of the agentic memory direction. It deliberately stops at syntax-layer contracts, validation, fixtures, and deterministic compilation into existing ContextPackage activations.

The broader memory architecture is a system concern. Durable graph stores, event persistence, retention, compaction, policy enforcement, audit, runtime APIs, and service operation belong in kontextual-engine or a future sister project such as phased-memory.

markitect-tool should keep the smaller and more natural responsibility:

• define markdown-friendly memory graph/profile schemas
• validate and normalize memory blueprint files
• define adapter descriptor expectations for external memory runtimes
• preserve provenance, freshness, confidence, policy metadata, and source spans
• compile selected memory graph fixtures into ContextPackage objects
• expose local validation/planning CLI commands that do not launch services

The practical goal is separation of concerns. Markitect should be able to describe, validate, and consume memory system contracts. Runtime repositories should implement, persist, govern, and operate those systems.

Purpose

Extend Markitect's explicit context-package memory layer with a graph-aware, profile-driven contract for agentic systems.

The target model describes three memory views:

• reasoning memory based on decision graphs
• short-term memory based on conversational paths
• long-term memory based on knowledge graphs

The current MKTT-WP-0008 implementation remains the activation and package layer. This workplan adds the schema, validation, examples, adapter boundary, and graph-to-package compiler needed for other repos to build durable memory runtimes without forcing that runtime into markitect-tool.

Background

The assessment in docs/agentic-memory-graph-blueprint-assessment.md concludes that the current memory package framework is a natural activation substrate but not a full memory operating model.

Current strengths:

• source spans
• namespaces
• deterministic summaries
• activation/deactivation lifecycle
• local package registry
• retrieval recipes
• token budgets
• provenance and policy metadata

Missing syntax-layer contracts:

• decision graph schema
• conversational event/path schema
• knowledge graph schema
• memory service profile and blueprint format
• adapter descriptor boundaries for runtime stores
• graph-to-context-package compiler
• graph-aware validation and planning CLI

Decision

Implement this as an optional contract extension over the existing memory framework.

Do not make LLMs, embeddings, vector stores, remote graph databases, flex-auth, or external policy services required. The first version should be deterministic and local-first, with runtime responsibilities handed off to kontextual-engine or future memory-runtime packages.

Implementation Update - 2026-05-15

Initial implementation is available in src/markitect_tool/memory/graph.py. It adds deterministic memory profile, graph, event, and selection models; contract validation helpers; profile planning; and graph-selection compilation into existing ContextPackage objects.

The CLI surface from this workplan is implemented:

mkt memory blueprint validate <file>
mkt memory blueprint plan <file>
mkt memory graph validate <file>
mkt memory graph pack <selection-file>

Examples and documentation now live in docs/memory-graph-contract.md and examples/memory/. The fixture catalog now covers reasoning decision graphs, conversation paths, knowledge neighborhoods, mixed profiles, invalid graph and profile examples, and non-executing runtime adapter handoff descriptors.

Closure Update - 2026-05-15

This workplan is complete. The final pass added deterministic conversation and knowledge fixtures, invalid validation fixtures, a runtime adapter boundary catalog, extension descriptor coverage, and tests that compile the valid graph selections into ContextPackage objects.

Out Of Scope

• Durable graph/event persistence.
• A production memory service or runtime daemon.
• Retention, deletion, compaction, and freshness enforcement.
• Permission enforcement, audit logs, or signed policy decisions.
• External graph databases, vector stores, embedding providers, or live LLM extraction.
• Remote memory registries or enterprise deployment topology.
• Application-specific memory evaluations for concrete infospaces.

P16.1 - Define memory graph vocabulary

id: MKTT-WP-0016-T001
status: done
priority: high
state_hub_task_id: "e1523ffb-47e6-4017-88e5-907586297416"

Define common node and edge envelopes for:

• reasoning graph nodes: question, claim, assumption, evidence, decision, alternative, outcome, risk, follow-up
• conversational path nodes: turn, plan, tool call, observation, edit, validation, interruption, activation
• knowledge graph nodes: entity, artifact, concept, capability, contract, policy, preference, source fact
• edge types: supports, contradicts, depends_on, led_to, supersedes, derived_from, affects, mentions, activates, governs

Every node and edge should support provenance, freshness, confidence, policy metadata, namespace, and source spans.

Output: model docs, dataclasses or schema objects, serialization tests, and fixture examples. Runtime storage and graph query execution are out of scope.

P16.2 - Define memory event envelope standard

id: MKTT-WP-0016-T002
status: done
priority: high
state_hub_task_id: "a5b871ea-1f5b-4065-bae2-04765da3bc96"

Create an append-only event envelope specification for short-term conversational paths and graph updates.

Events should capture:

• event id and timestamp
• actor/agent/thread/task namespace
• event kind
• references to context packages and activations
• graph node/edge update payloads
• branch and merge metadata
• policy metadata

Output: event schema, validation helpers, examples, and compatibility notes for runtime event logs. Persisting event logs belongs outside markitect-tool.

P16.3 - Define memory blueprint/profile schema

id: MKTT-WP-0016-T003
status: done
priority: high
state_hub_task_id: "07c94925-c593-4acb-8f2b-b6c61744deff"

Define a YAML/JSON profile that can describe a memory deployment:

• enabled memory kinds
• store/adapter ids per kind
• node/edge/event/package limits
• target p50/p95 latency as declared intent
• retention and deletion rules as declared intent
• refresh triggers
• compaction strategy names
• activation token budgets
• policy reauthorization requirements
• observability event names
• failure and fallback behavior

Output: profile schema, validation, example profiles, and docs. The schema may describe operational parameters, but Markitect must not enforce runtime retention, compaction, latency, or policy decisions.

P16.4 - Add local graph/profile fixtures

id: MKTT-WP-0016-T004
status: done
priority: medium
state_hub_task_id: "afcd7ce9-e657-4779-b3b2-0ae3f8e2d66e"

Add small deterministic fixtures for:

• decision graph subgraphs
• conversation paths
• knowledge graph neighborhoods
• mixed memory profiles
• invalid graph/profile examples

These fixtures should be enough for tests, docs, and handoff to kontextual-engine, infospace-bench, and future memory runtimes.

Output: fixture catalog, validation tests, and example docs. Do not implement a SQLite graph store or runtime query service in this workplan.

P16.5 - Compile graph selections into context packages

id: MKTT-WP-0016-T005
status: done
priority: high
state_hub_task_id: "5dfbe77e-f926-4ce8-a8c3-3c10aec0f2f6"

Add deterministic compilers from graph/path selections into ContextPackage objects:

• decision path package
• conversation episode package
• knowledge neighborhood package
• mixed package with explicit budget and priority rules

The compiler should operate on in-memory validated graph fixtures or adapter results, not on a Markitect-owned runtime store.

Output: compiler API, provenance-preserving package output, and activation tests.

P16.6 - Add memory contract validation CLI

id: MKTT-WP-0016-T006
status: done
priority: medium
state_hub_task_id: "07fb3f0d-aaf7-4bc0-a7a3-0fd4983776bb"

Add CLI commands to validate and explain memory contracts:

mkt memory blueprint validate <file>
mkt memory blueprint plan <file>
mkt memory graph validate <file>
mkt memory graph pack <selection-file>

These commands should validate schemas, explain declared storage/latency/budget implications, and compile package fixtures. They should not launch live external services or manage durable memory state.

Output: CLI commands, docs, and tests.

P16.7 - Define runtime adapter handoff boundaries

id: MKTT-WP-0016-T007
status: done
priority: medium
state_hub_task_id: "ff78d449-0738-4f1b-a018-2efed3d8e878"

Define optional adapter boundaries for:

• kontextual-engine durable graph/event persistence
• future phased-memory memory runtimes
• external graph databases
• vector stores and embedding providers
• LLM-assisted graph extraction and summaries
• enterprise policy decision points
• remote memory registries
• durable audit/event sinks

These are descriptor and contract notes only. Core graph/profile validation and local package compilation must remain useful without them.

Output: adapter interface notes, extension descriptors, and cross-repo handoff guidance.

Exit Criteria

• Memory graph vocabulary is explicit and serialized cleanly.
• Reasoning, conversation, and knowledge memory can be represented separately.
• A memory blueprint/profile can express operational size, latency, retention, refresh, compaction, activation, and policy parameters as declared contracts.
• Deterministic fixtures can compile into context packages.
• CLI can validate and explain memory blueprints and graph fixtures.
• Runtime storage, retrieval, policy enforcement, audit, and application evaluation remain outside markitect-tool.