diff --git a/docs/pmem-wp-0002-outline.md b/docs/pmem-wp-0002-outline.md index 0683559..4f96e44 100644 --- a/docs/pmem-wp-0002-outline.md +++ b/docs/pmem-wp-0002-outline.md @@ -1,5 +1,7 @@ # Candidate PMEM-WP-0002 Outline +Superseded by `workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md`. + Status: candidate outline ## Title diff --git a/workplans/PMEM-MATURITY-SCORECARD.md b/workplans/PMEM-MATURITY-SCORECARD.md new file mode 100644 index 0000000..8d04535 --- /dev/null +++ b/workplans/PMEM-MATURITY-SCORECARD.md @@ -0,0 +1,119 @@ +--- +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: **2.0 / 5** + +The repo has crossed from intent-only into a working deterministic library +foundation. It is not yet a usable local runtime because there is no facade, +CLI, file-backed persistence, review-gated apply path, package compiler bridge, +or service contract. + +| 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 | 2.5 | 4.0 | Python package, exports, dependency-light tests | Add runtime facade, stable public envelopes, CLI. | +| Profile contract ingress | 2.0 | 4.0 | Markitect-compatible profile loading and diagnostics | Add validation adapter boundary and compatibility fixture catalog. | +| Graph/event contract ingress | 2.0 | 4.0 | Graph loading, edge endpoint diagnostics, event model | Add richer event path modeling and import/export repair diagnostics. | +| Phase domain model | 2.5 | 4.0 | Phases, memory kinds, lifecycle states, actions | Add transition rules, approved apply behavior, path-aware state updates. | +| Profile execution planning | 2.5 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior | Add runtime orchestration, JSON snapshots, CLI outputs. | +| Lifecycle planning | 2.0 | 4.0 | Transition, retention, refresh, compaction dry-run plans | Add profile-driven rule evaluation and review-gated apply. | +| Activation planning | 2.0 | 5.0 | Budgeted selection and Markitect-compatible selection output | Add graph neighborhoods, event paths, ranking, metadata preservation, metrics. | +| Local persistence | 1.0 | 4.0 | In-memory adapters only | Add versioned file-backed graph store and JSONL event log. | +| Policy and audit | 1.5 | 5.0 | Policy/audit ports, allow-all gateway, recording sink, review flags | Add enforcement points, review records, redaction, audit schema. | +| Observability and diagnostics | 1.5 | 4.0 | Planner diagnostics and observability event names | Add audit/health envelopes and adapter status diagnostics. | +| Markitect interop | 1.5 | 4.0 | Compatible schema constants and selection handoff | Add package bridge envelopes, optional validation/compiler adapters. | +| Kontextual/Infospace interop | 1.0 | 4.0 | Boundaries documented and small derived fixtures | Add delegation envelope design and evaluation fixture reports. | +| Testing and evaluation | 2.0 | 4.0 | 13 deterministic tests over core planners/adapters | Add CLI snapshots, file-store round trips, policy denial, activation metrics. | +| Service readiness | 0.5 | 4.0 | Runtime ports exist | Add service contracts, config, health checks, adapter conformance tests. | +| Developer experience | 2.0 | 4.0 | README quick start and package map | Add CLI guide, local persistence guide, examples, troubleshooting. | + +## 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"] + + WP1 --> WP2 + WP2 --> WP3 + WP2 --> WP4 + WP2 --> WP5 + WP3 --> WP4 + WP5 --> WP6 + WP4 --> WP6 + WP3 --> WP7 + WP4 --> WP7 + WP5 --> WP7 + WP6 --> WP7 +``` + +## 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 diff --git a/workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md b/workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md new file mode 100644 index 0000000..7ca9b08 --- /dev/null +++ b/workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md @@ -0,0 +1,202 @@ +--- +id: PMEM-WP-0002 +type: workplan +title: "Local Runtime Facade And CLI" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: local-runtime +planning_priority: P1 +planning_order: 20 +related_workplans: + - PMEM-WP-0001 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "83dcb429-688d-473d-9973-63f6ac2acd5b" +--- + +# PMEM-WP-0002: Local Runtime Facade And CLI + +## Goal + +Turn the completed planning foundation into a usable local runtime entrypoint. + +The runtime should combine contract ingress, profile execution planning, +lifecycle planning, activation planning, local adapters, policy checks, and +audit recording behind one deterministic application surface. The first CLI +should make the package useful from a repository checkout without requiring a +service, external graph store, vector database, LLM, or enterprise policy +system. + +## Current Evidence + +PMEM-WP-0001 already provides: + +- Markitect-compatible profile and graph ingress. +- Profile execution plans. +- Dry-run lifecycle actions. +- Activation selection handoff. +- Runtime port protocols. +- In-memory adapters and deterministic tests. + +The missing layer is orchestration. Callers still need to manually wire modules +together and there is no command-line path for inspecting plans. + +## Non-Goals + +- Do not introduce durable writes as a default behavior. +- Do not make Markitect a hard runtime dependency. +- Do not start a long-lived HTTP service in this workplan. +- Do not add live LLM, vector, or graph database dependencies. + +## T01 - Add a local runtime facade + +```task +id: PMEM-WP-0002-T01 +status: todo +priority: high +state_hub_task_id: "456557a9-3ac3-483b-bbdd-5591224894b9" +``` + +Add a `PhaseMemoryRuntime` application service that wires together: + +- contract ingress +- profile execution planning +- lifecycle planning +- activation planning +- memory graph store +- event log +- context package compiler port +- policy gateway +- audit sink + +Output: a small public runtime API that keeps existing pure planner functions +usable, but gives integrations one obvious local entrypoint. + +## T02 - Define runtime input and output envelopes + +```task +id: PMEM-WP-0002-T02 +status: todo +priority: high +state_hub_task_id: "b04054cb-d743-4fcd-9b37-2685d1f9c00d" +``` + +Define stable dictionary envelopes for local runtime operations: + +- profile import result +- graph import result +- profile plan result +- lifecycle plan result +- activation plan result +- package compilation request and response +- audit receipt + +Output: deterministic JSON-serializable envelopes with diagnostics, operation +ids, dry-run flags, and source contract references. + +## T03 - Implement profile planning CLI + +```task +id: PMEM-WP-0002-T03 +status: todo +priority: high +state_hub_task_id: "8463924e-a6ce-43f1-b7fc-544a2aa7fd5f" +``` + +Add a dependency-light CLI entrypoint for: + +```bash +phase-memory profile plan tests/fixtures/memory-profile.json +``` + +The command should emit JSON by default and support a concise human-readable +summary mode. + +Output: CLI command, tests around success and diagnostics, and README usage. + +## T04 - Implement graph lifecycle CLI + +```task +id: PMEM-WP-0002-T04 +status: todo +priority: high +state_hub_task_id: "ab818835-5ef3-4a43-adf2-444ab712ead9" +``` + +Add a command for lifecycle planning over a graph fixture: + +```bash +phase-memory graph lifecycle tests/fixtures/memory-graph.json --stale-after-days 7 --delete-after-days 30 +``` + +The command should emit dry-run lifecycle actions only. It must not mutate +input files or local stores unless a later workplan adds explicit apply +behavior. + +Output: lifecycle command and fixture tests for stale, delete-requested, +refresh, and compaction proposals. + +## T05 - Implement activation CLI + +```task +id: PMEM-WP-0002-T05 +status: todo +priority: medium +state_hub_task_id: "9c8e8511-f00a-4685-91b5-a52c93d8461d" +``` + +Add a command for Markitect-compatible activation selection: + +```bash +phase-memory graph activate tests/fixtures/memory-graph.json --max-items 3 --max-tokens 60 +``` + +The command should emit the selection envelope and explain omitted nodes. + +Output: activation command, deterministic output tests, and README usage. + +## T06 - Add snapshot tests for CLI and runtime envelopes + +```task +id: PMEM-WP-0002-T06 +status: todo +priority: medium +state_hub_task_id: "a005aa31-053e-4b51-b3ea-3bebf24ac833" +``` + +Add small JSON snapshot fixtures for the main runtime outputs. Snapshot tests +should protect the public shape of the local interface without freezing +internal dataclass implementation details. + +Output: stable examples for downstream repos and future compatibility checks. + +## T07 - Update documentation for local usage + +```task +id: PMEM-WP-0002-T07 +status: todo +priority: medium +state_hub_task_id: "f6c6c6b2-141a-44da-a3d5-dbef95559049" +``` + +Update `README.md` and architecture docs with: + +- runtime facade role +- CLI quick start +- dry-run guarantees +- example plan outputs +- how adjacent repos should call the local API + +Output: a contributor can run the package and inspect a memory plan in under +five minutes. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- The package exposes a console script named `phase-memory`. +- Profile planning, graph lifecycle planning, and activation planning work from + the CLI against existing fixtures. +- Runtime outputs are deterministic and JSON-serializable. +- No default path mutates durable memory stores. diff --git a/workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md b/workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md new file mode 100644 index 0000000..4b0bcd1 --- /dev/null +++ b/workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md @@ -0,0 +1,188 @@ +--- +id: PMEM-WP-0003 +type: workplan +title: "File-Backed Stores And Event Path Runtime" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: local-persistence +planning_priority: P1 +planning_order: 30 +related_workplans: + - PMEM-WP-0002 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "c15d2f61-449b-48fa-9e4d-ea22a9b419b2" +--- + +# PMEM-WP-0003: File-Backed Stores And Event Path Runtime + +## Goal + +Add a local-first durable adapter layer that can persist profiles, graph +records, and append-only memory events without requiring external +infrastructure. + +This should move the project from deterministic in-memory tests to a useful +developer runtime while preserving the INTENT.md principle that durable writes +are explicit, inspectable, and policy-aware. + +## Current Evidence + +The repository has port protocols and in-memory adapters, but no file-backed +store, event replay, export, import, or durable local graph snapshot format. +The memory event model also exists, but conversational paths are not yet +first-class runtime objects. + +## Non-Goals + +- Do not choose a production graph database. +- Do not implement a generic vector database. +- Do not add hidden background compaction or deletion. +- Do not make file-backed storage the only adapter option. + +## T01 - Define local storage layout + +```task +id: PMEM-WP-0003-T01 +status: todo +priority: high +state_hub_task_id: "37d082c7-c019-4ecd-8655-94f8f27807ff" +``` + +Define a simple versioned local storage layout for: + +- profiles +- nodes +- edges +- events +- activation plans +- audit records +- runtime metadata + +Prefer JSON and JSONL formats for this slice unless a concrete requirement +forces SQLite. + +Output: documented storage layout, schema version fields, and fixture examples. + +## T02 - Implement a file-backed graph store + +```task +id: PMEM-WP-0003-T02 +status: todo +priority: high +state_hub_task_id: "c417f7ec-0423-4723-91c3-3b4681e30ec3" +``` + +Implement a deterministic adapter for the `MemoryGraphStore` protocol that can: + +- save and load profiles +- save and load nodes +- save and load edges +- list nodes by kind +- list edges by source or target +- export a Markitect-compatible graph envelope + +Output: adapter implementation and tests for round-trip behavior. + +## T03 - Implement a JSONL event log + +```task +id: PMEM-WP-0003-T03 +status: todo +priority: high +state_hub_task_id: "1d3b3ffb-fc9b-401f-a77f-cfad4a4f6b72" +``` + +Implement an append-only `MemoryEventLog` adapter with: + +- duplicate event id detection +- deterministic ordering +- kind filtering +- replay into graph snapshots where possible +- corruption diagnostics for malformed lines + +Output: event log adapter and tests for append, list, replay, and diagnostics. + +## T04 - Model conversational paths explicitly + +```task +id: PMEM-WP-0003-T04 +status: todo +priority: high +state_hub_task_id: "43d5863c-f2db-441e-8f3e-7e1843b6bc33" +``` + +Add first-slice path records for fluid memory: + +- path id +- parent path id +- event ids +- active branch marker +- merge marker +- abandoned branch reason +- compaction status + +Output: path model, path event helpers, and tests that show branch, merge, and +abandon flows without requiring transcript storage. + +## T05 - Add safe apply behavior behind review gates + +```task +id: PMEM-WP-0003-T05 +status: todo +priority: medium +state_hub_task_id: "e9079c0c-5834-47b2-b1dc-1d97604c96f8" +``` + +Add an optional runtime operation that applies approved lifecycle actions to a +file-backed store. The operation must reject actions that require review unless +the caller provides an explicit approval marker. + +Output: apply operation, approval checks, audit records, and tests that prove +unapproved durable actions are denied. + +## T06 - Add import, export, and repair diagnostics + +```task +id: PMEM-WP-0003-T06 +status: todo +priority: medium +state_hub_task_id: "a0597e3e-2f2d-4abf-8fc2-37c914e0ce34" +``` + +Add local tooling to: + +- import Markitect-compatible graph and profile fixtures +- export local state to a graph envelope +- report missing edge endpoints +- report orphaned events +- report unknown schema versions + +Output: CLI/runtime helpers and tests for useful diagnostics. + +## T07 - Update docs with local persistence examples + +```task +id: PMEM-WP-0003-T07 +status: todo +priority: medium +state_hub_task_id: "60b3bce7-3e73-427b-95d7-d68283503a3c" +``` + +Document how to create a local memory workspace, import a profile and graph, +append events, inspect paths, and export a graph. + +Output: local persistence guide and README pointers. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- File-backed adapters satisfy the same public protocols as in-memory adapters. +- A local workspace can be created, inspected, exported, and replayed + deterministically. +- Review-required actions cannot be applied without an explicit approval + marker. +- Conversational path branches and merges are represented as structured memory + events, not only as transcript text. diff --git a/workplans/PMEM-WP-0004-policy-audit-and-review-gates.md b/workplans/PMEM-WP-0004-policy-audit-and-review-gates.md new file mode 100644 index 0000000..ef45a96 --- /dev/null +++ b/workplans/PMEM-WP-0004-policy-audit-and-review-gates.md @@ -0,0 +1,204 @@ +--- +id: PMEM-WP-0004 +type: workplan +title: "Policy, Audit, And Review Gates" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: policy-audit +planning_priority: P1 +planning_order: 40 +related_workplans: + - PMEM-WP-0002 + - PMEM-WP-0003 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "e8d405a3-3ddd-4353-81a2-518850033b8e" +--- + +# PMEM-WP-0004: Policy, Audit, And Review Gates + +## Goal + +Make policy-aware memory behavior concrete enough that phase-memory can safely +plan and apply memory lifecycle changes. + +The project intent calls for provenance, confidence, freshness, policy +metadata, reauthorization, audit, redaction, and trust-zone boundaries. The +current implementation surfaces policy gates, but it does not yet enforce +review gates beyond planner metadata. + +## Current Evidence + +Current code includes: + +- `PolicyDecision` +- `PolicyGateway` protocol +- `AuditSink` protocol +- `AllowAllPolicyGateway` +- `RecordingAuditSink` +- policy gate strings in profile execution plans +- review-required flags on stabilization, compaction, refresh, and deletion + proposals + +The next step is an explicit authorization and audit workflow for reads, +activations, writes, compactions, and phase transitions. + +## Non-Goals + +- Do not build a full identity platform. +- Do not implement enterprise authorization policy languages. +- Do not make `flex-auth` a hard dependency. +- Do not store or expose secrets in test fixtures. + +## T01 - Define memory operation policy points + +```task +id: PMEM-WP-0004-T01 +status: todo +priority: high +state_hub_task_id: "1231b7bf-b23c-498d-a9d6-a6ee307aa3d4" +``` + +Define the canonical policy check points for: + +- profile import +- graph import +- node read +- event read +- activation +- stabilization +- compaction +- refresh +- delete request +- archive +- export + +Output: operation vocabulary and tests that runtime operations call policy at +the right boundary. + +## T02 - Add review authorization records + +```task +id: PMEM-WP-0004-T02 +status: todo +priority: high +state_hub_task_id: "b989d43c-eb25-4663-afd1-a54673ad565a" +``` + +Add structured review records for actions that move memory into stabilized or +rigid states, compact source records, refresh source-backed facts, or request +deletion. + +Records should capture: + +- reviewer id or local reviewer label +- reviewed action id +- approval or rejection +- timestamp +- reason +- policy obligations +- source digests + +Output: review record model and approval checks in the runtime facade. + +## T03 - Enforce durable write gates + +```task +id: PMEM-WP-0004-T03 +status: todo +priority: high +state_hub_task_id: "6b677c18-7135-4d54-9e46-5116645d2ebe" +``` + +Make durable write operations fail closed when profile policy declares +review-gated durable writes. + +Output: runtime tests proving that stabilization, rigid updates, compaction, +and deletion requests cannot be applied silently. + +## T04 - Add activation policy checks + +```task +id: PMEM-WP-0004-T04 +status: todo +priority: high +state_hub_task_id: "6f07087b-e6e2-469a-9bce-71bfd21cb633" +``` + +Before memory nodes or events are included in activation packages, check: + +- required labels +- denied labels +- trust zone compatibility +- secrets allowance +- reauthorization requirements +- source freshness requirements + +Output: activation planner/runtime policy tests and omitted-item diagnostics +for policy-denied records. + +## T05 - Add audit event schema + +```task +id: PMEM-WP-0004-T05 +status: todo +priority: medium +state_hub_task_id: "bb6461a8-9181-4b88-a152-334668b22208" +``` + +Define a stable audit event envelope for memory operations: + +- operation id +- operation kind +- subject id +- profile id +- graph id +- policy decision +- dry-run flag +- planned action id +- actor label +- timestamp +- source contract references + +Output: audit schema helpers and tests for profile, lifecycle, activation, and +apply operations. + +## T06 - Add redaction and denial diagnostics + +```task +id: PMEM-WP-0004-T06 +status: todo +priority: medium +state_hub_task_id: "dcdec3af-d20f-43ba-b12e-6febc4347d38" +``` + +Add deterministic redaction behavior for denied fields and policy-sensitive +metadata. Redaction should be visible in diagnostics and audit events. + +Output: redaction utility, denied activation examples, and regression tests. + +## T07 - Document policy and audit guarantees + +```task +id: PMEM-WP-0004-T07 +status: todo +priority: medium +state_hub_task_id: "c4e0bdff-5047-4fe5-ab86-e422d4b1a17e" +``` + +Document what the local runtime guarantees and what remains delegated to +external policy infrastructure. + +Output: policy architecture note with examples of allowed, denied, and +review-required operations. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- Every apply-capable operation has policy and audit coverage. +- Activation explains policy-denied and redacted items. +- Review-required actions fail closed without an explicit review record. +- The policy layer remains adapter-based and does not become an identity + platform. diff --git a/workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md b/workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md new file mode 100644 index 0000000..f3b9668 --- /dev/null +++ b/workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md @@ -0,0 +1,184 @@ +--- +id: PMEM-WP-0005 +type: workplan +title: "Markitect Package Bridge And Contract Interop" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: markitect-interop +planning_priority: P1 +planning_order: 50 +related_workplans: + - PMEM-WP-0002 + - PMEM-WP-0004 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "be683a3e-49d1-4e35-a227-c43233cc652e" +--- + +# PMEM-WP-0005: Markitect Package Bridge And Contract Interop + +## Goal + +Make the boundary with `markitect-tool` operational while preserving clean +ownership. + +`phase-memory` should consume Markitect-compatible profiles, graphs, events, +and selections; plan memory operations; and hand activation selections to a +Markitect-owned context-package compiler. It should not fork Markitect syntax +or quietly depend on Markitect internals. + +## Current Evidence + +The repository currently has: + +- constants for Markitect memory profile, graph, and selection schema versions +- profile and graph ingress helpers +- a selection output from activation planning +- a `ContextPackageCompiler` protocol +- a noop compiler adapter for tests + +The missing work is a real bridge contract, compatibility fixtures, validation +delegation, and stable package request/response envelopes. + +## Non-Goals + +- Do not reimplement Markitect schema validation. +- Do not own context package internals. +- Do not require Markitect installation for the default test suite. +- Do not turn Markitect into a hidden import dependency. + +## T01 - Define compiler bridge envelopes + +```task +id: PMEM-WP-0005-T01 +status: todo +priority: high +state_hub_task_id: "e51c4804-4938-443b-b02f-afa7bac0b846" +``` + +Define the request and response shape for context package compilation: + +- selection id +- graph id +- profile id +- selected nodes +- selected events +- budget metadata +- policy metadata +- provenance metadata +- compiler diagnostics +- package reference + +Output: typed helpers and JSON fixtures for package requests and responses. + +## T02 - Add Markitect validation adapter boundary + +```task +id: PMEM-WP-0005-T02 +status: todo +priority: high +state_hub_task_id: "5a1a8777-b971-4f1b-bf65-bd71918eabf6" +``` + +Add an adapter boundary that can delegate validation to Markitect when +available, while still accepting already-valid dictionaries in dependency-light +mode. + +Output: protocol, noop/local validation adapter, optional Markitect-backed +adapter design, and tests around fallback behavior. + +## T03 - Preserve provenance and source spans through activation + +```task +id: PMEM-WP-0005-T03 +status: todo +priority: high +state_hub_task_id: "012210c6-fc05-467e-9d36-7358c0e11abd" +``` + +Ensure activation selections carry enough information for Markitect to compile +inspectable packages: + +- source spans +- provenance +- confidence +- freshness +- namespace +- policy labels +- reason selected + +Output: expanded selection metadata and tests proving metadata survives ingress +to package request. + +## T04 - Add interop fixture catalog + +```task +id: PMEM-WP-0005-T04 +status: todo +priority: medium +state_hub_task_id: "90ebf80e-1f7e-422c-879c-f4270f1e232e" +``` + +Create a fixture catalog that mirrors the Markitect contract shapes this repo +expects, including: + +- valid profile +- invalid profile +- valid graph +- invalid graph +- activation selection +- package request +- package response + +Output: fixtures and docs that downstream repos can use as compatibility +examples. + +## T05 - Add contract compatibility tests + +```task +id: PMEM-WP-0005-T05 +status: todo +priority: medium +state_hub_task_id: "95b07795-6d8c-4473-a98a-5e48a3e6cca9" +``` + +Add tests that prove phase-memory can: + +- accept Markitect profile and graph fixtures +- report diagnostics without claiming schema ownership +- emit Markitect-compatible selections +- build package requests through the compiler port +- consume package responses without understanding internals + +Output: compatibility test suite. + +## T06 - Document the Markitect boundary + +```task +id: PMEM-WP-0005-T06 +status: todo +priority: medium +state_hub_task_id: "21e4ffb5-e8dc-4b32-9008-97fb6ffb3726" +``` + +Update architecture docs with a concrete boundary contract: + +- what Markitect owns +- what phase-memory owns +- which data moves across the boundary +- which diagnostics stay local +- how optional Markitect integration is configured + +Output: interop architecture note. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- Activation package bridge envelopes are stable and documented. +- The default test suite does not require Markitect to be installed. +- Optional Markitect validation or compilation can be added without changing + the core planner APIs. +- Source spans, provenance, freshness, confidence, and policy metadata survive + from graph ingress to package request. diff --git a/workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md b/workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md new file mode 100644 index 0000000..809c45e --- /dev/null +++ b/workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md @@ -0,0 +1,189 @@ +--- +id: PMEM-WP-0006 +type: workplan +title: "Retrieval, Activation Quality, And Evaluation" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: activation-quality +planning_priority: P2 +planning_order: 60 +related_workplans: + - PMEM-WP-0002 + - PMEM-WP-0005 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "68417e46-d0a4-4168-bdd6-9ba6ac7847c1" +--- + +# PMEM-WP-0006: Retrieval, Activation Quality, And Evaluation + +## Goal + +Move activation planning beyond deterministic id ordering into explainable, +policy-aware memory retrieval and evaluation. + +INTENT.md expects activation memory to compile graph neighborhoods, decision +paths, conversation episodes, and knowledge slices into bounded context +packages. The current activation planner selects nodes under item and token +budgets, but it does not yet model graph neighborhoods, event paths, freshness, +confidence, or retrieval quality. + +## Current Evidence + +Current activation behavior: + +- prioritizes explicitly requested node ids +- sorts remaining nodes by id +- estimates tokens with word count +- includes events only when they reference packages or activations +- emits Markitect-compatible selection dictionaries +- explains budget omissions + +This is enough for a first handoff, but not enough to satisfy the full +activation-memory intent. + +## Non-Goals + +- Do not require embeddings or vector stores in the default path. +- Do not use live LLM ranking in deterministic tests. +- Do not own benchmark dashboards that belong in `infospace-bench`. +- Do not optimize for a single application domain. + +## T01 - Add deterministic graph-neighborhood retrieval + +```task +id: PMEM-WP-0006-T01 +status: todo +priority: high +state_hub_task_id: "8ed0909f-9e8e-4d49-9312-dca267df29f5" +``` + +Add selection strategies that can expand from seed nodes across graph edges: + +- one-hop neighbors +- bounded multi-hop neighbors +- edge-kind filters +- source and target direction filters +- phase filters +- memory kind filters + +Output: retrieval planner and tests for stable graph-neighborhood selection. + +## T02 - Add event-path activation + +```task +id: PMEM-WP-0006-T02 +status: todo +priority: high +state_hub_task_id: "5d48ba91-fef0-4d4f-a560-836abed1c527" +``` + +Select conversational path episodes and event windows as first-class +activation inputs. + +Output: event-path selection support, path budget behavior, and tests around +active, abandoned, and merged paths. + +## T03 - Add ranking signals and explanations + +```task +id: PMEM-WP-0006-T03 +status: todo +priority: high +state_hub_task_id: "0f6340ef-f7bd-408b-b98e-6d90188c5969" +``` + +Rank activation candidates using deterministic local signals: + +- explicit priority +- graph distance from seed +- lifecycle state +- phase +- freshness +- confidence +- policy allowance +- source-backed status +- prior activation references + +Output: scoring model, per-item selection reason, and omitted-item reason. + +## T04 - Improve token and budget accounting + +```task +id: PMEM-WP-0006-T04 +status: todo +priority: medium +state_hub_task_id: "12d83382-a767-45a8-b7cc-8c3f6f3f4c37" +``` + +Replace rough word-count behavior with a pluggable budget estimator that can +stay deterministic locally and later delegate to provider-specific tokenizers. + +Output: estimator protocol, default estimator, and tests for node, event, and +package budget pressure. + +## T05 - Add evaluation fixture scenarios + +```task +id: PMEM-WP-0006-T05 +status: todo +priority: medium +state_hub_task_id: "509e9417-3aa7-4899-aed5-20749372fe00" +``` + +Add small evaluation fixtures inspired by adjacent `infospace-bench` pilots: + +- restart package +- decision recall +- stale source refresh +- policy-denied activation +- compacted trace window +- conflicting preference update + +Output: fixture set and expected activation plans. + +## T06 - Add maturity metrics for activation quality + +```task +id: PMEM-WP-0006-T06 +status: todo +priority: medium +state_hub_task_id: "477a896a-8013-42a5-b965-b1ccd2577fec" +``` + +Define local metrics that can be exported to `infospace-bench` later: + +- selected expected nodes +- omitted required nodes +- policy-denied required nodes +- token budget utilization +- stale item activation count +- provenance coverage +- source span coverage +- explanation coverage + +Output: metrics helper and JSON report fixture. + +## T07 - Document retrieval and evaluation behavior + +```task +id: PMEM-WP-0006-T07 +status: todo +priority: medium +state_hub_task_id: "551432e4-2551-49fa-b17b-f762853a6a50" +``` + +Document activation strategy, scoring inputs, limitations, and evaluation +fixtures. + +Output: activation planning guide and scorecard update. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- Activation can select graph neighborhoods and event paths under budget. +- Every selected and omitted item has a machine-readable reason. +- Evaluation fixtures produce deterministic activation quality reports. +- Optional semantic indexes remain behind the `SemanticIndex` port. diff --git a/workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md b/workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md new file mode 100644 index 0000000..64fd8ec --- /dev/null +++ b/workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md @@ -0,0 +1,195 @@ +--- +id: PMEM-WP-0007 +type: workplan +title: "Service Readiness And External Adapters" +domain: markitect +repo: phase-memory +status: proposed +owner: phase-memory +topic_slug: service-readiness +planning_priority: P2 +planning_order: 70 +related_workplans: + - PMEM-WP-0003 + - PMEM-WP-0004 + - PMEM-WP-0005 + - PMEM-WP-0006 +created: "2026-05-18" +updated: "2026-05-18" +state_hub_workstream_id: "35512fad-8a37-406d-9074-6b6891a5a83a" +--- + +# PMEM-WP-0007: Service Readiness And External Adapters + +## Goal + +Prepare phase-memory to run as an embedded runtime or service-backed adapter +layer once the local runtime, persistence, policy, package bridge, and +activation quality slices are stable. + +INTENT.md says the project should run standalone, embedded behind a local +agent toolchain, as a service with durable stores, and as an adapter layer over +existing systems. This workplan is the transition from local library to +integration-ready runtime. + +## Current Evidence + +The repository currently defines ports for graph stores, event logs, context +package compilers, semantic indexes, policy gateways, audit sinks, and runtime +registries. It does not yet define service API contracts, adapter conformance +tests, runtime configuration, health checks, or deployment guidance. + +## Non-Goals + +- Do not make the service path mandatory for local use. +- Do not choose one production graph, vector, policy, or audit provider as the + only supported backend. +- Do not move durable knowledge ownership out of `kontextual-engine`. +- Do not add operational complexity before PMEM-WP-0002 through PMEM-WP-0006 + stabilize. + +## T01 - Define runtime service API contracts + +```task +id: PMEM-WP-0007-T01 +status: todo +priority: high +state_hub_task_id: "48dc8e83-ff0f-4c25-b1c9-d94c3a2ac0eb" +``` + +Define service-level request and response contracts for: + +- profile plan +- graph import +- lifecycle plan +- lifecycle apply +- activation plan +- package compile handoff +- audit query +- health check + +Output: API contract docs and fixture request/response envelopes. + +## T02 - Add adapter conformance tests + +```task +id: PMEM-WP-0007-T02 +status: todo +priority: high +state_hub_task_id: "da22d548-3123-46fc-acac-8bbcf8b54fb7" +``` + +Create conformance tests for all public adapter protocols: + +- graph store +- event log +- context package compiler +- semantic index +- policy gateway +- audit sink +- runtime registry + +Output: reusable test helpers that any external adapter must pass. + +## T03 - Add Kontextual delegation adapter design + +```task +id: PMEM-WP-0007-T03 +status: todo +priority: high +state_hub_task_id: "2a0fc3d0-3dda-4c58-95de-3f70cf097ff1" +``` + +Define the first external delegation boundary for `kontextual-engine`: + +- what phase-memory asks Kontextual to persist or retrieve +- what Kontextual delegates back to phase-memory for phase policy +- how audit and policy decisions are exchanged +- how circular imports are avoided + +Output: adapter design note, envelope fixtures, and local fake adapter tests. + +## T04 - Add optional service runner + +```task +id: PMEM-WP-0007-T04 +status: todo +priority: medium +state_hub_task_id: "10934c46-db81-4a68-be4f-2ce95408d279" +``` + +Add an optional service runner only after the local runtime API is stable. +Keep dependencies optional and the default test suite dependency-light. + +Output: minimal service module, health endpoint, deterministic tests, and +clear installation extras if a framework is used. + +## T05 - Add runtime configuration model + +```task +id: PMEM-WP-0007-T05 +status: todo +priority: medium +state_hub_task_id: "a7129077-b736-4d69-94ab-d6921cd8ed15" +``` + +Define configuration for: + +- local store path +- adapter registry +- policy mode +- audit sink mode +- package compiler mode +- semantic index mode +- dry-run default +- trust-zone labels + +Output: config model, default local config, and validation diagnostics. + +## T06 - Add observability and health diagnostics + +```task +id: PMEM-WP-0007-T06 +status: todo +priority: medium +state_hub_task_id: "24ef8feb-90f8-454d-8c8f-7b3468454f57" +``` + +Expose runtime diagnostics for: + +- adapter availability +- store schema version +- pending review actions +- stale memory counts +- activation budget pressure +- audit sink status +- package compiler status + +Output: health report helpers and tests. + +## T07 - Document deployment modes + +```task +id: PMEM-WP-0007-T07 +status: todo +priority: medium +state_hub_task_id: "89c8802c-f536-441b-a514-8d3e56b3c6e5" +``` + +Document the supported deployment modes: + +- pure library +- CLI over local files +- embedded runtime +- optional service +- adapter layer over external stores + +Output: service-readiness guide and scorecard update. + +## Acceptance Criteria + +- `python3 -m pytest` passes. +- Service contracts are documented before service implementation expands. +- External adapters can be validated with reusable conformance tests. +- Local library and CLI use remain first-class. +- The Kontextual delegation boundary is explicit and avoids ownership drift.