From 751da54052961cf03a2bf33e71185a42220caf3f Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 18 May 2026 01:31:28 +0200 Subject: [PATCH] Add phase-memory architecture workplan --- docs/architecture.md | 157 +++++++++++ ...MEM-WP-0001-architecture-and-foundation.md | 247 ++++++++++++++++++ 2 files changed, 404 insertions(+) create mode 100644 docs/architecture.md create mode 100644 workplans/PMEM-WP-0001-architecture-and-foundation.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..95d30c3 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,157 @@ +# Phase Memory Architecture Sketch + +Date: 2026-05-18 +Status: initial sketch + +## Purpose + +`phase-memory` should be the memory operating layer between Markitect's +contract compiler, Kontextual Engine's durable knowledge runtime, and +Infospace Bench's evaluation fixtures. + +The adjacent repositories already cover important slices: + +- `markitect-tool` owns deterministic memory profile, graph, event, and + selection contracts, plus compilation of selected graph items into context + packages. +- `kontextual-engine` owns durable knowledge and memory graph records, + permission-aware retrieval, audit events, retention, refresh, compaction, + review-gated updates, and Markitect-compatible export envelopes. +- `infospace-bench` owns concrete corpus pilots, restart-package evaluation, + metrics, and fixture feedback. + +The missing layer is memory-native orchestration: interpreting profile intent +as phase-aware runtime plans, deciding which lifecycle actions are allowed or +required, planning activation packages, and coordinating adapter behavior +without becoming a markdown contract library, knowledge database, or benchmark. + +## Architecture Layers + +```mermaid +flowchart TB + MT["markitect-tool\ncontracts + package compiler"] + PM["phase-memory\nprofile execution + phase policy"] + KE["kontextual-engine\ndurable graph/runtime records"] + IB["infospace-bench\nfixtures + evaluation"] + EXT["optional adapters\ngraph, vector, policy, audit, registry"] + + MT -->|"profile, graph, selection contracts"| PM + PM -->|"runtime plan, lifecycle actions"| KE + KE -->|"graph records, audit traces, context inputs"| PM + PM -->|"selection/package request"| MT + IB -->|"profile + graph fixtures, metrics"| PM + PM -->|"planned retrieval/evaluation envelopes"| IB + PM -->|"adapter calls"| EXT +``` + +### 1. Contract Ingress + +Accept Markitect-compatible memory profiles, graph snapshots, events, and +selections as input contracts. `phase-memory` may call Markitect validators, but +it should not fork the Markitect vocabulary or become the syntax owner. + +Primary input contracts: + +- `markitect.memory.profile.v1` +- `markitect.memory.graph.v1` +- `markitect.memory.selection.v1` + +### 2. Phase Domain Model + +Introduce a memory-native model that explains what a profile means at runtime: + +- phases: `ephemeral`, `fluid`, `stabilized`, `rigid` +- memory kinds: `reasoning`, `conversation`, `knowledge`, `package`, + `identity`, `preference`, `source`, `task`, `tool` +- lifecycle states: active, stale, review-needed, compacted, superseded, + delete-requested, archived +- profile intent: limits, latency, retention, deletion, decay, refresh, + compaction, merge/conflict policy, activation, failure behavior, and policy + reauthorization +- action plans: deterministic dry-run records that explain proposed writes, + reads, activations, compactions, and denials + +### 3. Planning Engines + +The first useful implementation should be deterministic and local-first. + +Core planners: + +- Profile execution planner: turns a profile into a runtime capability and + adapter plan. +- Phase transition planner: decides which records can move from ephemeral or + fluid memory into stabilized or rigid memory. +- Retention planner: proposes stale, delete-requested, archived, or refresh + actions without physical deletion by default. +- Compaction planner: groups trace windows or graph neighborhoods into + reviewable summary-node proposals. +- Activation planner: turns graph neighborhoods and event paths into + Markitect-compatible selections under token/item budgets. +- Policy planner: surfaces required reauthorization, labels, trust zones, and + review gates before a runtime applies durable writes. + +### 4. Runtime Ports + +`phase-memory` should define ports before committing to infrastructure: + +- `MemoryGraphStore`: graph node, edge, event, and profile access +- `MemoryEventLog`: append-only fluid/conversational path events +- `ContextPackageCompiler`: Markitect-backed package compilation boundary +- `SemanticIndex`: optional vector or hybrid retrieval +- `PolicyGateway`: read/write/activation authorization +- `AuditSink`: durable operation and policy-decision recording +- `RuntimeRegistry`: remote or sibling runtime envelope exchange + +Local in-memory or file-backed adapters are enough for the first slice. External +graph databases, vector stores, LLM extraction, enterprise policy systems, and +remote registries should remain optional adapters. + +## Repository Boundaries + +`phase-memory` owns: + +- phase semantics and lifecycle policy +- profile execution planning +- retention, deletion, decay, refresh, compaction, and stabilization decisions +- activation planning and adapter orchestration +- memory-specific audit and observability envelopes +- deterministic local runtime behavior for tests and small deployments + +`phase-memory` does not own: + +- Markitect syntax vocabulary or context package internals +- generic content/knowledge artifact persistence +- benchmark corpus ownership or evaluation dashboards +- full identity or authorization platforms +- generic vector database behavior +- provider-specific LLM memory plugins + +## First Viable Slice + +The first implementation should establish a small package with: + +1. Python project scaffold and tests. +2. Domain dataclasses for phases, profile intent, lifecycle actions, and + runtime plans. +3. A Markitect contract adapter that accepts already-valid profile/graph + dictionaries and reports diagnostics without redefining schemas. +4. A deterministic profile execution planner. +5. A local in-memory store/event-log adapter for tests. +6. A fixture set derived from Markitect examples and the Infospace Bench + agentic-memory pilot. +7. Docs that keep the Markitect, Kontextual, Infospace, and Phase Memory + boundaries explicit. + +The slice should emit plans first, not mutate durable memory by surprise. +Durable writes, external adapters, live LLM extraction, vector retrieval, and +service deployment can follow once the plan model is stable. + +## Open Questions + +- Should `phase-memory` depend directly on `markitect-tool` for validation, or + shell out/consume JSON diagnostics to keep the boundary looser? +- Should the first local store be pure in-memory, JSONL/file-backed, or SQLite? +- Which actions belong in a stable public API first: activation planning, + retention planning, compaction planning, or profile capability inspection? +- How should `kontextual-engine` delegate phase-specific decisions without + creating circular imports? diff --git a/workplans/PMEM-WP-0001-architecture-and-foundation.md b/workplans/PMEM-WP-0001-architecture-and-foundation.md new file mode 100644 index 0000000..85dfcf2 --- /dev/null +++ b/workplans/PMEM-WP-0001-architecture-and-foundation.md @@ -0,0 +1,247 @@ +--- +id: PMEM-WP-0001 +type: workplan +title: "Phase Memory Architecture And Foundation" +domain: markitect +repo: phase-memory +status: active +owner: phase-memory +topic_slug: markitect +planning_priority: P1 +planning_order: 10 +related_workplans: + - MKTT-WP-0016 + - KONT-WP-0017 + - IB-WP-0017 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "ff1d85f4-5def-4492-9c91-b142dde7ccf4" +--- + +# PMEM-WP-0001: Phase Memory Architecture And Foundation + +## Goal + +Turn `phase-memory` from an intent-only repository into the first executable +memory operating layer for profile-driven agentic memory. + +This workplan starts with architecture, repository foundation, deterministic +domain models, and dry-run planning. It deliberately avoids launching a durable +service or claiming ownership of contracts already owned by adjacent repos. + +## Architecture Position + +`markitect-tool` owns memory contracts and graph-to-context-package +compilation. `kontextual-engine` owns durable knowledge/runtime records, +permission-aware retrieval, audit, and durable graph storage. `infospace-bench` +owns concrete pilots and evaluation metrics. + +`phase-memory` should own the missing orchestration layer: + +- phase semantics: ephemeral, fluid, stabilized, and rigid +- profile execution planning +- retention, deletion, decay, refresh, compaction, and stabilization decisions +- activation planning under token/item budgets +- memory-specific adapter orchestration, policy gates, audit intent, and + observability envelopes + +See `docs/architecture.md` for the initial architecture sketch. + +## Non-Goals + +- Do not fork Markitect's memory schema vocabulary. +- Do not implement generic knowledge persistence already owned by + `kontextual-engine`. +- Do not build a benchmark corpus or evaluation harness already owned by + `infospace-bench`. +- Do not require external graph databases, vector stores, LLM providers, + enterprise PDPs, or remote registries in the default test path. +- Do not perform durable memory writes without explicit review-gated plans. + +## T01 - Establish repository foundation + +```task +id: PMEM-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: "718df85f-3bed-46ca-8699-46d9819bb0ad" +``` + +Create the repo foundation needed for implementation work: + +- update `README.md` so it describes `phase-memory`, not the seed template +- write `SCOPE.md` with ownership boundaries and adjacent repo relationships +- add a Python package scaffold under `src/phase_memory` +- add `pyproject.toml`, test tooling, and a first smoke test +- preserve local-first, deterministic behavior in the default test suite + +Output: installable package skeleton, basic test pass, README/SCOPE aligned +with `INTENT.md`. + +## T02 - Codify phase-memory domain model + +```task +id: PMEM-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "47abf09f-d9cd-4d7e-adc0-7cc75d9f1e07" +``` + +Define core deterministic domain types: + +- `MemoryPhase`: ephemeral, fluid, stabilized, rigid +- `MemoryKind`: reasoning, conversation, knowledge, package, identity, + preference, source, task, tool +- lifecycle state and lifecycle action records +- profile intent records for limits, latency, retention, refresh, compaction, + activation, policy, observability, and failure behavior +- runtime plan and diagnostic envelopes + +Output: typed models, serialization helpers, and unit tests. + +## T03 - Add Markitect contract ingress adapter + +```task +id: PMEM-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: "9d47d569-113d-4126-a511-16ae3f31c8a0" +``` + +Accept Markitect-compatible memory profiles, graph snapshots, event envelopes, +and selections without redefining Markitect's schema ownership. + +The adapter should: + +- load or accept `markitect.memory.profile.v1` dictionaries +- preserve graph/profile ids, memory kinds, store declarations, activation + budgets, policy blocks, and failure behavior +- report contract diagnostics in phase-memory terms +- stay compatible with Markitect fixtures from `examples/memory/` + +Output: adapter module and tests against copied/minimal fixtures. + +## T04 - Implement profile execution planner + +```task +id: PMEM-WP-0001-T04 +status: todo +priority: high +state_hub_task_id: "2c9e29c3-1e22-45a5-bc9e-a5a1af188eb3" +``` + +Turn a memory profile into a deterministic dry-run runtime plan. + +The plan should explain: + +- enabled memory kinds and required stores/adapters +- declared limits and activation budgets +- retention, refresh, and compaction intent +- required policy gates and review gates +- observability events that would be emitted +- fallback behavior when an adapter is missing + +Output: `ProfileExecutionPlan` API, fixture outputs, and tests. + +## T05 - Define local runtime ports and adapters + +```task +id: PMEM-WP-0001-T05 +status: todo +priority: medium +state_hub_task_id: "a7a0c110-644a-47cf-8935-0d5d73f8f5ed" +``` + +Define ports before choosing durable infrastructure: + +- memory graph store +- append-only memory event log +- context package compiler boundary +- semantic index boundary +- policy gateway boundary +- audit sink boundary +- runtime registry boundary + +Add in-memory or file-backed test adapters only where needed by this workplan. + +Output: protocol/adapter definitions and deterministic adapter tests. + +## T06 - Implement first lifecycle planners + +```task +id: PMEM-WP-0001-T06 +status: todo +priority: high +state_hub_task_id: "e7d7d59f-cb63-4786-8bbf-a178340b61fe" +``` + +Implement initial dry-run planners for: + +- phase transitions from fluid to stabilized memory +- stale memory review +- delete-requested actions without physical deletion +- compaction proposal records for trace windows or graph neighborhoods +- refresh proposal records when source/profile digests change + +Output: lifecycle planner APIs, diagnostics, fixtures, and tests. + +## T07 - Implement activation planning handoff + +```task +id: PMEM-WP-0001-T07 +status: todo +priority: medium +state_hub_task_id: "881bc81b-e316-416d-af2a-fbe93224b617" +``` + +Plan graph/event selections for context-package activation without taking over +Markitect's compiler. + +The planner should: + +- select graph nodes/events under item and token budgets +- preserve source spans, provenance, confidence, freshness, and policy metadata +- emit a Markitect-compatible selection or package request +- explain omitted items and budget pressure + +Output: activation planner and selection fixture tests. + +## T08 - Add adjacent-repo fixture set + +```task +id: PMEM-WP-0001-T08 +status: todo +priority: medium +state_hub_task_id: "e841d580-c77e-4aad-8bce-08c5aaf19258" +``` + +Create minimal fixtures derived from: + +- Markitect memory graph/profile examples +- Kontextual memory runtime boundary records +- Infospace Bench agentic memory profile pilot + +Fixtures must be small, deterministic, and safe for default tests. + +Output: fixture catalog, tests, and documentation of what each fixture proves. + +## T09 - Sync StateHub and document the next slice + +```task +id: PMEM-WP-0001-T09 +status: todo +priority: medium +state_hub_task_id: "9927eebd-18f6-40e6-8b6a-fd0056759ebf" +``` + +Bring the repo into StateHub/ADR-001 shape and prepare the next workplan. + +This includes: + +- syncing this workplan with StateHub +- regenerating the custodian brief +- documenting remaining architecture questions +- proposing the next workplan for a first usable local runtime + +Output: StateHub consistency pass or documented residual warnings, plus a +candidate `PMEM-WP-0002` outline.