generated from coulomb/repo-seed
Add phase-memory architecture workplan
This commit is contained in:
247
workplans/PMEM-WP-0001-architecture-and-foundation.md
Normal file
247
workplans/PMEM-WP-0001-architecture-and-foundation.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user