generated from coulomb/repo-seed
281 lines
8.9 KiB
Markdown
281 lines
8.9 KiB
Markdown
---
|
|
id: KONT-WP-0017
|
|
type: workplan
|
|
title: "Agentic Memory Graph Runtime And Operational State"
|
|
domain: markitect
|
|
repo: kontextual-engine
|
|
status: completed
|
|
owner: codex
|
|
topic_slug: markitect
|
|
planning_priority: medium
|
|
planning_order: 17
|
|
created: "2026-05-15"
|
|
updated: "2026-05-15"
|
|
depends_on_workplans:
|
|
- KONT-WP-0007
|
|
- KONT-WP-0008
|
|
- KONT-WP-0009
|
|
- KONT-WP-0010
|
|
related_workplans:
|
|
- MKTT-WP-0016
|
|
- IB-WP-0017
|
|
state_hub_workstream_id: "18b51fcd-6a32-49f7-8d02-549a2768d0eb"
|
|
---
|
|
|
|
# KONT-WP-0017: Agentic Memory Graph Runtime And Operational State
|
|
|
|
## Purpose
|
|
|
|
Implement the durable runtime side of the agentic memory architecture described
|
|
by the `markitect-tool` memory graph/profile contracts.
|
|
|
|
`markitect-tool` should define schemas, validation, fixtures, adapter
|
|
descriptors, and deterministic graph-to-context-package compilation.
|
|
`kontextual-engine` should own the durable operational layer: graph/event
|
|
persistence, permission-aware retrieval, lifecycle state, auditability,
|
|
retention, compaction, and agent-safe APIs.
|
|
|
|
## Architecture Boundary
|
|
|
|
This workplan belongs in `kontextual-engine` because it is about persistent,
|
|
governed, operational memory state.
|
|
|
|
Allowed responsibilities:
|
|
|
|
- Persist memory graph nodes, edges, events, packages, and activations.
|
|
- Attach stable asset identity, provenance, policy metadata, lifecycle state,
|
|
and audit records.
|
|
- Execute retention, deletion, refresh, compaction, and reauthorization rules.
|
|
- Expose permission-aware retrieval and context assembly APIs.
|
|
- Import and validate `markitect-tool` memory profiles without redefining the
|
|
syntax-layer contract.
|
|
|
|
Disallowed responsibilities:
|
|
|
|
- Do not redefine Markitect's graph/profile schema vocabulary.
|
|
- Do not implement a document syntax parser or context package compiler that
|
|
competes with `markitect-tool`.
|
|
- Do not hard-code application-specific infospace evaluation logic.
|
|
- Do not require any one graph database, vector store, LLM provider, or
|
|
enterprise policy system in the core implementation.
|
|
|
|
## Implementation Update - 2026-05-15
|
|
|
|
The first runtime-contract slice is implemented. `kontextual-engine` can now
|
|
map `markitect.memory.graph.v1` and `markitect.memory.profile.v1` envelopes
|
|
into stable runtime records, persist them through a `MemoryGraphRepository`
|
|
port, and use `InMemoryMemoryGraphRepository` as the deterministic local
|
|
implementation for tests.
|
|
|
|
The implementation deliberately does not validate Markitect's node/edge
|
|
vocabulary. It checks runtime compatibility concerns only: schema version,
|
|
required ids, edge endpoint integrity, stable runtime id mapping, source-span
|
|
preservation, and append-only event identity.
|
|
|
|
Primary files:
|
|
|
|
- `src/kontextual_engine/core/memory.py`
|
|
- `src/kontextual_engine/ports/memory.py`
|
|
- `src/kontextual_engine/adapters/memory/graph_store.py`
|
|
- `src/kontextual_engine/services/memory_service.py`
|
|
- `docs/memory-graph-runtime.md`
|
|
|
|
The permission-aware retrieval slice is also implemented in
|
|
`MemoryRuntimeService.query_memory()`. It performs a scope policy check,
|
|
per-node policy checks, returns source-grounded context items, preserves denied
|
|
diagnostics without leaking denied node text, and emits an audit event in the
|
|
result envelope.
|
|
|
|
The lifecycle slice is implemented with deterministic local operations:
|
|
`apply_retention()` marks stale memories for review or transitions old memories
|
|
to `delete_requested`; `refresh_memory()` clears stale markers; and
|
|
`compact_memory()` creates a provenance/source-span preserving summary node,
|
|
optionally retiring the source nodes. Each mutating operation appends a memory
|
|
event and returns audit metadata.
|
|
|
|
The agent-safe API slice is implemented with dry-run update plans, explicit
|
|
review gates for durable writes, source/policy explanations on planned node
|
|
updates, and Markitect-compatible context package input export. The export
|
|
method emits package inputs only; Markitect remains the package compiler.
|
|
|
|
The observability/export slice is implemented. Memory audit events are now
|
|
persisted through the memory graph repository, queryable by graph, correlation,
|
|
and operation. Runtime export envelopes include graph nodes, edges, memory
|
|
events, audit traces, operation id, actor metadata, policy decisions, and
|
|
filter metadata for portable inspection or handoff.
|
|
|
|
The external adapter boundary slice is implemented. Optional semantic indexes,
|
|
audit sinks, and runtime registries are defined as ports with capability
|
|
metadata, while graph databases continue to implement `MemoryGraphRepository`
|
|
and enterprise policy systems continue to implement `PolicyGateway`.
|
|
|
|
## P17.1 - Import and map Markitect memory contracts
|
|
|
|
```task
|
|
id: KONT-WP-0017-T001
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "1b1f8904-3a3b-4d23-9d00-176633578801"
|
|
```
|
|
|
|
Define how `kontextual-engine` consumes memory graph/profile contracts from
|
|
`markitect-tool`.
|
|
|
|
The mapping should cover:
|
|
|
|
- graph node, edge, event, and profile schema versions
|
|
- stable runtime IDs versus source contract IDs
|
|
- provenance and source-span preservation
|
|
- policy metadata and reauthorization hints
|
|
- context package and activation references
|
|
- schema compatibility and migration strategy
|
|
|
|
Output: contract import design, mapping tests, and compatibility fixtures.
|
|
|
|
## P17.2 - Add durable graph and event storage
|
|
|
|
```task
|
|
id: KONT-WP-0017-T002
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "dc3557e3-d425-46b0-8acc-9ac0230a385c"
|
|
```
|
|
|
|
Implement runtime persistence for memory graph and event records.
|
|
|
|
The first slice should support:
|
|
|
|
- nodes and edges with typed relationships
|
|
- append-only memory events
|
|
- branch and merge metadata
|
|
- source-grounded provenance
|
|
- lifecycle state and timestamps
|
|
- deterministic local test storage
|
|
|
|
Output: storage interfaces, local implementation or test double, and CRUD/query
|
|
tests.
|
|
|
|
## P17.3 - Implement permission-aware retrieval and context assembly
|
|
|
|
```task
|
|
id: KONT-WP-0017-T003
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "711b945e-19e6-4548-8ddb-6c2c364148ca"
|
|
```
|
|
|
|
Expose retrieval operations that can select graph neighborhoods, decision
|
|
paths, conversation episodes, and knowledge neighborhoods while respecting
|
|
engine policy decisions.
|
|
|
|
The retrieval layer should:
|
|
|
|
- apply existing policy gateways and fail-closed behavior
|
|
- preserve denied-item explanations without leaking content
|
|
- produce source-grounded snippets or Markitect-compatible package inputs
|
|
- record retrieval provenance and actor context
|
|
|
|
Output: service/domain API, permission tests, and denied-access diagnostics.
|
|
|
|
## P17.4 - Add retention, refresh, and compaction operations
|
|
|
|
```task
|
|
id: KONT-WP-0017-T004
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "853807fe-53ac-440e-823f-8d9b0b7ce4b7"
|
|
```
|
|
|
|
Implement operational memory lifecycle behavior from declared profiles.
|
|
|
|
The engine should support:
|
|
|
|
- retention windows
|
|
- deletion rules
|
|
- refresh triggers
|
|
- compaction runs
|
|
- stale assumption and freshness markers
|
|
- review-required transitions
|
|
|
|
Output: lifecycle operations, workflow/job integration points, audit events,
|
|
and tests.
|
|
|
|
## P17.5 - Add agent-safe memory APIs
|
|
|
|
```task
|
|
id: KONT-WP-0017-T005
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "9e2ad830-c9e6-47a2-8eca-ffe895781fdf"
|
|
```
|
|
|
|
Expose bounded APIs for agents to inspect, retrieve, update, and package memory
|
|
state.
|
|
|
|
The API should support:
|
|
|
|
- dry-run update plans
|
|
- review gates for durable writes
|
|
- source and policy explanations
|
|
- package export to `markitect-tool` context packages
|
|
- explicit actor, namespace, thread, and task coordinates
|
|
|
|
Output: API contracts, tests, and agent-safe operation notes.
|
|
|
|
## P17.6 - Add observability, audit, and export surface
|
|
|
|
```task
|
|
id: KONT-WP-0017-T006
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "54f51f87-6420-4170-913f-f6dae098fe71"
|
|
```
|
|
|
|
Record memory operations as auditable engine events.
|
|
|
|
The runtime should expose:
|
|
|
|
- operation ids
|
|
- actor and policy decision metadata
|
|
- affected graph nodes, edges, events, and packages
|
|
- compaction and retention traces
|
|
- export/import envelopes for portability
|
|
|
|
Output: audit model, observability events, export fixtures, and tests.
|
|
|
|
## P17.7 - Define external runtime adapter boundaries
|
|
|
|
```task
|
|
id: KONT-WP-0017-T007
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "c3cf79d8-389c-4583-a02d-303d0ce75cc1"
|
|
```
|
|
|
|
Define optional adapters for advanced memory runtimes without making them core
|
|
dependencies.
|
|
|
|
Candidate adapters:
|
|
|
|
- external graph databases
|
|
- vector stores and embedding providers
|
|
- future `phased-memory` services
|
|
- enterprise policy decision points
|
|
- durable event sinks
|
|
- remote memory registries
|
|
|
|
Output: adapter interfaces and extension notes that preserve local deterministic
|
|
engine behavior.
|
|
|
|
## Exit Criteria
|
|
|
|
- The engine can persist and retrieve memory graph/event state using
|
|
Markitect-compatible contracts.
|
|
- Permission-aware retrieval and context assembly are source-grounded and
|
|
auditable.
|
|
- Retention, refresh, compaction, and review gates are modeled as operational
|
|
engine behavior.
|
|
- Agents have bounded APIs for memory operations.
|
|
- Markitect remains the contract/compiler layer; infospace-bench remains the
|
|
applied evaluation layer.
|