coulomb/markitect-tool
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(workplans): split memory architecture scope

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-15 00:23:27 +02:00
parent a6cb213844
commit 8064466fc2
2 changed files with 116 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
workplans/MKTT-WP-0015-render-and-document-function-extensions.md
View File

@@ -17,6 +17,8 @@ related_workplans:
- MKTT-WP-0008 - MKTT-WP-0008
- MKTT-WP-0009 - MKTT-WP-0009
- MKTT-WP-0013 - MKTT-WP-0013
- KONT-WP-0017
- IB-WP-0017
created: "2026-05-04" created: "2026-05-04"
updated: "2026-05-04" updated: "2026-05-04"
state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681" 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 calls, filesystem writes, or external processes required for deterministic
Markitect parsing and function validation. 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 ## P15.1 - Typed document values and value mapping
```task ```task
@@ -139,17 +149,19 @@ priority: high
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904" 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 - emit Quarkdown source from Markitect references, processors, templates, and
function calls function calls
- support output profiles such as plain, docs, slides, paged, and static site - 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 - keep direct code reuse license-safe
- track source to rendered-artifact provenance - track source to rendered-artifact provenance
Output: adapter interface, Quarkdown export sketch, policy model, and tests Output: adapter interface, Quarkdown export sketch, local policy model, and
with deterministic fake renderers. 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 ## P15.5 - Render-aware references, numbering, and assets
@@ -194,6 +206,8 @@ required for deterministic function parsing, validation, and rendering of pure
functions. functions.
Output: permission vocabulary, denied-operation diagnostics, and policy tests. 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 ## Exit Criteria
@@ -204,3 +218,5 @@ Output: permission vocabulary, denied-operation diagnostics, and policy tests.
dependency. dependency.
- Typed values, render provenance, references, and assets have clear contracts. - Typed values, render provenance, references, and assets have clear contracts.
- The extension does not duplicate the dataflow workflow engine. - The extension does not duplicate the dataflow workflow engine.
- Durable render operations, publication lifecycle, and enterprise policy
enforcement remain outside `markitect-tool`.

163
workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md
View File

