System boundry and persistance workplan

docs/phase-memory-boundary.md

@@ -0,0 +1,107 @@
+# 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.