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

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

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