generated from coulomb/repo-seed
294 lines
8.8 KiB
Markdown
294 lines
8.8 KiB
Markdown
---
|
|
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.
|