Implement phase-memory foundation

README.md

@@ -1,3 +1,50 @@
-# repo-seed
+# phase-memory
 
-A git repository template to bootstrap coulomb projects from.
+`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.