phase-memory/README.md

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

python3 -m pytest

The default test suite uses only deterministic local fixtures.

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

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:

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 for the first architecture sketch, docs/local-persistence.md for the local file-backed adapter, docs/policy-audit.md for local policy and review gates, docs/markitect-interop.md for package bridge boundaries, docs/activation-quality.md for retrieval and evaluation behavior, docs/service-readiness.md for service and adapter contracts, docs/lifecycle-rules.md for profile-driven lifecycle rules, docs/external-adapter-packs.md for fake external integration packs, docs/maturity-scorecard.md for the current maturity assessment, and SCOPE.md for repository boundaries.