markitect-tool/docs/memory-graph-contract.md

Memory Graph Contract

Markitect owns the deterministic contract layer for agentic memory. It validates memory profiles, validates graph snapshots/events, and compiles selected graph nodes into context packages. Runtime storage, retrieval, compaction, refresh, and benchmark execution stay outside this repository.

Contract Versions

• markitect.memory.profile.v1: service-agnostic memory blueprint/profile.
• markitect.memory.graph.v1: graph snapshot with typed nodes, edges, and event envelopes.
• markitect.memory.selection.v1: packageable graph selection.

Profile Shape

A profile declares which memory kinds a runtime supports and the contracts that go with them.

schema_version: markitect.memory.profile.v1
id: local-agent-memory
title: Local Agent Memory
intent: Compile selected reasoning and knowledge memories into context packages.
memory_kinds: [reasoning, knowledge, package]
stores:
  reasoning: local-event-log
  knowledge: local-graph-store
  package: markitect-context-registry
activation:
  max_items: 8
  max_tokens: 2400

The profile is descriptive in Markitect. mkt memory blueprint plan explains the handoff to runtime repositories but does not launch services.

Graph Shape

A graph contains explicit node, edge, and event vocabulary. Unknown kinds fail validation so that cross-repository contracts do not drift silently.

Valid node kinds include question, claim, assumption, evidence, decision, alternative, outcome, risk, follow_up, turn, plan, tool_call, observation, edit, validation, task, topic, document, entity, artifact, concept, capability, contract, policy, preference, source_fact, episode, finding, constraint, profile, context_package, and memory.

Valid edge kinds include supports, contradicts, depends_on, derived_from, led_to, affects, references, relates_to, supersedes, belongs_to, mentions, activates, and governs.

Valid event kinds include recorded, updated, activated, deactivated, refreshed, compacted, forgotten, branched, merged, and policy_decision.

Selection To Context Package

mkt memory graph pack reads a markitect.memory.selection.v1 file, resolves the referenced graph/profile, validates both contracts, and emits a normal ContextPackage. Selected nodes become package items. Selected or implied edges are preserved in package metadata, while selected events are included as synthetic package items.

mkt memory blueprint validate examples/memory/memory-profile.local.yaml
mkt memory blueprint plan examples/memory/memory-profile.local.yaml
mkt memory graph validate examples/memory/decision-graph.yaml
mkt memory graph pack examples/memory/decision-graph-selection.yaml --format yaml

This keeps Markitect as the compiler/contract boundary. kontextual-engine should implement runtime stores and event production against these schemas, and infospace-bench should benchmark generated context packages and runtime retrieval behavior against the same fixtures.