memory graph and services

docs/examples-index.md

@@ -46,6 +46,7 @@ This index maps example files to practical usecases and useful commands.
 | `examples/policy/local-label-policy.yaml` | Local policy gateway | `mkt policy check public-agent read note --policy examples/policy/local-label-policy.yaml --label public` |
 | `examples/policy/enterprise-policy-map.yaml` | Enterprise IAM mapping fixture | `mkt policy subject examples/policy/netkingdom-claims.yaml --policy-map examples/policy/enterprise-policy-map.yaml` |
 | `examples/memory/workplan-context.manifest.yaml` | Context package manifest | `mkt context pack examples/memory/workplan-context.manifest.yaml --root . --no-save` |
+| `examples/memory/memory-profile.local.yaml`, `examples/memory/decision-graph*.yaml` | Memory graph/profile contract fixtures | `mkt memory graph pack examples/memory/decision-graph-selection.yaml --format yaml` |
 
 ## Literate And Migration
 

docs/memory-graph-contract.md

@@ -0,0 +1,76 @@
+# 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.