generated from coulomb/repo-seed
77 lines
3.0 KiB
Markdown
77 lines
3.0 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`, `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.
|