diff --git a/workplans/KONT-WP-0017-agentic-memory-graph-runtime.md b/workplans/KONT-WP-0017-agentic-memory-graph-runtime.md new file mode 100644 index 0000000..8a68751 --- /dev/null +++ b/workplans/KONT-WP-0017-agentic-memory-graph-runtime.md @@ -0,0 +1,230 @@ +--- +id: KONT-WP-0017 +type: workplan +title: "Agentic Memory Graph Runtime And Operational State" +domain: markitect +repo: kontextual-engine +status: todo +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. + +## P17.1 - Import and map Markitect memory contracts + +```task +id: KONT-WP-0017-T001 +status: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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: todo +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.