--- id: MKTT-WP-0016 type: workplan title: "Memory Graph Profile Contract And Context Package Compiler" domain: markitect status: done owner: markitect-tool topic_slug: markitect planning_priority: P2 planning_order: 140 depends_on_workplans: - MKTT-WP-0008 - MKTT-WP-0007 - MKTT-WP-0009 - MKTT-WP-0013 related_workplans: - MKTT-WP-0011 - MKTT-WP-0014 - KONT-WP-0017 - IB-WP-0017 created: "2026-05-04" updated: "2026-05-15" state_hub_workstream_id: "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: ```text mkt memory blueprint validate mkt memory blueprint plan mkt memory graph validate mkt memory graph pack ``` 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 ```task 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 ```task 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 ```task 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 ```task 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 ```task 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 ```task 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: ```text mkt memory blueprint validate mkt memory blueprint plan mkt memory graph validate mkt memory graph pack ``` 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 ```task 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`.