markitect-tool/workplans/MKTT-WP-0016-agentic-memory-graphs-and-service-blueprints.md

---
id: MKTT-WP-0016
type: workplan
title: "Agentic Memory Graphs And Service Blueprints"
domain: markitect
status: todo
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
created: "2026-05-04"
updated: "2026-05-04"
state_hub_workstream_id: "850cbc13-71cb-422c-86ec-1cc7679095cf"
---

# MKTT-WP-0016: Agentic Memory Graphs And Service Blueprints

## Preamble: Repository Boundary

This workplan is intentionally scoped as a boundary-setting bridge between
`markitect-tool` and a future sister project named `phased-memory`.

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.

`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.

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.

## Purpose

Extend Markitect's explicit context-package memory layer into a graph-aware,
profile-driven memory architecture for agentic systems.

The target model separates:

- 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.

## 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.

Current strengths:

- source spans
- namespaces
- deterministic summaries
- activation/deactivation lifecycle
- local package registry
- retrieval recipes
- token budgets
- provenance and policy metadata

Missing layers:

- 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
- graph-to-context-package compiler
- graph-aware CLI inspection/planning

## Decision

Implement this as an optional 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.

## P16.1 - Define graph memory vocabulary

```task
id: MKTT-WP-0016-T001
status: todo
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, and serialization tests.

## P16.2 - Add memory event log

```task
id: MKTT-WP-0016-T002
status: todo
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.

Events should capture:

- event id and timestamp
- actor/agent/thread/task namespace
- event kind
- references to context packages and activations
- graph node/edge updates
- branch and merge metadata
- policy metadata

Output: local event log interface, deterministic tests, and examples.

## P16.3 - Define memory service blueprint/profile standard

```task
id: MKTT-WP-0016-T003
status: todo
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
- stores/adapters per kind
- node/edge/event/package limits
- target p50/p95 latency
- retention and deletion rules
- refresh triggers
- compaction strategy
- activation token budgets
- policy reauthorization requirements
- observability events
- failure and fallback behavior

Output: profile schema, validation, example profiles, and docs.

## P16.4 - Implement local graph/event prototype

```task
id: MKTT-WP-0016-T004
status: todo
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:

- decision graph subgraphs
- conversation paths
- knowledge graph neighborhoods

This should be adequate for tests and local use, not a full graph database.

Output: local store or adapter interface, graph query helpers, and tests.

## P16.5 - Compile graph neighborhoods into context packages

```task
id: MKTT-WP-0016-T005
status: todo
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

Output: compiler API, provenance-preserving package output, and activation
tests.

## P16.6 - Add blueprint planning CLI

```task
id: MKTT-WP-0016-T006
status: todo
priority: medium
state_hub_task_id: "07fb3f0d-aaf7-4bc0-a7a3-0fd4983776bb"
```

Add CLI commands to inspect and plan memory systems:

```text
mkt memory blueprint validate <file>
mkt memory blueprint plan <file>
mkt memory graph explain <graph-or-package-id>
mkt memory graph pack <selection>
```

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.

Output: CLI commands, docs, and tests.

## P16.7 - Define adapter boundaries for advanced services

```task
id: MKTT-WP-0016-T007
status: todo
priority: medium
state_hub_task_id: "ff78d449-0738-4f1b-a018-2efed3d8e878"
```

Define optional adapter boundaries for:

- 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 adapter protocols only. Core graph/profile validation and local
package compilation must remain useful without them.

Output: adapter interface notes and extension descriptors.

## 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.