# Phase Memory Boundary

Date: 2026-05-05

This note defines how `kontextual-engine` should relate to the sibling
`phase-memory` project while closing the current persistence gap.

## Source Scope

`phase-memory` exists to provide profile-driven memory infrastructure for
agentic systems. Its intent covers memory phases, memory graphs, event paths,
stores, compaction, retention, service profiles, activation planning, and
adapters for advanced memory backends.

`kontextual-engine` exists to provide an AI-first, headless knowledge and
content engine. Its intent covers persistent knowledge artifacts, collections,
relationships, ingestion, workflow state, query, service access, and agent-
operable knowledge processes.

The projects overlap around durable state, graph-shaped records, context
packages, provenance, and agent operation. They must stay separated by purpose.

## Ownership Boundary

`kontextual-engine` owns:

- Persistent knowledge collections, artifacts, relationships, and revisions.
- Content identity, artifact metadata, source provenance, and lifecycle state.
- Durable workflow run records and operation manifests.
- Query and retrieval over knowledge artifacts and relationships.
- Service and programmatic APIs for operating knowledge systems.
- Adapter surfaces that can call `markitect-tool`, `phase-memory`, storage
  backends, and future workflow engines.

`phase-memory` owns:

- Ephemeral, fluid, stabilized, and rigid memory phase semantics.
- Reasoning graphs, conversational paths, activation memory, identity memory,
  preference memory, and reviewed memory records.
- Memory profiles with latency, token, byte, retention, decay, compaction,
  freshness, merge, conflict, and policy parameters.
- Memory-specific lifecycle enforcement, including retention, deletion,
  stabilization, compaction, and summarization.
- Memory retrieval planning and activation-package compilation.
- Adapters to graph databases, vector stores, audit sinks, policy systems, and
  memory-specific backend infrastructure.

## Interop Boundary

`kontextual-engine` may persist memory-related artifacts when they are treated
as knowledge assets, such as:

- reviewed decisions,
- source-backed facts,
- durable project context packages,
- workflow outputs,
- policy-visible provenance records,
- exported memory graph slices.

It should not implement memory-specific behavior such as:

- conversational path branching and merge semantics,
- memory decay and retention policy execution,
- compaction or summarization strategies,
- activation planning heuristics,
- preference or identity memory governance,
- graph/vector memory backend selection,
- memory service profile validation.

Those behaviors belong to `phase-memory`. `kontextual-engine` should integrate
with them through explicit adapters and stable exchange formats.

## Persistence Implication

The persistence gap in `kontextual-engine` should be closed as durable knowledge
runtime storage, not as a general memory runtime.

The first durable backend should persist:

- collections,
- artifacts,
- artifact revisions,
- relationships,
- workflow runs,
- run manifests,
- change records,
- queryable metadata,
- context-package references.

It should not persist phase-memory internals beyond opaque references or
exported artifacts unless an integration adapter explicitly maps them.

## Integration Shape

The preferred integration shape is:

1. Core `kontextual-engine` repository contracts remain independent.
2. A future `phase-memory` adapter can read/write durable knowledge artifacts
   through those contracts.
3. Context packages can move between the systems as inspectable payloads.
4. Memory-specific policies stay in `phase-memory`; knowledge persistence
   policy stays in `kontextual-engine`.
5. Cross-repo references should use stable identifiers, content digests, and
   provenance metadata rather than implicit filesystem coupling.

This keeps `kontextual-engine` focused on persistent, operable knowledge while
leaving sophisticated agentic memory behavior to the project designed for it.