generated from coulomb/repo-seed
328 lines
10 KiB
Markdown
328 lines
10 KiB
Markdown
---
|
|
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 <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
|
|
|
|
```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 <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
|
|
|
|
```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`.
|