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

From a checkout, run the CLI through the local source tree:

```bash
PYTHONPATH=src python3 -m phase_memory.cli profile plan tests/fixtures/memory-profile.json
PYTHONPATH=src python3 -m phase_memory.cli graph lifecycle tests/fixtures/memory-graph.json --stale-after-days 7 --delete-after-days 30
PYTHONPATH=src python3 -m phase_memory.cli graph lifecycle tests/fixtures/memory-graph.json --profile tests/fixtures/memory-profile.json
PYTHONPATH=src python3 -m phase_memory.cli graph activate tests/fixtures/memory-graph.json --max-items 3 --max-tokens 60
PYTHONPATH=src python3 -m phase_memory.cli store import --store .phase-memory-local --profile tests/fixtures/memory-profile.json --graph tests/fixtures/memory-graph.json
```

When installed, the package exposes the same commands as `phase-memory`.
Commands emit JSON runtime envelopes by default and accept `--format summary`
for a concise human-readable view. All current commands are dry-run planning
operations; they do not mutate durable memory stores.

## Local Runtime

`PhaseMemoryRuntime` is the dependency-light application facade for local
integrations. It coordinates contract ingress, profile planning, lifecycle
planning, activation planning, the context-package compiler port, policy
checks, and audit recording.

Example:

```python
import json
from phase_memory import PhaseMemoryRuntime

runtime = PhaseMemoryRuntime()
profile = json.load(open("tests/fixtures/memory-profile.json", encoding="utf-8"))
envelope = runtime.plan_profile(profile, source_ref="tests/fixtures/memory-profile.json")
```

Runtime outputs use stable JSON-serializable envelopes with operation ids,
diagnostics, policy decisions, audit receipts, dry-run flags, and source
references. Activation planning also includes a Markitect-compatible selection
and a package compilation request for the `ContextPackageCompiler` boundary.

## 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 and profile-driven lifecycle planning.
- `phase_memory.activation`: Markitect-compatible activation selection planning.
- `phase_memory.ports`: runtime port protocols.
- `phase_memory.adapters`: deterministic in-memory test adapters.
- `phase_memory.external_adapters`: deterministic fake external adapter packs.
- `phase_memory.runtime`: local runtime facade and stable operation envelopes.
- `phase_memory.cli`: dependency-light command-line interface.

See [docs/architecture.md](docs/architecture.md) for the first architecture
sketch, [docs/local-persistence.md](docs/local-persistence.md) for the local
file-backed adapter, [docs/policy-audit.md](docs/policy-audit.md) for local
policy and review gates, [docs/markitect-interop.md](docs/markitect-interop.md)
for package bridge boundaries, [docs/activation-quality.md](docs/activation-quality.md)
for retrieval and evaluation behavior, [docs/service-readiness.md](docs/service-readiness.md)
for service and adapter contracts, [docs/lifecycle-rules.md](docs/lifecycle-rules.md)
for profile-driven lifecycle rules, [docs/external-adapter-packs.md](docs/external-adapter-packs.md)
for fake external integration packs, [docs/operational-readiness.md](docs/operational-readiness.md)
for the local end-to-end operational recipe, [docs/operator-readiness-runbook.md](docs/operator-readiness-runbook.md)
for operator readiness, [docs/api-compatibility.md](docs/api-compatibility.md)
for public API compatibility expectations, [docs/maturity-scorecard.md](docs/maturity-scorecard.md)
for the current maturity assessment, and [SCOPE.md](SCOPE.md) for repository boundaries.