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

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:

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?