generated from coulomb/repo-seed
Extension workplan for phased-memory
This commit is contained in:
@@ -0,0 +1,270 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user