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