diff --git a/workplans/MKTT-WP-0015-render-and-document-function-extensions.md b/workplans/MKTT-WP-0015-render-and-document-function-extensions.md index 5686bc0..7200e7f 100644 --- a/workplans/MKTT-WP-0015-render-and-document-function-extensions.md +++ b/workplans/MKTT-WP-0015-render-and-document-function-extensions.md @@ -17,6 +17,8 @@ related_workplans: - MKTT-WP-0008 - MKTT-WP-0009 - MKTT-WP-0013 + - KONT-WP-0017 + - IB-WP-0017 created: "2026-05-04" updated: "2026-05-04" state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681" @@ -62,6 +64,14 @@ interfaces, but should not make Quarkdown, flex-auth, network access, live LLM calls, filesystem writes, or external processes required for deterministic Markitect parsing and function validation. +Boundary clarification: `markitect-tool` owns typed value contracts, +Markdown-compatible function syntax, render/export adapter interfaces, +provenance envelopes, diagnostics, and deterministic fake renderers. It does +not own durable rendered artifact storage, publication workflows, enterprise +authorization, real renderer operations, or concrete application reports. Those +belong in `kontextual-engine`, optional renderer packages, or +`infospace-bench` application workflows. + ## P15.1 - Typed document values and value mapping ```task @@ -139,17 +149,19 @@ priority: high state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904" ``` -Design optional render/export adapters: +Design optional render/export adapter contracts: - emit Quarkdown source from Markitect references, processors, templates, and function calls - support output profiles such as plain, docs, slides, paged, and static site -- invoke external renderers only through declared capabilities +- invoke external renderers only through declared capabilities and fake + deterministic test adapters in this repo - keep direct code reuse license-safe - track source to rendered-artifact provenance -Output: adapter interface, Quarkdown export sketch, policy model, and tests -with deterministic fake renderers. +Output: adapter interface, Quarkdown export sketch, local policy model, and +tests with deterministic fake renderers. Durable render jobs, stored artifacts, +publication state, and application-specific reports are out of scope here. ## P15.5 - Render-aware references, numbering, and assets @@ -194,6 +206,8 @@ required for deterministic function parsing, validation, and rendering of pure functions. Output: permission vocabulary, denied-operation diagnostics, and policy tests. +This is a syntax-layer capability contract, not a durable authorization service +or audit system. ## Exit Criteria @@ -204,3 +218,5 @@ Output: permission vocabulary, denied-operation diagnostics, and policy tests. dependency. - Typed values, render provenance, references, and assets have clear contracts. - The extension does not duplicate the dataflow workflow engine. +- Durable render operations, publication lifecycle, and enterprise policy + enforcement remain outside `markitect-tool`. diff --git a/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md b/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md index 11065b2..6b5693f 100644 --- a/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md +++ b/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md @@ -1,7 +1,7 @@ --- id: MKTT-WP-0016 type: workplan -title: "Agentic Memory Graphs And Service Blueprints" +title: "Memory Graph Profile Contract And Context Package Compiler" domain: markitect status: todo owner: markitect-tool @@ -16,56 +16,60 @@ depends_on_workplans: related_workplans: - MKTT-WP-0011 - MKTT-WP-0014 + - KONT-WP-0017 + - IB-WP-0017 created: "2026-05-04" -updated: "2026-05-04" +updated: "2026-05-15" state_hub_workstream_id: "850cbc13-71cb-422c-86ec-1cc7679095cf" --- -# MKTT-WP-0016: Agentic Memory Graphs And Service Blueprints +# MKTT-WP-0016: Memory Graph Profile Contract And Context Package Compiler ## Preamble: Repository Boundary -This workplan is intentionally scoped as a boundary-setting bridge between -`markitect-tool` and a future sister project named `phased-memory`. +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 emerging memory architecture is bigger than Markitect itself. Its -sophisticated form should live in `phased-memory`, a dedicated repo for memory -concepts that range from ephemeral and fluid working context to durable, -stabilized long-term memory. That repo can own memory service runtimes, -specialized stores, compaction strategies, graph evolution, profile -instantiation, retention mechanics, and operational deployment concerns. +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 interface contracts, memory blueprint/profile shapes, -adapter descriptors, provenance expectations, and deterministic compilers from -memory selections into `ContextPackage` activations. Markitect may provide local -fixtures and validation tools, but should avoid becoming the full memory -runtime. + +- 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 systems. `phased-memory` should be able -to implement and operate them. +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 into a graph-aware, -profile-driven memory architecture for agentic systems. +Extend Markitect's explicit context-package memory layer with a graph-aware, +profile-driven contract for agentic systems. -The target model separates: +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 graph, event, and service-blueprint layers needed -to instantiate memory systems with explicit operational parameters. +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 substrate but not yet a -complete graph memory system. +that the current memory package framework is a natural activation substrate but +not a full memory operating model. Current strengths: @@ -78,26 +82,38 @@ Current strengths: - token budgets - provenance and policy metadata -Missing layers: +Missing syntax-layer contracts: - decision graph schema - conversational event/path schema - knowledge graph schema - memory service profile and blueprint format -- operational parameters such as size, latency, retention, freshness, and - compaction +- adapter descriptor boundaries for runtime stores - graph-to-context-package compiler -- graph-aware CLI inspection/planning +- graph-aware validation and planning CLI ## Decision -Implement this as an optional extension over the existing memory framework. +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 adapter boundaries for more sophisticated deployments. +and local-first, with runtime responsibilities handed off to +`kontextual-engine` or future memory-runtime packages. -## P16.1 - Define graph memory vocabulary +## 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 @@ -120,9 +136,10 @@ Define common node and edge envelopes for: Every node and edge should support provenance, freshness, confidence, policy metadata, namespace, and source spans. -Output: model docs, dataclasses or schema objects, and serialization tests. +Output: model docs, dataclasses or schema objects, serialization tests, and +fixture examples. Runtime storage and graph query execution are out of scope. -## P16.2 - Add memory event log +## P16.2 - Define memory event envelope standard ```task id: MKTT-WP-0016-T002 @@ -131,8 +148,8 @@ priority: high state_hub_task_id: "a5b871ea-1f5b-4065-bae2-04765da3bc96" ``` -Create an append-only event envelope for short-term conversational paths and -graph updates. +Create an append-only event envelope specification for short-term +conversational paths and graph updates. Events should capture: @@ -140,13 +157,14 @@ Events should capture: - actor/agent/thread/task namespace - event kind - references to context packages and activations -- graph node/edge updates +- graph node/edge update payloads - branch and merge metadata - policy metadata -Output: local event log interface, deterministic tests, and examples. +Output: event schema, validation helpers, examples, and compatibility notes for +runtime event logs. Persisting event logs belongs outside `markitect-tool`. -## P16.3 - Define memory service blueprint/profile standard +## P16.3 - Define memory blueprint/profile schema ```task id: MKTT-WP-0016-T003 @@ -158,20 +176,22 @@ state_hub_task_id: "07c94925-c593-4acb-8f2b-b6c61744deff" Define a YAML/JSON profile that can describe a memory deployment: - enabled memory kinds -- stores/adapters per kind +- store/adapter ids per kind - node/edge/event/package limits -- target p50/p95 latency -- retention and deletion rules +- target p50/p95 latency as declared intent +- retention and deletion rules as declared intent - refresh triggers -- compaction strategy +- compaction strategy names - activation token budgets - policy reauthorization requirements -- observability events +- observability event names - failure and fallback behavior -Output: profile schema, validation, example profiles, and docs. +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 - Implement local graph/event prototype +## P16.4 - Add local graph/profile fixtures ```task id: MKTT-WP-0016-T004 @@ -180,18 +200,21 @@ priority: medium state_hub_task_id: "afcd7ce9-e657-4779-b3b2-0ae3f8e2d66e" ``` -Implement a small local prototype, likely SQLite-backed or interface-first with -durable YAML fixtures, that can store and query: +Add small deterministic fixtures for: - decision graph subgraphs - conversation paths - knowledge graph neighborhoods +- mixed memory profiles +- invalid graph/profile examples -This should be adequate for tests and local use, not a full graph database. +These fixtures should be enough for tests, docs, and handoff to +`kontextual-engine`, `infospace-bench`, and future memory runtimes. -Output: local store or adapter interface, graph query helpers, and tests. +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 neighborhoods into context packages +## P16.5 - Compile graph selections into context packages ```task id: MKTT-WP-0016-T005 @@ -208,10 +231,13 @@ Add deterministic compilers from graph/path selections into - 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 blueprint planning CLI +## P16.6 - Add memory contract validation CLI ```task id: MKTT-WP-0016-T006 @@ -220,22 +246,22 @@ priority: medium state_hub_task_id: "07fb3f0d-aaf7-4bc0-a7a3-0fd4983776bb" ``` -Add CLI commands to inspect and plan memory systems: +Add CLI commands to validate and explain memory contracts: ```text mkt memory blueprint validate mkt memory blueprint plan -mkt memory graph explain -mkt memory graph pack +mkt memory graph validate +mkt memory graph pack ``` -These commands should validate profiles and produce implementation plans with -storage, latency, budget, and policy implications. They should not launch live -external services in the first version. +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 adapter boundaries for advanced services +## P16.7 - Define runtime adapter handoff boundaries ```task id: MKTT-WP-0016-T007 @@ -246,6 +272,8 @@ 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 @@ -253,18 +281,19 @@ Define optional adapter boundaries for: - remote memory registries - durable audit/event sinks -These are adapter protocols only. Core graph/profile validation and local -package compilation must remain useful without them. +These are descriptor and contract notes only. Core graph/profile validation +and local package compilation must remain useful without them. -Output: adapter interface notes and extension descriptors. +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. -- Local deterministic graph/event examples can compile into context packages. -- CLI can validate and explain memory blueprints. -- External LLM, embedding, vector, graph, policy, and registry services remain - optional. + 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`.