phase-memory/workplans/PMEM-WP-0001-architecture-and-foundation.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	related_workplans	created	updated	state_hub_workstream_id
PMEM-WP-0001	workplan	Phase Memory Architecture And Foundation	markitect	phase-memory	finished	phase-memory	markitect	P1	10	MKTT-WP-0016 KONT-WP-0017 IB-WP-0017	2026-05-18	2026-05-18	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.

Implementation Update - 2026-05-18

The first implementation slice is complete.

Implemented outputs:

• README.md and SCOPE.md now describe the real repository boundary.
• pyproject.toml defines a dependency-light Python package.
• src/phase_memory/ contains deterministic domain models, Markitect contract ingress, profile execution planning, lifecycle planning, activation planning, runtime ports, and local in-memory adapters.
• tests/fixtures/ contains small Markitect-compatible profile and graph fixtures derived from the adjacent memory work.
• tests/ covers contract ingress, profile planning, lifecycle planning, activation handoff, local adapters, and smoke import behavior.
• docs/pmem-wp-0002-outline.md sketches the next local runtime/service slice.

Validation:

• python3 -m pytest -> 13 passed.

T01 - Establish repository foundation

id: PMEM-WP-0001-T01
status: done
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

id: PMEM-WP-0001-T02
status: done
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

id: PMEM-WP-0001-T03
status: done
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

id: PMEM-WP-0001-T04
status: done
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

id: PMEM-WP-0001-T05
status: done
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

id: PMEM-WP-0001-T06
status: done
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

id: PMEM-WP-0001-T07
status: done
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

id: PMEM-WP-0001-T08
status: done
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

id: PMEM-WP-0001-T09
status: done
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.

Closure Review - 2026-05-18

Outcome: All tasks completed.

Completed

• PMEM-WP-0001-T01 - Establish repository foundation
• PMEM-WP-0001-T02 - Codify phase-memory domain model
• PMEM-WP-0001-T03 - Add Markitect contract ingress adapter
• PMEM-WP-0001-T04 - Implement profile execution planner
• PMEM-WP-0001-T05 - Define local runtime ports and adapters
• PMEM-WP-0001-T06 - Implement first lifecycle planners
• PMEM-WP-0001-T07 - Implement activation planning handoff
• PMEM-WP-0001-T08 - Add adjacent-repo fixture set
• PMEM-WP-0001-T09 - Sync StateHub and document the next slice

Cancelled

None.

Carried Forward

The next slice is outlined in docs/pmem-wp-0002-outline.md; no open task is carried forward from this workplan.