generated from coulomb/repo-seed
103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
# 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.
|