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

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

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