generated from coulomb/repo-seed
Add phase-memory architecture workplan
This commit is contained in:
157
docs/architecture.md
Normal file
157
docs/architecture.md
Normal file
@@ -0,0 +1,157 @@
|
|||||||
|
# Phase Memory Architecture Sketch
|
||||||
|
|
||||||
|
Date: 2026-05-18
|
||||||
|
Status: initial sketch
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
`phase-memory` should be the memory operating layer between Markitect's
|
||||||
|
contract compiler, Kontextual Engine's durable knowledge runtime, and
|
||||||
|
Infospace Bench's evaluation fixtures.
|
||||||
|
|
||||||
|
The adjacent repositories already cover important slices:
|
||||||
|
|
||||||
|
- `markitect-tool` owns deterministic memory profile, graph, event, and
|
||||||
|
selection contracts, plus compilation of selected graph items into context
|
||||||
|
packages.
|
||||||
|
- `kontextual-engine` owns durable knowledge and memory graph records,
|
||||||
|
permission-aware retrieval, audit events, retention, refresh, compaction,
|
||||||
|
review-gated updates, and Markitect-compatible export envelopes.
|
||||||
|
- `infospace-bench` owns concrete corpus pilots, restart-package evaluation,
|
||||||
|
metrics, and fixture feedback.
|
||||||
|
|
||||||
|
The missing layer is memory-native orchestration: interpreting profile intent
|
||||||
|
as phase-aware runtime plans, deciding which lifecycle actions are allowed or
|
||||||
|
required, planning activation packages, and coordinating adapter behavior
|
||||||
|
without becoming a markdown contract library, knowledge database, or benchmark.
|
||||||
|
|
||||||
|
## Architecture Layers
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
MT["markitect-tool\ncontracts + package compiler"]
|
||||||
|
PM["phase-memory\nprofile execution + phase policy"]
|
||||||
|
KE["kontextual-engine\ndurable graph/runtime records"]
|
||||||
|
IB["infospace-bench\nfixtures + evaluation"]
|
||||||
|
EXT["optional adapters\ngraph, vector, policy, audit, registry"]
|
||||||
|
|
||||||
|
MT -->|"profile, graph, selection contracts"| PM
|
||||||
|
PM -->|"runtime plan, lifecycle actions"| KE
|
||||||
|
KE -->|"graph records, audit traces, context inputs"| PM
|
||||||
|
PM -->|"selection/package request"| MT
|
||||||
|
IB -->|"profile + graph fixtures, metrics"| PM
|
||||||
|
PM -->|"planned retrieval/evaluation envelopes"| IB
|
||||||
|
PM -->|"adapter calls"| EXT
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1. Contract Ingress
|
||||||
|
|
||||||
|
Accept Markitect-compatible memory profiles, graph snapshots, events, and
|
||||||
|
selections as input contracts. `phase-memory` may call Markitect validators, but
|
||||||
|
it should not fork the Markitect vocabulary or become the syntax owner.
|
||||||
|
|
||||||
|
Primary input contracts:
|
||||||
|
|
||||||
|
- `markitect.memory.profile.v1`
|
||||||
|
- `markitect.memory.graph.v1`
|
||||||
|
- `markitect.memory.selection.v1`
|
||||||
|
|
||||||
|
### 2. Phase Domain Model
|
||||||
|
|
||||||
|
Introduce a memory-native model that explains what a profile means at runtime:
|
||||||
|
|
||||||
|
- phases: `ephemeral`, `fluid`, `stabilized`, `rigid`
|
||||||
|
- memory kinds: `reasoning`, `conversation`, `knowledge`, `package`,
|
||||||
|
`identity`, `preference`, `source`, `task`, `tool`
|
||||||
|
- lifecycle states: active, stale, review-needed, compacted, superseded,
|
||||||
|
delete-requested, archived
|
||||||
|
- profile intent: limits, latency, retention, deletion, decay, refresh,
|
||||||
|
compaction, merge/conflict policy, activation, failure behavior, and policy
|
||||||
|
reauthorization
|
||||||
|
- action plans: deterministic dry-run records that explain proposed writes,
|
||||||
|
reads, activations, compactions, and denials
|
||||||
|
|
||||||
|
### 3. Planning Engines
|
||||||
|
|
||||||
|
The first useful implementation should be deterministic and local-first.
|
||||||
|
|
||||||
|
Core planners:
|
||||||
|
|
||||||
|
- Profile execution planner: turns a profile into a runtime capability and
|
||||||
|
adapter plan.
|
||||||
|
- Phase transition planner: decides which records can move from ephemeral or
|
||||||
|
fluid memory into stabilized or rigid memory.
|
||||||
|
- Retention planner: proposes stale, delete-requested, archived, or refresh
|
||||||
|
actions without physical deletion by default.
|
||||||
|
- Compaction planner: groups trace windows or graph neighborhoods into
|
||||||
|
reviewable summary-node proposals.
|
||||||
|
- Activation planner: turns graph neighborhoods and event paths into
|
||||||
|
Markitect-compatible selections under token/item budgets.
|
||||||
|
- Policy planner: surfaces required reauthorization, labels, trust zones, and
|
||||||
|
review gates before a runtime applies durable writes.
|
||||||
|
|
||||||
|
### 4. Runtime Ports
|
||||||
|
|
||||||
|
`phase-memory` should define ports before committing to infrastructure:
|
||||||
|
|
||||||
|
- `MemoryGraphStore`: graph node, edge, event, and profile access
|
||||||
|
- `MemoryEventLog`: append-only fluid/conversational path events
|
||||||
|
- `ContextPackageCompiler`: Markitect-backed package compilation boundary
|
||||||
|
- `SemanticIndex`: optional vector or hybrid retrieval
|
||||||
|
- `PolicyGateway`: read/write/activation authorization
|
||||||
|
- `AuditSink`: durable operation and policy-decision recording
|
||||||
|
- `RuntimeRegistry`: remote or sibling runtime envelope exchange
|
||||||
|
|
||||||
|
Local in-memory or file-backed adapters are enough for the first slice. External
|
||||||
|
graph databases, vector stores, LLM extraction, enterprise policy systems, and
|
||||||
|
remote registries should remain optional adapters.
|
||||||
|
|
||||||
|
## Repository Boundaries
|
||||||
|
|
||||||
|
`phase-memory` owns:
|
||||||
|
|
||||||
|
- phase semantics and lifecycle policy
|
||||||
|
- profile execution planning
|
||||||
|
- retention, deletion, decay, refresh, compaction, and stabilization decisions
|
||||||
|
- activation planning and adapter orchestration
|
||||||
|
- memory-specific audit and observability envelopes
|
||||||
|
- deterministic local runtime behavior for tests and small deployments
|
||||||
|
|
||||||
|
`phase-memory` does not own:
|
||||||
|
|
||||||
|
- Markitect syntax vocabulary or context package internals
|
||||||
|
- generic content/knowledge artifact persistence
|
||||||
|
- benchmark corpus ownership or evaluation dashboards
|
||||||
|
- full identity or authorization platforms
|
||||||
|
- generic vector database behavior
|
||||||
|
- provider-specific LLM memory plugins
|
||||||
|
|
||||||
|
## First Viable Slice
|
||||||
|
|
||||||
|
The first implementation should establish a small package with:
|
||||||
|
|
||||||
|
1. Python project scaffold and tests.
|
||||||
|
2. Domain dataclasses for phases, profile intent, lifecycle actions, and
|
||||||
|
runtime plans.
|
||||||
|
3. A Markitect contract adapter that accepts already-valid profile/graph
|
||||||
|
dictionaries and reports diagnostics without redefining schemas.
|
||||||
|
4. A deterministic profile execution planner.
|
||||||
|
5. A local in-memory store/event-log adapter for tests.
|
||||||
|
6. A fixture set derived from Markitect examples and the Infospace Bench
|
||||||
|
agentic-memory pilot.
|
||||||
|
7. Docs that keep the Markitect, Kontextual, Infospace, and Phase Memory
|
||||||
|
boundaries explicit.
|
||||||
|
|
||||||
|
The slice should emit plans first, not mutate durable memory by surprise.
|
||||||
|
Durable writes, external adapters, live LLM extraction, vector retrieval, and
|
||||||
|
service deployment can follow once the plan model is stable.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
- Should `phase-memory` depend directly on `markitect-tool` for validation, or
|
||||||
|
shell out/consume JSON diagnostics to keep the boundary looser?
|
||||||
|
- Should the first local store be pure in-memory, JSONL/file-backed, or SQLite?
|
||||||
|
- Which actions belong in a stable public API first: activation planning,
|
||||||
|
retention planning, compaction planning, or profile capability inspection?
|
||||||
|
- How should `kontextual-engine` delegate phase-specific decisions without
|
||||||
|
creating circular imports?
|
||||||
247
workplans/PMEM-WP-0001-architecture-and-foundation.md
Normal file
247
workplans/PMEM-WP-0001-architecture-and-foundation.md
Normal file
@@ -0,0 +1,247 @@
|
|||||||
|
---
|
||||||
|
id: PMEM-WP-0001
|
||||||
|
type: workplan
|
||||||
|
title: "Phase Memory Architecture And Foundation"
|
||||||
|
domain: markitect
|
||||||
|
repo: phase-memory
|
||||||
|
status: active
|
||||||
|
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.
|
||||||
|
|
||||||
|
## T01 - Establish repository foundation
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: PMEM-WP-0001-T01
|
||||||
|
status: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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: todo
|
||||||
|
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.
|
||||||
Reference in New Issue
Block a user