generated from coulomb/repo-seed
113 lines
5.4 KiB
Markdown
113 lines
5.4 KiB
Markdown
# 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.
|