phase-memory/docs/architecture.md

# 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.

## Local Runtime Facade

The second implementation slice adds a local facade, `PhaseMemoryRuntime`, over
the deterministic core. The facade is not a service runner. It is the small
application surface that adjacent tools can call before a service deployment
exists.

Runtime operations currently include:

- profile import
- graph import
- profile execution planning
- graph lifecycle planning
- graph activation planning
- package compilation handoff through `ContextPackageCompiler`

Each operation returns a JSON-serializable envelope with:

- `schema_version`
- `operation_id`
- `operation`
- `dry_run`
- `valid`
- `subject`
- `source`
- `policy_decision`
- `audit_receipt`
- `diagnostics`
- `data`

The local CLI exposes the same facade for fixtures and developer workflows:

```bash
phase-memory profile plan profile.json
phase-memory graph lifecycle graph.json --stale-after-days 7 --delete-after-days 30
phase-memory graph activate graph.json --max-items 3 --max-tokens 60
```

The default implementation uses in-memory stores, an allow-all local policy
gateway, a recording audit sink, and a noop context-package compiler. These are
test and integration adapters, not a claim that durable persistence, policy, or
package internals belong in this repository.

## 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?