@@ -1,7 +1,7 @@
--- ---
id: MKTT-WP-0016 id: MKTT-WP-0016
type: workplan type: workplan
title: "Agentic Memory Graphs And Service Blueprints" title: "Memory Graph Profile Contract And Context Package Compiler"
domain: markitect domain: markitect
status: todo status: todo
owner: markitect-tool owner: markitect-tool
@@ -16,56 +16,60 @@ depends_on_workplans:
related_workplans: related_workplans:
- MKTT-WP-0011 - MKTT-WP-0011
- MKTT-WP-0014 - MKTT-WP-0014
- KONT-WP-0017
- IB-WP-0017
created: "2026-05-04" created: "2026-05-04"
updated: "2026-05-04" updated: "2026-05-15"
state_hub_workstream_id: "850cbc13-71cb-422c-86ec-1cc7679095cf" 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 ## Preamble: Repository Boundary
This workplan is intentionally scoped as a boundary-setting bridge between This workplan is the Markitect contract slice of the agentic memory direction.
`markitect-tool` and a future sister project named `phased-memory`. 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 The broader memory architecture is a system concern. Durable graph stores,
sophisticated form should live in `phased-memory`, a dedicated repo for memory event persistence, retention, compaction, policy enforcement, audit, runtime
concepts that range from ephemeral and fluid working context to durable, APIs, and service operation belong in `kontextual-engine` or a future sister
stabilized long-term memory. That repo can own memory service runtimes, project such as `phased-memory`.
specialized stores, compaction strategies, graph evolution, profile
instantiation, retention mechanics, and operational deployment concerns.
`markitect-tool` should keep the smaller and more natural responsibility: `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 - define markdown-friendly memory graph/profile schemas
memory selections into `ContextPackage` activations. Markitect may provide local - validate and normalize memory blueprint files
fixtures and validation tools, but should avoid becoming the full memory - define adapter descriptor expectations for external memory runtimes
runtime. - 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 The practical goal is separation of concerns. Markitect should be able to
describe, validate, and consume memory systems. `phased-memory` should be able describe, validate, and consume memory system contracts. Runtime repositories
to implement and operate them. should implement, persist, govern, and operate those systems.
## Purpose ## Purpose
Extend Markitect's explicit context-package memory layer into a graph-aware, Extend Markitect's explicit context-package memory layer with a graph-aware,
profile-driven memory architecture for agentic systems. profile-driven contract for agentic systems.
The target model separates: The target model describes three memory views:
- reasoning memory based on decision graphs - reasoning memory based on decision graphs
- short-term memory based on conversational paths - short-term memory based on conversational paths
- long-term memory based on knowledge graphs - long-term memory based on knowledge graphs
The current `MKTT-WP-0008` implementation remains the activation and package The current `MKTT-WP-0008` implementation remains the activation and package
layer. This workplan adds the graph, event, and service-blueprint layers needed layer. This workplan adds the schema, validation, examples, adapter boundary,
to instantiate memory systems with explicit operational parameters. and graph-to-package compiler needed for other repos to build durable memory
runtimes without forcing that runtime into `markitect-tool`.
## Background ## Background
The assessment in `docs/agentic-memory-graph-blueprint-assessment.md` concludes 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 that the current memory package framework is a natural activation substrate but
complete graph memory system. not a full memory operating model.
Current strengths: Current strengths:
@@ -78,26 +82,38 @@ Current strengths:
- token budgets - token budgets
- provenance and policy metadata - provenance and policy metadata
Missing layers: Missing syntax-layer contracts:
- decision graph schema - decision graph schema
- conversational event/path schema - conversational event/path schema
- knowledge graph schema - knowledge graph schema
- memory service profile and blueprint format - memory service profile and blueprint format
- operational parameters such as size, latency, retention, freshness, and - adapter descriptor boundaries for runtime stores
compaction
- graph-to-context-package compiler - graph-to-context-package compiler
- graph-aware CLI inspection/planning - graph-aware validation and planning CLI
## Decision ## 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, Do not make LLMs, embeddings, vector stores, remote graph databases, flex-auth,
or external policy services required. The first version should be deterministic 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 ```task
id: MKTT-WP-0016-T001 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 Every node and edge should support provenance, freshness, confidence, policy
metadata, namespace, and source spans. 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 ```task
id: MKTT-WP-0016-T002 id: MKTT-WP-0016-T002
@@ -131,8 +148,8 @@ priority: high
state_hub_task_id: "a5b871ea-1f5b-4065-bae2-04765da3bc96" state_hub_task_id: "a5b871ea-1f5b-4065-bae2-04765da3bc96"
``` ```
Create an append-only event envelope for short-term conversational paths and Create an append-only event envelope specification for short-term
graph updates. conversational paths and graph updates.
Events should capture: Events should capture:
@@ -140,13 +157,14 @@ Events should capture:
- actor/agent/thread/task namespace - actor/agent/thread/task namespace
- event kind - event kind
- references to context packages and activations - references to context packages and activations
- graph node/edge updates - graph node/edge update payloads
- branch and merge metadata - branch and merge metadata
- policy 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 ```task
id: MKTT-WP-0016-T003 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: Define a YAML/JSON profile that can describe a memory deployment:
- enabled memory kinds - enabled memory kinds
- stores/adapters per kind - store/adapter ids per kind
- node/edge/event/package limits - node/edge/event/package limits
- target p50/p95 latency - target p50/p95 latency as declared intent
- retention and deletion rules - retention and deletion rules as declared intent
- refresh triggers - refresh triggers
- compaction strategy - compaction strategy names
- activation token budgets - activation token budgets
- policy reauthorization requirements - policy reauthorization requirements
- observability events - observability event names
- failure and fallback behavior - 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 ```task
id: MKTT-WP-0016-T004 id: MKTT-WP-0016-T004
@@ -180,18 +200,21 @@ priority: medium
state_hub_task_id: "afcd7ce9-e657-4779-b3b2-0ae3f8e2d66e" state_hub_task_id: "afcd7ce9-e657-4779-b3b2-0ae3f8e2d66e"
``` ```
Implement a small local prototype, likely SQLite-backed or interface-first with Add small deterministic fixtures for:
durable YAML fixtures, that can store and query:
- decision graph subgraphs - decision graph subgraphs
- conversation paths - conversation paths
- knowledge graph neighborhoods - 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 ```task
id: MKTT-WP-0016-T005 id: MKTT-WP-0016-T005
@@ -208,10 +231,13 @@ Add deterministic compilers from graph/path selections into
- knowledge neighborhood package - knowledge neighborhood package
- mixed package with explicit budget and priority rules - 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 Output: compiler API, provenance-preserving package output, and activation
tests. tests.
## P16.6 - Add blueprint planning CLI ## P16.6 - Add memory contract validation CLI
```task ```task
id: MKTT-WP-0016-T006 id: MKTT-WP-0016-T006
@@ -220,22 +246,22 @@ priority: medium
state_hub_task_id: "07fb3f0d-aaf7-4bc0-a7a3-0fd4983776bb" 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 ```text
mkt memory blueprint validate <file> mkt memory blueprint validate <file>
mkt memory blueprint plan <file> mkt memory blueprint plan <file>
mkt memory graph explain <graph-or-package-id> mkt memory graph validate <file>
mkt memory graph pack <selection> mkt memory graph pack <selection-file>
``` ```
These commands should validate profiles and produce implementation plans with These commands should validate schemas, explain declared storage/latency/budget
storage, latency, budget, and policy implications. They should not launch live implications, and compile package fixtures. They should not launch live
external services in the first version. external services or manage durable memory state.
Output: CLI commands, docs, and tests. Output: CLI commands, docs, and tests.
## P16.7 - Define adapter boundaries for advanced services ## P16.7 - Define runtime adapter handoff boundaries
```task ```task
id: MKTT-WP-0016-T007 id: MKTT-WP-0016-T007
@@ -246,6 +272,8 @@ state_hub_task_id: "ff78d449-0738-4f1b-a018-2efed3d8e878"
Define optional adapter boundaries for: Define optional adapter boundaries for:
- `kontextual-engine` durable graph/event persistence
- future `phased-memory` memory runtimes
- external graph databases - external graph databases
- vector stores and embedding providers - vector stores and embedding providers
- LLM-assisted graph extraction and summaries - LLM-assisted graph extraction and summaries
@@ -253,18 +281,19 @@ Define optional adapter boundaries for:
- remote memory registries - remote memory registries
- durable audit/event sinks - durable audit/event sinks
These are adapter protocols only. Core graph/profile validation and local These are descriptor and contract notes only. Core graph/profile validation
package compilation must remain useful without them. 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 ## Exit Criteria
- Memory graph vocabulary is explicit and serialized cleanly. - Memory graph vocabulary is explicit and serialized cleanly.
- Reasoning, conversation, and knowledge memory can be represented separately. - Reasoning, conversation, and knowledge memory can be represented separately.
- A memory blueprint/profile can express operational size, latency, retention, - A memory blueprint/profile can express operational size, latency, retention,
refresh, compaction, activation, and policy parameters. refresh, compaction, activation, and policy parameters as declared contracts.
- Local deterministic graph/event examples can compile into context packages. - Deterministic fixtures can compile into context packages.
- CLI can validate and explain memory blueprints. - CLI can validate and explain memory blueprints and graph fixtures.
- External LLM, embedding, vector, graph, policy, and registry services remain - Runtime storage, retrieval, policy enforcement, audit, and application
optional. evaluation remain outside `markitect-tool`.