generated from coulomb/repo-seed
315 lines
14 KiB
Markdown
315 lines
14 KiB
Markdown
---
|
|
id: PMEM-MATURITY-SCORECARD
|
|
type: scorecard
|
|
title: "Phase Memory Maturity Scorecard"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: active
|
|
owner: phase-memory
|
|
created: "2026-05-18"
|
|
updated: "2026-05-18"
|
|
state_hub_workstream_id: "e82b1c2d-0c5e-47d3-9627-f85e7173dcbe"
|
|
---
|
|
|
|
# Phase Memory Maturity Scorecard
|
|
|
|
## Purpose
|
|
|
|
Track progress from the current foundation toward the full `INTENT.md` vision:
|
|
a profile-driven, phase-aware memory infrastructure layer for agentic systems.
|
|
|
|
This scorecard is intentionally practical. It scores what exists in this repo,
|
|
not what adjacent repositories may already provide.
|
|
|
|
## Scoring Scale
|
|
|
|
| Score | Meaning |
|
|
| --- | --- |
|
|
| 0 | Not started. |
|
|
| 1 | Intent or docs exist, but no executable behavior. |
|
|
| 2 | Deterministic local library slice exists with tests. |
|
|
| 3 | Usable local runtime or CLI exists with stable envelopes. |
|
|
| 4 | Integration-ready with policy, persistence, interop, and evaluation coverage. |
|
|
| 5 | Service-ready and operationally mature with adapter conformance and diagnostics. |
|
|
|
|
## Milestone Ladder
|
|
|
|
| Milestone | Target State | Primary Workplans |
|
|
| --- | --- | --- |
|
|
| M1 | Foundation complete: domain model, contract ingress, dry-run planners, ports, tests. | PMEM-WP-0001 |
|
|
| M2 | Usable local runtime: facade, CLI, stable JSON envelopes, local file persistence. | PMEM-WP-0002, PMEM-WP-0003 |
|
|
| M3 | Governed interop runtime: review gates, audit, policy-aware activation, Markitect package bridge. | PMEM-WP-0004, PMEM-WP-0005 |
|
|
| M4 | Evaluated activation memory: graph neighborhoods, event paths, ranking, quality metrics. | PMEM-WP-0006 |
|
|
| M5 | Service-ready adapter layer: service contracts, config, health, external adapter conformance. | PMEM-WP-0007 |
|
|
|
|
## Current Baseline - 2026-05-18
|
|
|
|
Overall maturity: **4.5 / 5**
|
|
|
|
The repo has crossed from intent-only into a working deterministic library
|
|
foundation, a usable local runtime facade, a CLI, a file-backed local
|
|
workspace, first-slice policy/review/audit gates, a concrete Markitect package
|
|
bridge, deterministic activation quality helpers, and first-slice service
|
|
readiness contracts with profile-driven runtime adapter resolution,
|
|
profile-derived lifecycle rules, and fake external adapter packs.
|
|
|
|
| Dimension | Current | Target | Evidence | Needed Next |
|
|
| --- | ---: | ---: | --- | --- |
|
|
| Intent and boundaries | 4.0 | 5.0 | `INTENT.md`, `SCOPE.md`, `README.md`, architecture doc, PMEM-WP-0001 closure | Keep boundaries current as runtime behavior expands. |
|
|
| Package foundation | 4.0 | 4.0 | Python package, exports, runtime facade, CLI entrypoint, config, service contracts, dependency-light tests | Maintain public API compatibility as adapters expand. |
|
|
| Profile contract ingress | 3.2 | 4.0 | Markitect-compatible profile loading, diagnostics, runtime envelopes, profile-derived runtime config, local adapter alias normalization | Add richer compatibility coverage. |
|
|
| Graph/event contract ingress | 3.7 | 4.0 | Graph loading, edge endpoint diagnostics, event model, JSONL event log, export, repair diagnostics, service import/export contracts, fake external graph/event adapters | Add broader external adapter fixtures. |
|
|
| Phase domain model | 3.4 | 4.0 | Phases, memory kinds, lifecycle states, actions, explicit path records, profile-derived transition rules | Add migration semantics. |
|
|
| Profile execution planning | 4.0 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior, CLI output, snapshot fixture, service contract, config-driven local and fake external adapter resolution | Maintain compatibility as live adapters land. |
|
|
| Lifecycle planning | 3.6 | 4.0 | Transition, retention, refresh, compaction dry-run plans, profile-driven lifecycle rules, review-gated local apply | Add service apply contracts and migration semantics. |
|
|
| Activation planning | 3.8 | 5.0 | Budgeted selection, Markitect-compatible selection output, package request envelope, graph neighborhoods, event paths, ranking, metadata preservation, metrics | Add semantic-index adapters and broader evaluation corpora. |
|
|
| Local persistence | 3.0 | 4.0 | Versioned local workspace, file-backed graph store, JSONL event log, JSONL audit sink | Add migration/repair utilities and stronger durability semantics. |
|
|
| Policy and audit | 3.5 | 5.0 | Operation points, policy gateway checks, audit schema, review records, redaction, activation denials, fake external policy/audit adapters | Add richer audit retention behavior and live policy adapters. |
|
|
| Observability and diagnostics | 3.8 | 4.0 | Planner diagnostics, runtime diagnostics, event log corruption checks, repair diagnostics, policy denial diagnostics, health envelopes, adapter status, fake telemetry audit sink | Add production telemetry adapters. |
|
|
| Markitect interop | 3.7 | 4.0 | Compatible contract ingress, optional validation boundary, enriched selection metadata, package request/response envelopes, fake Markitect package compiler | Add live optional Markitect compiler adapter when available. |
|
|
| Kontextual/Infospace interop | 3.0 | 4.0 | Boundaries documented, small derived fixtures, activation quality report fixture, Kontextual delegation envelope, fake Kontextual runtime registry | Add live delegation adapters and broader Infospace reports. |
|
|
| Testing and evaluation | 4.0 | 4.0 | 60 deterministic tests over planners, adapters, runtime envelopes, CLI, snapshots, file-store round trips, lifecycle rules, apply denial, review records, audit schema, policy redaction, Markitect bridge fixtures, retrieval, activation metrics, service contracts, config, health, conformance, adapter resolution, and fake external packs | Add broader evaluation corpora. |
|
|
| Service readiness | 4.0 | 4.0 | Runtime ports, service contracts, config model, profile-derived adapter resolution, health checks, local service runner lifecycle support, adapter conformance helpers, fake external adapter pack | Add framework-specific bindings and production adapter packs. |
|
|
| Developer experience | 3.7 | 4.0 | README quick start, package map, runtime facade docs, CLI examples, local persistence guide, service adapter resolution docs, lifecycle rule docs, external adapter pack docs | Add troubleshooting and richer examples. |
|
|
|
|
## Progress Update - PMEM-WP-0002
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added `PhaseMemoryRuntime` as the local application facade.
|
|
- Added JSON runtime envelopes with policy decisions, audit receipts,
|
|
diagnostics, dry-run flags, operation ids, and source references.
|
|
- Added `phase-memory` console script metadata and CLI commands for profile
|
|
planning, graph lifecycle planning, and graph activation planning.
|
|
- Added snapshot fixtures for profile-plan and activation-plan envelope shapes.
|
|
- Updated local usage and architecture docs.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- File-backed persistence and event path runtime.
|
|
- Review-gated apply behavior.
|
|
- Policy enforcement and redaction beyond the allow-all local adapter.
|
|
- Stronger Markitect compiler/validation bridge.
|
|
- Activation quality evaluation.
|
|
- Service contracts and external adapter conformance.
|
|
|
|
## Progress Update - PMEM-WP-0003
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added a versioned local file-backed workspace layout.
|
|
- Added deterministic file-backed profile, node, edge, and path storage.
|
|
- Added append-only JSONL event and audit adapters.
|
|
- Added graph export, event replay, and repair diagnostics.
|
|
- Added explicit conversational path records and path-event helpers.
|
|
- Added review-gated lifecycle apply behavior for local stores.
|
|
- Added store import/export/repair CLI coverage and local persistence docs.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Policy operation vocabulary and review records.
|
|
- Activation-time policy checks and redaction.
|
|
- Stable audit event schema.
|
|
- Markitect compiler/validation bridge.
|
|
- Activation quality metrics.
|
|
- Service readiness and external adapter conformance.
|
|
|
|
## Progress Update - PMEM-WP-0006
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added deterministic graph-neighborhood retrieval.
|
|
- Added event-path selection from structured memory paths.
|
|
- Added candidate scoring and explanation reasons.
|
|
- Added pluggable token estimator protocol with deterministic word-count
|
|
default.
|
|
- Added activation quality report metrics and fixture.
|
|
- Documented retrieval and evaluation behavior.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Service API contracts.
|
|
- Runtime configuration model.
|
|
- Health diagnostics.
|
|
- External adapter conformance tests.
|
|
- Kontextual delegation adapter design.
|
|
|
|
## Progress Update - PMEM-WP-0007
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added service operation contract catalog.
|
|
- Added runtime configuration model.
|
|
- Added health reports and adapter status diagnostics.
|
|
- Added local service runner shape without framework dependency.
|
|
- Added adapter conformance helpers.
|
|
- Added Kontextual delegation envelope.
|
|
- Documented deployment modes.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Live external adapter implementations.
|
|
- Broader evaluation corpora.
|
|
- Optional framework-specific service bindings.
|
|
- Production telemetry and audit retention integrations.
|
|
|
|
## Progress Update - PMEM-WP-0008
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added `RuntimeConfig.from_profile(...)` for Markitect-compatible profile
|
|
mappings and `ProfileIntent` inputs.
|
|
- Added adapter alias normalization for local graph stores, event logs, audit
|
|
sinks, package compilers, semantic indexes, and runtime registries.
|
|
- Added `RuntimeAdapterBundle` and `resolve_runtime_adapters(...)`.
|
|
- Updated `runtime_from_config(...)` and `LocalServiceRunner` to use resolved
|
|
adapters.
|
|
- Added diagnostics that block unresolved external adapters.
|
|
- Added tests and service readiness documentation for the resolver path.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Live external adapter implementations.
|
|
- Broader evaluation corpora.
|
|
- Optional framework-specific service bindings.
|
|
- Production telemetry and audit retention integrations.
|
|
|
|
## Progress Update - PMEM-WP-0009
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added `LifecycleRuleConfig` for profile-derived retention, transition,
|
|
refresh, and compaction settings.
|
|
- Added profile-derived retention planning.
|
|
- Added review-gated phase transition rules from profile metadata.
|
|
- Added `plan_lifecycle_from_profile(...)`.
|
|
- Added `PhaseMemoryRuntime.plan_lifecycle_with_profile(...)`.
|
|
- Added CLI `graph lifecycle --profile`.
|
|
- Added lifecycle rule docs, README examples, and regression tests.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Migration semantics for profile/rule changes over durable stores.
|
|
- Service apply contracts.
|
|
- Live external adapter implementations.
|
|
- Broader evaluation corpora.
|
|
|
|
## Progress Update - PMEM-WP-0010
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added `ExternalAdapterPack`.
|
|
- Added deterministic fake external graph and event adapters.
|
|
- Added fake Markitect package compiler.
|
|
- Added fake external policy gateway.
|
|
- Added fake telemetry audit sink with retention metadata.
|
|
- Added fake semantic index and fake Kontextual runtime registry.
|
|
- Added `fake_external_adapter_pack()` and `fake_external_runtime_config()`.
|
|
- Added conformance tests and all-external runtime wiring tests.
|
|
- Added external adapter pack documentation and README links.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Live external adapter implementations.
|
|
- Broader evaluation corpora.
|
|
- Framework-specific service bindings.
|
|
- Production audit retention and telemetry integrations.
|
|
|
|
## Progress Update - PMEM-WP-0004
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added canonical memory operation policy points.
|
|
- Added review records and deterministic review ids.
|
|
- Added stable audit event schema `phase_memory.audit.event.v1`.
|
|
- Added review-record enforcement for lifecycle apply.
|
|
- Added activation policy checks for labels, denied labels, trust zones,
|
|
secrets, reauthorization, and freshness.
|
|
- Added deterministic redaction records and diagnostics for denied activation
|
|
items.
|
|
- Added policy/audit documentation.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Optional Markitect validation and package compiler bridge.
|
|
- Activation ranking and evaluation metrics.
|
|
- Service contracts, health diagnostics, and external adapter conformance.
|
|
|
|
## Progress Update - PMEM-WP-0005
|
|
|
|
Closed on 2026-05-18:
|
|
|
|
- Added Markitect package request and response envelopes.
|
|
- Added local and optional Markitect validation adapter boundary.
|
|
- Preserved selected item source spans, provenance, confidence, freshness,
|
|
namespace, policy metadata, and selection reasons through activation.
|
|
- Added compatibility fixtures and tests for invalid contracts, activation
|
|
package requests, and opaque package responses.
|
|
- Documented the Markitect boundary.
|
|
|
|
Remaining maturity blockers:
|
|
|
|
- Graph-neighborhood retrieval and event-path activation.
|
|
- Ranking signals and token accounting.
|
|
- Activation quality metrics and evaluation fixtures.
|
|
- Service readiness and external adapter conformance.
|
|
|
|
## Score Movement Rules
|
|
|
|
A dimension should move up only when executable behavior and tests exist.
|
|
Documentation alone can justify score 1, but not score 2 or higher.
|
|
|
|
Suggested gates:
|
|
|
|
- Move to 3 when the behavior is usable through the runtime facade or CLI.
|
|
- Move to 4 when the behavior has policy, persistence, interop, and regression
|
|
coverage appropriate to its risk.
|
|
- Move to 5 when the behavior has service contracts, health diagnostics,
|
|
adapter conformance tests, and operational documentation.
|
|
|
|
## Workplan Dependency Map
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
WP1["PMEM-WP-0001\nArchitecture and foundation"]
|
|
WP2["PMEM-WP-0002\nLocal runtime facade and CLI"]
|
|
WP3["PMEM-WP-0003\nFile-backed stores and event paths"]
|
|
WP4["PMEM-WP-0004\nPolicy, audit, review gates"]
|
|
WP5["PMEM-WP-0005\nMarkitect package bridge"]
|
|
WP6["PMEM-WP-0006\nRetrieval and activation quality"]
|
|
WP7["PMEM-WP-0007\nService readiness and adapters"]
|
|
WP8["PMEM-WP-0008\nProfile-driven runtime config"]
|
|
WP9["PMEM-WP-0009\nProfile-driven lifecycle rules"]
|
|
WP10["PMEM-WP-0010\nFake external adapter packs"]
|
|
|
|
WP1 --> WP2
|
|
WP2 --> WP3
|
|
WP2 --> WP4
|
|
WP2 --> WP5
|
|
WP3 --> WP4
|
|
WP5 --> WP6
|
|
WP4 --> WP6
|
|
WP3 --> WP7
|
|
WP4 --> WP7
|
|
WP5 --> WP7
|
|
WP6 --> WP7
|
|
WP3 --> WP8
|
|
WP5 --> WP8
|
|
WP7 --> WP8
|
|
WP2 --> WP9
|
|
WP4 --> WP9
|
|
WP8 --> WP9
|
|
WP7 --> WP10
|
|
WP8 --> WP10
|
|
```
|
|
|
|
## Next Tracking Cadence
|
|
|
|
Update this scorecard at the end of each workplan closure review:
|
|
|
|
- record completed task ids
|
|
- update dimension scores only when tests and docs support the change
|
|
- add residual risks
|
|
- list score regressions if behavior was removed or narrowed
|
|
- link new workplans if the intent expands
|