generated from coulomb/repo-seed
docs(workplans): split memory architecture scope
This commit is contained in:
@@ -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`.
|
||||
|
||||
@@ -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 <file>
|
||||
mkt memory blueprint plan <file>
|
||||
mkt memory graph explain <graph-or-package-id>
|
||||
mkt memory graph pack <selection>
|
||||
mkt memory graph validate <file>
|
||||
mkt memory graph pack <selection-file>
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
Reference in New Issue
Block a user