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, interruption, activation, 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

Fixture Catalog

The memory fixtures cover the three intended memory views:

Files	View	Purpose
`examples/memory/decision-graph.yaml`, `examples/memory/decision-graph-selection.yaml`	reasoning	Decision and constraint path that pins the contract/runtime boundary.
`examples/memory/conversation-path.yaml`, `examples/memory/conversation-path-selection.yaml`	conversation	Short-term branch/plan/tool/observation episode with event activation.
`examples/memory/knowledge-neighborhood.yaml`, `examples/memory/knowledge-neighborhood-selection.yaml`	knowledge	Durable neighborhood around schema versions, docs, compiler capability, and runtime policy.
`examples/memory/memory-profile.local.yaml`	mixed profile	Local profile declaring reasoning, knowledge, and package stores plus activation limits.
`examples/memory/invalid-memory-graph.yaml`, `examples/memory/invalid-memory-profile.yaml`	invalid	Negative fixtures for validation diagnostics and handoff contract tests.

The valid selections compile to standard ContextPackage output. Invalid fixtures are deliberately small so downstream runtimes can assert diagnostic codes without needing Markitect-owned durable storage.

Runtime Adapter Handoff

examples/memory/runtime-adapter-boundaries.yaml is a non-executing descriptor catalog for external memory runtimes and stores. It names the contracts that runtime packages should accept or emit while keeping Markitect limited to local validation, planning, and package compilation.

The descriptor catalog covers:

Boundary	Responsibility
`memory.runtime.kontextual-engine`	Durable graph snapshots, event append, selection resolution, and refresh execution.
`memory.runtime.phased-memory`	Future lifecycle policies such as compaction, retention intent, and observability.
`memory.store.external-graph`	External graph database path and neighborhood queries.
`memory.store.vector`	Embedding and vector retrieval flows that return graph selections.
`memory.extract.llm-assisted`	Optional graph extraction proposals from transcripts or source artifacts.
`memory.policy.enterprise-pdp`	Runtime policy authorization and activation reauthorization.
`memory.registry.remote`	Future remote profile/package registry interactions.
`memory.audit.sink`	Durable audit and policy decision event sinks.

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.

5.4 KiB Raw Blame History