# phase-memory

`phase-memory` is the profile-driven memory operating layer for agentic
systems. It interprets Markitect memory profiles as runtime plans, models
memory phases, and produces deterministic dry-run actions for retention,
refresh, compaction, stabilization, and activation.

The first implementation slice is local-first and dependency-light. It does not
launch a service or mutate durable memory stores by default.

## Repository Role

Adjacent repositories own nearby but separate concerns:

- `markitect-tool`: memory profile, graph, event, and selection contracts plus
  context-package compilation.
- `kontextual-engine`: durable knowledge/runtime records, permission-aware
  retrieval, audit records, and long-lived storage.
- `infospace-bench`: concrete pilots, restart-package evaluation, metrics, and
  fixture feedback.

`phase-memory` owns the orchestration layer between them:

- phase semantics: ephemeral, fluid, stabilized, rigid
- profile execution planning
- retention, deletion, refresh, compaction, and stabilization decisions
- activation planning under token and item budgets
- adapter, policy, audit, and observability boundaries

## Quick Start

```bash
python3 -m pytest
```

The default test suite uses only deterministic local fixtures.

## Package Map

- `phase_memory.models`: domain records, phases, lifecycle states, diagnostics,
  and plan envelopes.
- `phase_memory.contracts`: Markitect-compatible profile/graph ingress.
- `phase_memory.planner`: profile execution planning.
- `phase_memory.lifecycle`: dry-run lifecycle planning.
- `phase_memory.activation`: Markitect-compatible activation selection planning.
- `phase_memory.ports`: runtime port protocols.
- `phase_memory.adapters`: deterministic in-memory test adapters.

See [docs/architecture.md](docs/architecture.md) for the first architecture
sketch and [SCOPE.md](SCOPE.md) for repository boundaries.