---
id: PMEM-WP-0001
type: workplan
title: "Phase Memory Architecture And Foundation"
domain: markitect
repo: phase-memory
status: finished
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.

## 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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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.